サブエージェント

サブエージェントは、メインエージェントが集中的なサブタスクを処理するために生成できる個別のエージェントインスタンス。コンテキストの分離、タスクの並列実行、専門的な指示の適用を行う。

作成方法

プログラム的に定義されたエージェントは、同じ名前のファイルシステムベースのエージェントよりも優先される。

サブエージェントの利点

• コンテキスト管理: メインエージェントとは別のコンテキストを維持し、情報過多を防止
• 並列化: 複数のサブエージェントを同時実行し、ワークフローを高速化
• 専門的な指示と知識: カスタマイズされたシステムプロンプトで特定の専門知識を付与
• ツール制限: 特定のツールに制限し、意図しないアクションのリスクを軽減

AgentDefinition設定

制約: サブエージェントは独自のサブエージェントを生成できない。tools 配列に Task を含めないこと。

コード例: プログラム的定義

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review the authentication module for security issues",
        options=ClaudeAgentOptions(
            # Task tool is required for subagent invocation
            allowed_tools=["Read", "Grep", "Glob", "Task"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
                    prompt="""You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.""",
                    tools=["Read", "Grep", "Glob"],
                    model="sonnet"
                ),
                "test-runner": AgentDefinition(
                    description="Runs and analyzes test suites. Use for test execution and coverage analysis.",
                    prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures""",
                    tools=["Bash", "Read", "Grep"]
                )
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import { query } from '@anthropic-ai/claude-agent-sdk';

for await (const message of query({
  prompt: "Review the authentication module for security issues",
  options: {
    allowedTools: ['Read', 'Grep', 'Glob', 'Task'],
    agents: {
      'code-reviewer': {
        description: 'Expert code review specialist. Use for quality, security, and maintainability reviews.',
        prompt: `You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.`,
        tools: ['Read', 'Grep', 'Glob'],
        model: 'sonnet'
      },
      'test-runner': {
        description: 'Runs and analyzes test suites. Use for test execution and coverage analysis.',
        prompt: `You are a test execution specialist. Run tests and provide clear analysis of results.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures`,
        tools: ['Bash', 'Read', 'Grep'],
      }
    }
  }
})) {
  if ('result' in message) console.log(message.result);
}

動的エージェント設定

実行時の条件に基づいてエージェント定義を動的に作成できる。

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

def create_security_agent(security_level: str) -> AgentDefinition:
    is_strict = security_level == "strict"
    return AgentDefinition(
        description="Security code reviewer",
        prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",
        tools=["Read", "Grep", "Glob"],
        model="opus" if is_strict else "sonnet"
    )

async def main():
    async for message in query(
        prompt="Review this PR for security issues",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Task"],
            agents={
                "security-reviewer": create_security_agent("strict")
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

import { query, type AgentDefinition } from '@anthropic-ai/claude-agent-sdk';

function createSecurityAgent(securityLevel: 'basic' | 'strict'): AgentDefinition {
  const isStrict = securityLevel === 'strict';
  return {
    description: 'Security code reviewer',
    prompt: `You are a ${isStrict ? 'strict' : 'balanced'} security reviewer...`,
    tools: ['Read', 'Grep', 'Glob'],
    model: isStrict ? 'opus' : 'sonnet'
  };
}

for await (const message of query({
  prompt: "Review this PR for security issues",
  options: {
    allowedTools: ['Read', 'Grep', 'Glob', 'Task'],
    agents: {
      'security-reviewer': createSecurityAgent('strict')
    }
  }
})) {
  if ('result' in message) console.log(message.result);
}

一般的なツールの組み合わせ

呼び出し方式

• 自動呼び出し: Claudeがタスクと各サブエージェントの description に基づいて自動判断
• 明示的呼び出し: プロンプトで名前を指定（例: "Use the code-reviewer agent to check the authentication module"）

サブエージェント呼び出しの検出

サブエージェントはTaskツールを介して呼び出される。name: "Task" を持つ tool_use ブロックを確認する。サブエージェントのコンテキスト内からのメッセージには parent_tool_use_id フィールドが含まれる。

async for message in query(
    prompt="Use the code-reviewer agent to review this codebase",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep", "Task"],
        agents={
            "code-reviewer": AgentDefinition(
                description="Expert code reviewer.",
                prompt="Analyze code quality and suggest improvements.",
                tools=["Read", "Glob", "Grep"]
            )
        }
    )
):
    if hasattr(message, 'content') and message.content:
        for block in message.content:
            if getattr(block, 'type', None) == 'tool_use' and block.name == 'Task':
                print(f"Subagent invoked: {block.input.get('subagent_type')}")

    if hasattr(message, 'parent_tool_use_id') and message.parent_tool_use_id:
        print("  (running inside subagent)")

サブエージェントの再開

サブエージェントは中断したところから続行するために再開できる。完全な会話履歴を保持する。

1. セッションIDのキャプチャ: メッセージから session_id を抽出
2. エージェントIDの抽出: メッセージコンテンツから agentId を解析
3. セッションの再開: resume: sessionId を渡し、プロンプトにエージェントIDを含める

import { query, type SDKMessage } from '@anthropic-ai/claude-agent-sdk';

function extractAgentId(message: SDKMessage): string | undefined {
  if (!('message' in message)) return undefined;
  const content = JSON.stringify(message.message.content);
  const match = content.match(/agentId:\s*([a-f0-9-]+)/);
  return match?.[1];
}

let agentId: string | undefined;
let sessionId: string | undefined;

// First invocation
for await (const message of query({
  prompt: "Use the Explore agent to find all API endpoints in this codebase",
  options: { allowedTools: ['Read', 'Grep', 'Glob', 'Task'] }
})) {
  if ('session_id' in message) sessionId = message.session_id;
  const extractedId = extractAgentId(message);
  if (extractedId) agentId = extractedId;
  if ('result' in message) console.log(message.result);
}

// Second invocation - resume and ask follow-up
if (agentId && sessionId) {
  for await (const message of query({
    prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,
    options: { allowedTools: ['Read', 'Grep', 'Glob', 'Task'], resume: sessionId }
  })) {
    if ('result' in message) console.log(message.result);
  }
}

永続性に関する注意:

• メイン会話がコンパクションされても、サブエージェントのトランスクリプトは影響を受けない
• トランスクリプトはセッション内で永続化される
• 自動クリーンアップは cleanupPeriodDays 設定（デフォルト: 30日）に基づく