# Quickstart

Build your first agent in 5 minutes

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

> [!NOTE]
> **Default Template**
> When you create a project with `agentuity project 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

- [New to AI Agents?](/cookbook/tutorials/understanding-agents): Learn how agents use tools and run in loops to complete tasks autonomously.

## 1. Create the Agent

Create `src/agent/chat/agent.ts`:

```typescript
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;
```

## 2. Register the Agent

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

```typescript
import chat from './chat/agent';

export default [chat];
```

## 3. Add a Route

Create `src/api/index.ts`:

```typescript
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`:

```typescript
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,
});
```

## 4. Run Your Agent

Start the dev server:

```bash
agentuity dev
# or: bun run dev
```

Test your agent via curl:

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

Response:

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

## 5. Add a Frontend

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

```tsx
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.

## 6. Add Streaming

For real-time responses, return a stream instead:

```typescript
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.4-nano'),
      prompt: input.message,
    });

    return textStream;
  },
});

export default agent;
```

Update the route to return the agent stream:

```typescript
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;
```

## 7. Deploy

When you're ready, deploy to Agentuity:

```bash
agentuity deploy
# or: bun run deploy
```

Your agent is now live with a public URL. View deployments, logs, and more in the [Web App](https://app.agentuity.com).

> [!NOTE]
> **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, streaming, and other routes
> - **Sessions**: Request history and logs as traffic flows
> - **Deployments**: Version history with rollback options

## What's Next?

> [!TIP]
> **AI-Assisted Development**
> Install the [OpenCode plugin](/reference/cli/opencode-plugin) for AI-assisted agent development. Get help writing agents, debugging, and deploying directly from your editor:
>
> ```bash
> agentuity ai opencode install
> ```

**Learn the concepts:**

- [Understanding How Agents Work](/cookbook/tutorials/understanding-agents): Tools, loops, and autonomous behavior

**Build something more:**

- [Build a multi-agent system](/agents/calling-other-agents): Routing, RAG, workflows
- [Persist data](/agents/state-management): Use thread and session state
- [RPC Client](/frontend/rpc-client): Type-safe `hc()` patterns for browser and server code

**Understand the platform:**

- [Project Structure](/get-started/project-structure): Agents, routes, and frontend
- [App Configuration](/get-started/app-configuration): Configure your project
- [Local Development](/reference/cli/development): Dev server, hot reload, and debugging