Use Sub-Agents

Delegate focused tasks to specialized AI agents with their own system prompts, tool restrictions, and model selection.

Create a sub-agent

Sub-agents are Markdown files with YAML frontmatter stored in .proto/agents/ (project) or ~/.proto/agents/ (global).

mkdir -p .proto/agents

Create .proto/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for quality, security, and maintainability. Use proactively when changes are ready for review.
tools:
  - read_file
  - grep_search
  - glob
---
 
You are an experienced code reviewer. For each file you review:
 
1. Check for security vulnerabilities
2. Identify performance issues
3. Note maintainability concerns
 
Cite the exact file path and line number for each finding.

Use the agent

Ask naturally — proto delegates based on the description field:

Review the authentication module for security issues

Or invoke explicitly:

Use the code-reviewer agent to check my recent changes

Configuration reference

Frontmatter fields

Tool restrictions

Allowlist (tools) — only these tools are available:

tools:
  - read_file
  - grep_search
  - glob

Denylist (disallowedTools) — remove from the inherited set:

disallowedTools:
  - write_file
  - edit

Permission modes

Storage hierarchy

Built-in agents

Multi-sample retry

For high-stakes tasks where failure is costly:

{
  "subagent_type": "general-purpose",
  "multi_sample": true,
  "prompt": "..."
}

The harness retries up to 2 more times with escalating temperatures, scoring each attempt and returning the best result. See Explanation → Agent Harness for the scoring reference.

Behavior verification gate

Run automatic post-task verification by creating .proto/verify-scenarios.json:

[
  {
    "name": "Unit tests pass",
    "command": "npm test -- --run",
    "timeoutMs": 60000
  },
  {
    "name": "Build succeeds",
    "command": "npm run build",
    "timeoutMs": 30000
  }
]

Scenarios run in parallel after each successful subagent completion. If any fail, the output is fed back to the agent for self-correction.

Background execution

Agents can run concurrently using run_in_background: true in the Agent tool call. The coordinator agent uses this to delegate subtasks in parallel.

Agent teams

Teams run multiple coordinated agents concurrently. Each member is a live in-process agent with its own system prompt and tools, plus two extras injected automatically: mailbox_send and mailbox_receive for direct peer-to-peer messaging.

/team start research researcher:Explore implementer:general-purpose

Default team (no members specified): lead (coordinator) + scout (Explore).

Team commands

Shared task list

All team members share the same task list. Members can create, claim, and update tasks using the standard task tools (task_create, task_list, task_update).

Inter-agent messaging

Each agent gets mailbox_send and mailbox_receive tools at spawn time. Agents address each other by agentId (<name>-<index>, e.g. lead-0, scout-1).

See Guides → Use Agent Teams for the full reference including message patterns, status tracking, hooks integration, and implementation details.

Management commands

Design guidelines

Single responsibility — one agent, one purpose. Split “testing and documentation” into two agents.

Actionable descriptions — write the description so proto knows exactly when to delegate:

description: Reviews code for security vulnerabilities, performance issues, and maintainability. Use after implementing any change.

Minimal tool access — grant only what the agent needs.

SDK usage

When using the TypeScript SDK, pass subagent configs via the agents option:

import { query, type SubagentConfig } from '@protolabsai/sdk';
 
const reviewer: SubagentConfig = {
  name: 'code-reviewer',
  description:
    'Reviews code for bugs, security issues, and performance problems',
  systemPrompt: 'You are a code reviewer...',
  level: 'session',
  tools: ['read_file', 'glob', 'grep_search'],
  modelConfig: { model: 'claude-sonnet-4-6' },
};
 
const conversation = query({
  prompt: 'Review the changes in the current branch',
  options: { agents: [reviewer] },
});

See Contributing → Examples → SDK Sub-Agents for more patterns.