Agentuity Docs

This guide walks you through building a chat agent from scratch using OpenAI.

Default Template

When you create a project with agentuity create, you get a translation agent demonstrating:

AI Gateway: OpenAI SDK routed through Agentuity (unified billing, no separate API keys)
Thread state: Persistent translation history across requests
Structured logging: Observability via ctx.logger
Tailwind CSS: Pre-configured styling
Workbench: Local testing UI at /workbench

New to AI Agents?

Learn how agents use tools and run in loops to complete tasks autonomously.

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. Run Your Agent

Start the dev server:

agentuity dev
# or: bun run dev

Test your agent 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. Test Locally with Workbench

Workbench is a built-in UI for testing agents directly, without going through your frontend. Enable it by adding a workbench section to your agentuity.config.ts:

import type { AgentuityConfig } from '@agentuity/cli';
 
export default {
  workbench: {
    route: '/workbench',
  },
} satisfies AgentuityConfig;

Open http://localhost:3500/workbench to test your agents with raw JSON input. See Testing with Workbench for adding test prompts and configuration options.

5. Add a Frontend

Add a React UI in src/web/ to call your agent. Here's a simple example:

import { useAPI } from '@agentuity/react';
import { useState } from 'react';
 
export function App() {
  const [message, setMessage] = useState('');
  const { data, invoke, isLoading } = useAPI('POST /api/chat');
 
  return (
    <div>
      <input
        value={message}
        onChange={(e) => setMessage(e.target.value)}
        placeholder="Ask something..."
        disabled={isLoading}
      />
      <button onClick={() => invoke({ message })} disabled={isLoading}>
        {isLoading ? 'Thinking...' : 'Send'}
      </button>
      {data && <p>{data.response}</p>}
    </div>
  );
}

The useAPI hook provides type-safe access to your routes. It infers types from your agent's schema, so data.response is fully typed.

6. 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 stream() middleware:

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

7. Deploy

When you're ready, deploy to Agentuity:

agentuity deploy
# or: bun run deploy

Your agent is now live with a public URL. View deployments, logs, and more in the App.

What You'll See in the App

After your first deployment, the App populates with:

Agents: Your deployed agents with their endpoints
Routes: Registered HTTP, cron, and other routes
Sessions: Request history and logs as traffic flows
Deployments: Version history with rollback options

What's Next?

Learn the concepts:

Understanding How Agents Work: Tools, loops, and autonomous behavior

Build something more:

Build a multi-agent system: Routing, RAG, workflows
Persist data: Use thread and session state
Explore React Hooks: WebSocket, SSE, and more patterns

Understand the platform:

Project Structure: Agents, routes, and frontend
App Configuration: Configure your project
Local Development: Dev server, hot reload, and debugging

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