Quickstart — Agentuity Documentation

Quickstart

Build your first agent in 5 minutes

Start from a new Agentuity project and replace the default translation example with a small chat agent using OpenAI.

New to AI Agents?
Learn how agents use tools and run in loops to complete tasks autonomously.

1. Add Chat Dependencies

The default template includes the OpenAI SDK. This quickstart uses Vercel AI SDK helpers, so add them before replacing the default agent:

bun add ai @ai-sdk/openai

2. 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.4-nano'),
      prompt: input.message,
    });
 
    return { response: text };
  },
});
 
export default agent;

3. Register the Agent

Add the agent to the registry in src/agent/index.ts:

import chat from './chat/agent';
 
export default [chat];

4. Add a Route

Create src/api/index.ts:

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

Wire the route and your agent into the project-root app.ts:

import { createApp } from '@agentuity/runtime';
import api from './src/api/index';
import agents from './src/agent';
 
export default await createApp({
  router: { path: '/api', router: api },
  agents,
});

5. 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."
}

6. Add a Frontend

Add a React UI in src/web/ to call your agent. Use Hono's hc() client for type-safe API calls:

import { hc } from 'hono/client';
import type { ApiRouter } from '../api';
import { useState } from 'react';
 
const client = hc<ApiRouter>('/api');
 
export function App() {
  const [message, setMessage] = useState('');
  const [response, setResponse] = useState('');
  const [isLoading, setIsLoading] = useState(false);
 
  const handleSend = async () => {
    setIsLoading(true);
    try {
      const res = await client.chat.$post({ json: { message } });
      const data = await res.json();
      setResponse(data.response);
    } finally {
      setIsLoading(false);
    }
  };
 
  return (
    <div>
      <input
        value={message}
        onChange={(e) => setMessage(e.target.value)}
        placeholder="Ask something..."
        disabled={isLoading}
      />
      <button onClick={handleSend} disabled={isLoading}>
        {isLoading ? 'Thinking...' : 'Send'}
      </button>
      {response && <p>{response}</p>}
    </div>
  );
}

The hc() client infers types from your router, so data.response is fully typed.

7. 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) => {
    ctx.logger.info('Streaming chat response');
 
    const { textStream } = streamText({
      model: openai('gpt-5.4-nano'),
      prompt: input.message,
    });
 
    return textStream;
  },
});
 
export default agent;

Update the route to return the agent stream:

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

8. Deploy

When the project is ready, deploy to Agentuity:

agentuity deploy
# or: bun run deploy

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

What's Next?

Learn the concepts:

Build something more:

Understand the platform: