Claude Code agents provide AgentPool's native integration with the Claude Agent SDK, enabling file operations, terminal access, and advanced code editing capabilities through Claude's official tooling.

Overview¶

While Claude Code can be used via the ACP bridge, AgentPool provides its own complete integration using the Claude Agent SDK directly. This approach offers several advantages:

• Lower latency: No ACP protocol overhead between AgentPool and Claude Code
• Tighter integration: Direct access to Claude Code's streaming, tools, and events
• Toolset bridging: Expose AgentPool's internal toolsets to Claude Code via MCP
• Better error handling: Native exception propagation and recovery
• Structured outputs: Full support for typed response schemas

Claude Code agents are ideal for:

• Complex coding tasks requiring file system access
• Terminal operations and shell command execution
• Multi-file refactoring and code generation
• Tasks benefiting from Claude's extended thinking

Configuration Reference¶

claude_code_agents:
  coder:
    cwd: /path/to/project
    model: claude-sonnet-4-5
    allowed_tools:
      - Read
      - Write
      - Bash
    system_prompt: "You are a helpful coding assistant."
    max_turns: 10

  planner:
    cwd: /path/to/project
    permission_mode: plan
    max_thinking_tokens: 10000
    include_builtin_system_prompt: false
    system_prompt:
      - "You are a planning-only assistant."
      - "Focus on architecture decisions."

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

type: claude_code  # Top-level discriminator for agent type.
cwd: null  # Working directory for Claude Code operations.
model: null  # Model to use for this agent. Defaults to Claude's default model.
allowed_tools: null  # List of tool names the agent is allowed to use.
disallowed_tools: null  # List of tool names the agent is NOT allowed to use.
system_prompt: null  # System prompt for the agent. Can be a string or list of strings/prompt configs.
include_builtin_system_prompt: true  # Whether to include Claude Code's builtin system prompt.
max_turns: null  # Maximum number of conversation turns before stopping.
max_budget_usd: null  # Maximum budget in USD before stopping.
max_thinking_tokens: null  # Maximum tokens for extended thinking mode.
permission_mode: null  # Permission handling mode:
output_type: null  # Optional structured output type for responses.
env: null  # Environment variables to set for the agent process.
add_dir: null  # Additional directories to allow tool access to.
builtin_tools: null  # Available tools from Claude Code's built-in set.
fallback_model: null  # Fallback model when default is overloaded.
dangerously_skip_permissions: false  # Bypass all permission checks. Only for sandboxed environments.
setting_sources: null  # Setting sources to load configuration from.
use_subscription: false  # Force usage of Claude subscription instead of API key.
tools: []  # Tools and toolsets to expose to this Claude Code agent via MCP bridge.
requires_tool_confirmation: per_tool  # How to handle tool confirmation:
name: null  # Identifier for the node. Set from dict key, not from YAML.
display_name: null  # Human-readable display name for the node.
description: null  # Optional description of the agent / team.
triggers: []  # Event sources that activate this agent / team
connections: []  # Targets to forward results to.
mcp_servers: []  # List of MCP server configurations:
input_provider: null  # Provider for human-input-handling.
event_handlers: []  # Event handlers for processing agent stream events.

Examples¶

Basic Configuration¶

A minimal Claude Code agent for coding tasks:

claude_code_agents:
  coder:
    cwd: /path/to/project
    model: claude-sonnet-4-5

Custom System Prompt¶

Add custom instructions while keeping Claude Code's built-in system prompt:

claude_code_agents:
  python_dev:
    cwd: /path/to/project
    model: claude-sonnet-4-5
    system_prompt:
      - "You are a Python expert focused on clean, maintainable code."
      - "Always include type hints and docstrings."
      - "Prefer pytest for testing."

To replace the built-in prompt entirely:

claude_code_agents:
  minimal_agent:
    cwd: /path/to/project
    include_builtin_system_prompt: false
    system_prompt: "You are a focused code reviewer. Only suggest improvements."

Tool Restrictions¶

Control which tools the agent can use:

claude_code_agents:
  reader:
    cwd: /path/to/project
    allowed_tools:
      - Read
      - Grep
      - Glob
    disallowed_tools:
      - Bash
      - Write
      - Edit

Extended Thinking¶

Enable extended thinking for complex reasoning:

claude_code_agents:
  architect:
    cwd: /path/to/project
    model: claude-sonnet-4-5
    max_thinking_tokens: 10000
    system_prompt: "You are a software architect. Think deeply about design decisions."

Toolset Integration¶

Expose AgentPool's internal toolsets to Claude Code via MCP:

claude_code_agents:
  coordinator:
    cwd: /path/to/project
    tools:
      - type: subagent
        agents:
          - researcher
          - writer
      - type: agent_management
      - type: resource_access

This allows Claude Code to delegate tasks to other AgentPool agents.

Structured Output¶

Define typed responses:

responses:
  code_review:
    type: object
    properties:
      issues:
        type: array
        items:
          type: object
          properties:
            file: { type: string }
            line: { type: integer }
            severity: { type: string, enum: [error, warning, info] }
            message: { type: string }
      summary: { type: string }
      approved: { type: boolean }

claude_code_agents:
  reviewer:
    cwd: /path/to/project
    output_type: code_review
    system_prompt: "Review the code and provide structured feedback."

Environment Variables¶

Set environment variables for the agent:

claude_code_agents:
  secure_agent:
    cwd: /path/to/project
    env:
      ANTHROPIC_API_KEY: ""  # Empty forces subscription usage
      DEBUG: "1"
      CUSTOM_VAR: "value"

Permission Modes¶

Claude Code agents support different permission handling modes:

Example:

claude_code_agents:
  planner:
    cwd: /path/to/project
    permission_mode: plan
    system_prompt: "Analyze the codebase and create an implementation plan."

Toolset Integration¶

One of the key features of Claude Code agents is the ability to expose AgentPool's internal toolsets via MCP. When you configure toolsets, they are:

1. Started as an in-process MCP server
2. Connected to Claude Code using the SDK's native MCP support
3. Available as tools within Claude Code's tool palette

This enables powerful workflows:

claude_code_agents:
  smart_coder:
    cwd: /path/to/project
    tools:
      # Delegate to specialized agents
      - type: subagent
        agents:
          - test_writer
          - documentation_writer

      # Access shared resources
      - type: resource_access

      # Manage other agents
      - type: agent_management

The toolsets communicate directly with Claude Code without HTTP overhead.

Comparison with ACP Agents¶

Choose Claude Code agents for:

• Maximum performance and integration depth
• When you need toolset bridging
• Primary AgentPool deployments

Choose ACP agents when:

• Interoperating with other ACP clients (Zed, Toad)
• Using Claude Code alongside other ACP-compatible agents
• Building ACP-first architectures

Related Configuration¶

• ACP Agents - ACP protocol integration (alternative approach)
• Toolsets - Tool collections for agents
• System Prompts - Prompt configuration
• Responses - Structured output types