> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.thatdevguy.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Anvil JS Agent Routes: Build Streaming AI Agents

> Build streaming AI agents in Anvil JS. Drop an agent.ts into any route folder and Anvil streams responses using the Vercel AI SDK data protocol.

Agent routes are the agentic core of Anvil JS. Place an `agent.ts` file inside any folder under `server/routes/` and Anvil automatically mounts it as a `POST` endpoint that streams the [Vercel AI SDK data stream protocol](https://sdk.vercel.ai/docs/ai-sdk-ui/stream-protocol). Because the wire format is compatible, you can point `useChat` directly at an agent route with no extra adapter code.

## How an agent route works

An `agent.ts` file exports a handler built with `defineAgent`. When a request arrives, the runtime:

1. Extracts the `messages` array from the JSON request body (AI SDK `useChat` shape by default).
2. Runs the **model↔tool loop** — calls the model, executes any tools the model requests, feeds results back, and repeats.
3. Streams each text token, tool call, and tool result back to the client as data stream parts.
4. Emits a final summary event with token usage and cost once the model produces a response with no tool calls (or the iteration cap is reached).

The runtime enforces several safety properties automatically:

* **Iteration cap** — `maxIterations` (default `10`) prevents the loop from running forever on a runaway tool-calling sequence.
* **AbortSignal propagation** — when the HTTP client disconnects, the cancellation signal flows into every model call and tool execution. Partial work is stopped immediately.
* **Zod schema validation** — each tool's `zodSchema` is checked before `execute` runs. Invalid inputs return an error result to the model rather than crashing the handler.
* **Token tracking** — input and output tokens are accumulated across every turn and reported in the `final` event.

## File conventions

```text theme={null}
server/routes/
  chat/
    agent.ts          → POST /chat  (agent route)
  summarize/
    post.ts           → POST /summarize (also works with defineAgent)
```

Both `agent.ts` and `post.ts` work. Use `agent.ts` as the conventional name for routes whose primary purpose is running an agent loop.

## Connecting a frontend

Because Anvil streams the Vercel AI SDK data stream protocol, `useChat` works out of the box:

```tsx theme={null}
import { useChat } from 'ai/react';

export function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: '/chat',
    streamProtocol: 'data',
  });

  return (
    <form onSubmit={handleSubmit}>
      {messages.map((m) => (
        <p key={m.id}><strong>{m.role}:</strong> {m.content}</p>
      ))}
      <input value={input} onChange={handleInputChange} />
      <button type="submit">Send</button>
    </form>
  );
}
```

<Note>
  `streamProtocol: 'data'` is required. Anvil uses the prefix-coded data stream format, not raw text streaming.
</Note>

## What's in this section

<CardGroup cols={2}>
  <Card title="Define Agent" icon="code" href="/agents/define-agent">
    The `defineAgent` API — system prompts, tools, context pipelines, budgets, and the `withLlm` middleware.
  </Card>

  <Card title="LLM Client" icon="microchip" href="/agents/llm-client">
    `LlmClient` and its drivers for Anthropic, OpenAI, and Gemini — plus fallback chains and structured output.
  </Card>

  <Card title="Agent Tools" icon="wrench" href="/agents/tools">
    The `AgentTool` interface — Zod schemas, side-effect fencing, and the `maxIterations` safeguard.
  </Card>

  <Card title="Orchestration" icon="sitemap" href="/agents/orchestration">
    `AgentRegistry`, `agentAsTool`, and `withAgents` — compose multi-agent systems without HTTP round-trips.
  </Card>
</CardGroup>