Filesystem Agents

<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 283 64">
  <path fill="currentColor" d="M141.04 16c-11.04 0-19 7.2-19 18s8.96 18 20 18c6.67 0 12.55-2.64 16.19-7.09l-7.65-4.42c-2.02 2.21-5.09 3.51-8.54 3.51-4.79 0-8.86-2.5-10.37-6.5h28.02c.22-1.12.35-2.28.35-3.5 0-10.79-7.96-18-19-18Zm-9.46 14.5c1.25-3.99 4.67-6.5 9.45-6.5 4.79 0 8.21 2.51 9.45 6.5h-18.9ZM248.72 16c-11.04 0-19 7.2-19 18s8.96 18 20 18c6.67 0 12.55-2.64 16.19-7.09l-7.65-4.42c-2.02 2.21-5.09 3.51-8.54 3.51-4.79 0-8.86-2.5-10.37-6.5h28.02c.22-1.12.35-2.28.35-3.5 0-10.79-7.96-18-19-18Zm-9.45 14.5c1.25-3.99 4.67-6.5 9.45-6.5 4.79 0 8.21 2.51 9.45 6.5h-18.9ZM36.95 0 73.9 64H0L36.95 0Zm92.28 0-6.2 10.78L106 34l20.96 30h13.06L126.8 44.43l6.62-10.71L146.3 0h-17.07ZM85.41 0v64h14.84V0H85.41Zm162 0v64h14.84V0h-14.84Zm-73.71 16c-6.62 0-11.73 2.8-14.53 7.04V16.6h-14.09V64h14.84V37.02c0-6.3 4.2-11.07 10.16-11.07 5.96 0 9.63 4.77 9.63 11.07V64h14.84V34.41c0-11.73-8.33-18.41-20.85-18.41Zm86.62 0c-6.62 0-11.73 2.8-14.53 7.04V16.6h-14.09V64h14.84V37.02c0-6.3 4.2-11.07 10.16-11.07 5.96 0 9.63 4.77 9.63 11.07V64h14.84V34.41c0-11.73-8.33-18.41-20.85-18.41Z"/>
</svg>


# AI SDK Agent Patterns

Reference for the AI SDK components used in filesystem agents.

## ToolLoopAgent

The core agent class. It takes a model, instructions, and tools, then runs a loop: the model decides which tool to call, the tool executes, the result goes back to the model, and the loop repeats until the model has enough information to respond.

```typescript
import { ToolLoopAgent } from 'ai';

export const agent = new ToolLoopAgent({
  model: 'anthropic/claude-opus-4.6',
  instructions: 'You are a helpful assistant...',
  tools: {
    bashTool: createBashTool(sandbox)
  }
});
```

### Properties

| Property | Type | Purpose |
|----------|------|---------|
| `model` | `string` | Model identifier. Use AI Gateway format: `provider/model-name` |
| `instructions` | `string` | System prompt. Defines the agent's role, available tools, data layout, and strategy |
| `tools` | `Record<string, Tool>` | Named map of tools the agent can call. Keys become the tool names the LLM sees |

### Streaming

The agent streams responses through the API route:

```typescript
// app/api/route.ts
const stream = await agent.stream({ prompt });
writer.merge(stream.toUIMessageStream());
```

`agent.stream()` returns a stream that includes both tool calls and text responses. `toUIMessageStream()` converts it to the format the `useChat` hook expects on the client.

### Model Configuration

AI Gateway routes to any provider through a single API key:

```typescript
// These all work — just change the string
const MODEL = 'anthropic/claude-opus-4.6';
const MODEL = 'anthropic/claude-sonnet-4.6';
const MODEL = 'openai/gpt-4o';
const MODEL = 'google/gemini-2.5-pro';
```

Set `AI_GATEWAY_API_KEY` in `.env.local`. On Vercel, OIDC authentication handles this automatically.

## tool()

Defines a single tool the agent can call.

```typescript
import { tool } from 'ai';
import { z } from 'zod';

const myTool = tool({
  description: 'What this tool does — the LLM reads this to decide when to use it',
  inputSchema: z.object({
    param1: z.string().describe('What to put here'),
    param2: z.number().describe('What this number means')
  }),
  execute: async ({ param1, param2 }) => {
    // Do work, return result
    return { result: 'done' };
  }
});
```

### Three Parts

1. **description** — When should the LLM use this tool? Be specific. "Execute bash commands to explore transcript and instruction files" is better than "Run commands."

2. **inputSchema** — Zod schema. Every field needs `.describe()` — this is the tool's documentation for the LLM. Without it, the model guesses what to put in each field.

3. **execute** — Async function that receives validated inputs and returns a result. The return value goes back to the model as the tool call result.

### Factory Pattern

Tools that need external dependencies (sandbox, database, API c