Agentuity Docs

This guide walks you through creating a simple chat agent that uses OpenAI to generate responses.

1. Create the Agent

Create src/agent/chat/agent.ts:

import { createAgent } from '@agentuity/runtime';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { s } from '@agentuity/schema';
 
const agent = createAgent('Chat', {
  schema: {
    input: s.object({ message: s.string() }),
    output: s.object({ response: s.string() }),
  },
  handler: async (ctx, input) => {
    ctx.logger.info('Received message', { message: input.message });
 
    const { text } = await generateText({
      model: openai('gpt-5-mini'),
      prompt: input.message,
    });
 
    return { response: text };
  },
});
 
export default agent;

2. Add a Route

Create src/api/index.ts:

import { createRouter } from '@agentuity/runtime';
import chat from '@agent/chat';
 
const router = createRouter();
 
router.post('/chat', chat.validator(), async (c) => {
  const data = c.req.valid('json');
  const result = await chat.run(data);
  return c.json(result);
});
 
export default router;

3. Test It

Start the dev server:

agentuity dev

Open http://localhost:3500 in your browser. The default template includes a UI where you can test your agents directly.

You can also test via curl:

curl -X POST http://localhost:3500/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the capital of France?"}'

Response:

{
  "response": "The capital of France is Paris."
}

4. Add Streaming

For real-time responses, return a stream instead:

import { createAgent } from '@agentuity/runtime';
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { s } from '@agentuity/schema';
 
const agent = createAgent('Chat', {
  schema: {
    input: s.object({ message: s.string() }),
    stream: true,
  },
  handler: async (ctx, input) => {
    const { textStream } = streamText({
      model: openai('gpt-5-mini'),
      prompt: input.message,
    });
 
    return textStream;
  },
});
 
export default agent;

Update the route to use the streaming endpoint:

import { createRouter } from '@agentuity/runtime';
import chat from '@agent/chat';
 
const router = createRouter();
 
router.stream('/chat', async (c) => {
  const body = await c.req.json();
  return chat.run(body);
});
 
export default router;

5. Deploy

When you're ready, deploy to Agentuity:

agentuity deploy

Your agent is now live with a public URL.

What's Next?

Build something more:

Build a multi-agent system: Routing, RAG, workflows
Add a React frontend: Call your agent from the web
Persist data: Use thread and session state

Understand the platform:

Project Structure: The two-file pattern
App Configuration: Configure your project

Need Help?

Join our Community for assistance or just to hang with other humans building agents.

Send us an email at hi@agentuity.com if you'd like to get in touch.

Please Follow us on

If you haven't already, please Signup for your free account now and start building your first agent!

Quickstart