---
title: 'Agent Reference'
section: 'advanced'
tags: ['customization', 'agent templates', 'agents', 'reference']
order: 4
---

# Agent Reference

<AgentDefinitionDisplay />

### Core Configuration

#### `id` (string, required)

Unique identifier for this agent. Must contain only lowercase letters, numbers, and hyphens.

```json
"id": "code-reviewer"
```

#### `displayName` (string, required)

Human-readable name for the agent.

```json
"displayName": "Code Review Specialist"
```

#### `spawnerPrompt` (string, optional)

Tells other agents when to spawn this one.

```json
"spawnerPrompt": "Spawn this agent for thorough code review, focusing on bugs, security issues, and best practices"
```

### Model Configuration

#### `model` (string, required)

The model to use, which can be any model string from [Openrouter](https://openrouter.ai/models).

```json
"model": "anthropic/claude-sonnet-4.5"
```

#### Reasoning Options (`reasoningOptions`, object, optional)

Controls model reasoning behavior using OpenRouter-style settings.

Fields:

- `enabled` (boolean, default: false) — Turn reasoning mode on for supported models.
- `exclude` (boolean, default: false) — If true, omit model-revealed reasoning content from responses (when available), returning only the final answer.
- `effort` ("low" | "medium" | "high") — How much the model thinks before answering. Higher = better for hard tasks, more tokens.

Only works on models that support reasoning. Ignored otherwise.

Example:

```ts
// .agents/thinker.ts
const definition = {
  id: 'thinker',
  // ... other fields ...
  reasoningOptions: {
    enabled: true,
    exclude: false,
    effort: 'high',
  },
}
```

### Behavior Configuration

#### `outputMode` (string, optional, default: "last_message")

How the agent's output is handled.

**Options:**

- `"last_message"` - Return only the final message (default)
- `"all_messages"` - Return all messages from the conversation
- `"structured_output"` - Return a structured JSON object (use with `outputSchema`)

```json
"outputMode": "last_message"
```

#### `includeMessageHistory` (boolean, optional, default: false)

Whether to include conversation history from the parent agent when spawning this agent.

```json
"includeMessageHistory": true
```

#### `outputSchema` (object, optional)

JSON Schema for structured output (when `outputMode` is `"structured_output"`).

```json
"outputMode": "structured_output",
"outputSchema": {
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "issues": {
      "type": "array",
      "items": { "type": "string" }
    },
    "score": { "type": "number" }
  },
  "required": ["summary", "issues"]
}
```

### Tools and Capabilities

#### `toolNames` (array, optional, default: ["end_turn"])

List of tools the agent can use.

**Available Tools:**

- `add_subgoal` - Create subgoals for tracking progress
- `browser_logs` - Navigate web pages and get console logs
- `code_search` - Search for patterns in code files
- `create_plan` - Generate detailed plans for complex tasks
- `end_turn` - End the agent's turn
- `find_files` - Find relevant files in the codebase
- `read_docs` - Read documentation for libraries
- `read_files` - Read file contents
- `run_file_change_hooks` - Run configured file change hooks
- `run_terminal_command` - Execute terminal commands
- `spawn_agents` - Spawn other agents
- `str_replace` - Replace strings in files
- `think_deeply` - Perform deep analysis
- `update_subgoal` - Update existing subgoals
- `web_search` - Search the web
- `write_file` - Create or edit files
- `set_output` - Set an output JSON object

```json
"toolNames": ["read_files", "write_file", "code_search", "end_turn"]
```

#### `spawnableAgents` (array, optional, default: [])

Other agents this agent can spawn. Use the fully qualified agent ID from the agent store (publisher/name@version) or the agent ID from a local agent file.

> **⚠️ Important:** When referencing built-in agents, you **must** specify both publisher and version (e.g., `codebuff/reviewer@0.0.1`). Omit publisher/version only for local agents defined in your `.agents/` directory.

**Referencing Agents:**

- Published/built-in agents: `"codebuff/file-picker@0.0.1"` (publisher and version required!)
- Local agents: `"my-custom-agent"` (just the agent ID)

**Available Built-in Agents:**

- [`codebuff/base`](/publishers/codebuff/agents/base) - Main coding assistant
- [`codebuff/reviewer`](/publishers/codebuff/agents/reviewer) - Code review agent
- [`codebuff/thinker`](/publishers/codebuff/agents/thinker) - Deep thinking agent
- [`codebuff/researcher`](/publishers/codebuff/agents/researcher) - Research and documentation agent
- [`codebuff/planner`](/publishers/codebuff/agents/planner) - Planning and architecture agent
- [`codebuff/file-picker`](/publishers/codebuff/agents/file-picker) - File discovery agent

```json
"spawnableAgents": ["codebuff/researcher@0.0.1", "my-local-agent"]
```

### Prompt Configuration

All prompt fields support two formats:

1. **Direct string content:**

```json
"systemPrompt": "You are a helpful assistant..."
```

2. **External file reference:**

```json
"systemPrompt": {
  "path": "./my-system-prompt.md"
}
```

#### Prompt Fields (all optional)

#### `systemPrompt` (string or object, optional)

Background information. Usually `instructionsPrompt` is better.

#### `instructionsPrompt` (string or object, optional)

Instructions inserted after each user input. Best way to shape behavior.

#### `stepPrompt` (string or object, optional)

Inserted at each agent step.

### Programmatic Control

#### `handleSteps` (generator function, optional)

Generator function for programmatic control over tool calls and LLM steps.

<MarkdownTable>
| Yield Value | What It Does |
| --- | --- |
| Tool call object | Execute a tool and get its result |
| 'STEP' | Run one LLM generation step |
| 'STEP_ALL' | Let the agent run until completion |
| return | End the agent's turn immediately |
</MarkdownTable>

**Tool Call Pattern:**

```typescript
const { toolResult, toolError } = yield {
  toolName: 'read_files',
  input: { paths: ['file.ts'] },
}
// use toolResult or handle toolError
```

**Example:**

```typescript
handleSteps: function* ({ prompt }) {
  const { toolResult } = yield {
    toolName: 'read_files',
    input: { paths: ['src/index.ts', 'src/config.ts'] },
  }

  yield {
    toolName: 'spawn_agents',
    input: {
      agents: [{ agent_type: 'thinker', prompt: 'Analyze this code structure' }],
    },
  }

  yield 'STEP_ALL'
}
```

### Schema Validation

#### `inputSchema` (object, optional)

JSON Schema for validating prompt and params when spawning the agent.

```json
{
  "prompt": {
    "type": "string",
    "description": "What documentation to create"
  },
  "params": {
    "type": "object",
    "properties": {
      "format": {
        "type": "string",
        "enum": ["markdown", "html"]
      }
    }
  }
}
```

**Example combining tools**

```typescript
  const { toolResult: searchResults } = yield {
    toolName: 'code_search',
    input: { pattern: params.searchPattern || 'TODO' },
  }

  const files = JSON.parse(searchResults || '[]').slice(0, 10)
  if (files.length) {
    yield { toolName: 'read_files', input: { paths: files } }
  }

  if (files.some((file) => file.includes('security'))) {
    yield {
      toolName: 'spawn_agents',
      input: {
        agents: [
          {
            agent_type: 'security-reviewer',
            prompt: `Review security implications in: ${files.join(', ')}`,
          },
        ],
      },
    }
  }

  yield 'STEP_ALL'
```

### Agent Example

**.agents/documentation-writer.ts**

```typescript
import { AgentDefinition } from './types/agent-definition'

const definition: AgentDefinition = {
  id: "documentation-writer",
  version: "1.0.0",
  publisher: "mycompany",

  displayName: "Documentation Writer",
  spawnerPrompt: "Spawn this agent for writing documentation, API docs, or user guides",
  model: "anthropic/claude-sonnet-4.5",
  outputMode: "last_message",
  includeMessageHistory: true,

  toolNames: [
    "read_files",
    "write_file",
    "code_search",
    "spawn_agents",
    "end_turn"
  ],
  spawnableAgents: ["codebuff/researcher@0.0.1"],

  inputSchema: {
    prompt: {
      type: "string",
      description: "What documentation to create or update"
    }
  },

  systemPrompt: {
    path: "./prompts/doc-writer-system.md"
  },
  instructionsPrompt: "Create documentation based on the user's request. Research existing code first.",
  stepPrompt: "Continue working on the documentation. Use end_turn when complete."
}

export default definition
```
