---
title: 'Customizing Agents'
section: 'advanced'
tags: ['customization', 'agent templates', 'agents']
order: 1
---

# Customizing Agents

Create agents with TypeScript files in the `.agents/` directory:

```markdown
.agents/
├── my-custom-agent.ts
├── security-coordinator.ts
└── types/
└── agent-definition.ts
```

### Domain-Specific Customization

Design agents to manage context flow: orchestrate steps so the right files and facts stay in scope, instead of trying to mimic job titles.

**Tip:** Use specialty reviewers as spawnable subagents that your context-manager agent calls at the right time in the workflow.

### Reasoning Options (optional)

For models that support it, you can enable and tune reasoning directly on your agent:

```ts
const definition = {
  id: 'reviewer',
  // ... other fields ...
  reasoningOptions: {
    enabled: true, // turn on reasoning if supported
    exclude: false, // include reasoning traces when available
    effort: 'medium', // low | medium | high
  },
}
```

- Effort roughly corresponds to a larger internal "max tokens for reasoning."
- If the selected model doesn't support reasoning, these options are safely ignored.

## Example: Security Coordinator Agent

This example uses [`reviewer`](/publishers/codebuff/agents/reviewer), [`researcher`](/publishers/codebuff/agents/researcher), and [`file-picker`](/publishers/codebuff/agents/file-picker) as spawnable subagents:

**.agents/security-coordinator.ts**

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

const definition: AgentDefinition = {
  id: 'security-coordinator',
  version: '1.0.0',

  displayName: 'Security Coordinator',
  spawnerPrompt:
    'Spawn this agent to coordinate security-focused development workflows',
  model: 'anthropic/claude-sonnet-4.5',
  outputMode: 'last_message',
  includeMessageHistory: true,

  toolNames: ['read_files', 'spawn_agents', 'code_search', 'end_turn'],
  spawnableAgents: [
    'codebuff/reviewer@0.0.1',
    'codebuff/researcher@0.0.1',
    'codebuff/file-picker@0.0.1',
  ],

  inputSchema: {
    prompt: {
      type: 'string',
      description: 'Security analysis or coordination task',
    },
  },

  systemPrompt:
    'You are a security coordinator responsible for secure development practices.',
  instructionsPrompt:
    'Analyze the security implications of the request and coordinate security-focused agents.',
  stepPrompt:
    'Continue analyzing security requirements and coordinating the workflow. Use end_turn when complete.',
}

export default definition
```

## Adding Programmatic Control

```typescript
const definition: AgentDefinition = {
  id: 'security-coordinator',
  // ... other fields ...

  handleSteps: function* ({ prompt, params }) {
    // 1. Scan for security vulnerabilities
    const { toolResult: scanResults } = yield {
      toolName: 'code_search',
      input: {
        pattern: '(eval|exec|dangerouslySetInnerHTML|process\.env)',
        flags: '-i',
      },
    }

    // 2. If vulnerabilities found, spawn security reviewer
    if (scanResults) {
      yield {
        toolName: 'spawn_agents',
        input: {
          agents: [
            {
              agent_type: 'security-reviewer',
              prompt: `Review these potential security issues: ${scanResults}`,
            },
          ],
        },
      }
    }

    // 3. Let the agent handle the rest
    yield 'STEP_ALL'
  },
}
```

With `handleSteps`, your agent can:

- Make decisions from tool output
- Orchestrate tools in sequence
- Handle errors
- Run conditional logic

## Available Fields

**Core:**

- `id`
- `displayName`
- `model`
- `version`
- `publisher`

**Tools:**

- `toolNames`
- `spawnableAgents`

**Prompts:**

- `spawnerPrompt`
- `systemPrompt`
- `instructionsPrompt`
- `stepPrompt`

**Input/Output:**

- `inputSchema`
- `outputMode`
- `outputSchema`
- `includeMessageHistory`

**Programmatic:**

- `handleSteps`

## Troubleshooting

**Agent not loading:** Check TypeScript syntax, file must export default AgentDefinition

**Type errors:** Import types from `'./types/agent-definition'`

**Prompts not applying:** Verify file paths are relative to `.agents/` directory

**Running specific agents:**

1. Check TypeScript: `bun run typecheck` in `.agents/` directory
2. Restart Codebuff to see errors
3. Test with `--agent <agent-id>` to debug specific agents
