指南

SDK 中的子代理

在 Claude Agent SDK 中使用子代理

Claude Agent SDK 中的子代理是由主代理編排的專門化 AI。使用子代理進行上下文管理和並行化。

本指南說明如何使用 agents 參數在 SDK 中定義和使用子代理。

概述

在使用 SDK 時，子代理可以通過兩種方式定義：

程式化 - 在您的 query() 選項中使用 agents 參數（推薦用於 SDK 應用程式）
基於檔案系統 - 將帶有 YAML 前置資料的 markdown 檔案放置在指定目錄中（.claude/agents/）

本指南主要專注於使用 agents 參數的程式化方法，這為 SDK 應用程式提供了更整合的開發體驗。

使用子代理的好處

上下文管理

子代理與主代理保持獨立的上下文，防止資訊過載並保持互動的專注性。這種隔離確保專門化任務不會用無關細節污染主對話上下文。

範例：research-assistant 子代理可以探索數十個檔案和文件頁面，而不會用所有中間搜尋結果混亂主對話 - 只返回相關發現。

並行化

多個子代理可以同時運行，大幅加速複雜工作流程。

範例：在程式碼審查期間，您可以同時運行 style-checker、security-scanner 和 test-coverage 子代理，將審查時間從幾分鐘縮短到幾秒鐘。

專門化指令和知識

每個子代理都可以有量身定制的系統提示，具有特定的專業知識、最佳實踐和約束。

範例：database-migration 子代理可以擁有關於 SQL 最佳實踐、回滾策略和資料完整性檢查的詳細知識，這些在主代理的指令中會是不必要的雜訊。

工具限制

子代理可以被限制為特定工具，降低意外操作的風險。

範例：doc-reviewer 子代理可能只能存取 Read 和 Grep 工具，確保它可以分析但永遠不會意外修改您的文件檔案。

建立子代理

程式化定義（推薦）

使用 agents 參數直接在您的程式碼中定義子代理：

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

const result = query({
  prompt: "Review the authentication module for security issues",
  options: {
    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'],
      }
    }
  }
});

for await (const message of result) {
  console.log(message);
}

AgentDefinition 配置

欄位	類型	必需	描述
`description`	`string`	是	何時使用此代理的自然語言描述
`prompt`	`string`	是	定義代理角色和行為的系統提示
`tools`	`string[]`	否	允許的工具名稱陣列。如果省略，繼承所有工具
`model`	`'sonnet' \| 'opus' \| 'haiku' \| 'inherit'`	否	此代理的模型覆蓋。如果省略，預設為主模型

基於檔案系統的定義（替代方案）

您也可以將子代理定義為特定目錄中的 markdown 檔案：

專案級別：.claude/agents/*.md - 僅在當前專案中可用
使用者級別：~/.claude/agents/*.md - 在所有專案中可用

每個子代理都是帶有 YAML 前置資料的 markdown 檔案：

---
name: code-reviewer
description: Expert code review specialist. Use for quality, security, and maintainability reviews.
tools: Read, Grep, Glob, Bash
---

Your subagent's system prompt goes here. This defines the subagent's
role, capabilities, and approach to solving problems.

注意：程式化定義的代理（通過 agents 參數）優先於同名的基於檔案系統的代理。

SDK 如何使用子代理

使用 Claude Agent SDK 時，子代理可以程式化定義或從檔案系統載入。Claude 將：

載入程式化代理 從您選項中的 agents 參數
自動檢測檔案系統代理 從 .claude/agents/ 目錄（如果未被覆蓋）
自動調用它們 基於任務匹配和代理的 description
使用它們的專門化提示 和工具限制
為每個子代理調用維護獨立上下文

程式化定義的代理（通過 agents 參數）優先於同名的基於檔案系統的代理。

範例子代理

有關子代理的全面範例，包括程式碼審查員、測試執行器、除錯器和安全稽核員，請參閱主要子代理指南。該指南包括詳細的配置和建立有效子代理的最佳實踐。

SDK 整合模式

自動調用

SDK 將根據任務上下文自動調用適當的子代理。確保您代理的 description 欄位清楚地指示何時應該使用它：

const result = query({
  prompt: "Optimize the database queries in the API layer",
  options: {
    agents: {
      'performance-optimizer': {
        description: 'Use PROACTIVELY when code changes might impact performance. MUST BE USED for optimization tasks.',
        prompt: 'You are a performance optimization specialist...',
        tools: ['Read', 'Edit', 'Bash', 'Grep'],
        model: 'sonnet'
      }
    }
  }
});

明確調用

使用者可以在他們的提示中請求特定的子代理：

const result = query({
  prompt: "Use the code-reviewer agent to check the authentication module",
  options: {
    agents: {
      'code-reviewer': {
        description: 'Expert code review specialist',
        prompt: 'You are a security-focused code reviewer...',
        tools: ['Read', 'Grep', 'Glob']
      }
    }
  }
});

動態代理配置

您可以根據應用程式的需求動態配置代理：

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

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

const result = query({
  prompt: "Review this PR for security issues",
  options: {
    agents: {
      'security-reviewer': createSecurityAgent('strict')
    }
  }
});

工具限制

子代理可以通過 tools 欄位限制工具存取：

省略該欄位 - 代理繼承所有可用工具（預設）
指定工具 - 代理只能使用列出的工具

唯讀分析代理的範例：

const result = query({
  prompt: "Analyze the architecture of this codebase",
  options: {
    agents: {
      'code-analyzer': {
        description: 'Static code analysis and architecture review',
        prompt: `You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.`,
        tools: ['Read', 'Grep', 'Glob']  // No write or execute permissions
      }
    }
  }
});

常見工具組合

唯讀代理（分析、審查）：

tools: ['Read', 'Grep', 'Glob']

測試執行代理：

tools: ['Bash', 'Read', 'Grep']

程式碼修改代理：

tools: ['Read', 'Edit', 'Write', 'Grep', 'Glob']

SDK 中的子代理

在 Claude Agent SDK 中使用子代理

Claude Agent SDK 中的子代理是由主代理編排的專門化 AI。使用子代理進行上下文管理和並行化。

本指南說明如何使用 agents 參數在 SDK 中定義和使用子代理。

概述

在使用 SDK 時，子代理可以通過兩種方式定義：

程式化 - 在您的 query() 選項中使用 agents 參數（推薦用於 SDK 應用程式）
基於檔案系統 - 將帶有 YAML 前置資料的 markdown 檔案放置在指定目錄中（.claude/agents/）

本指南主要專注於使用 agents 參數的程式化方法，這為 SDK 應用程式提供了更整合的開發體驗。

使用子代理的好處

上下文管理

子代理與主代理保持獨立的上下文，防止資訊過載並保持互動的專注性。這種隔離確保專門化任務不會用無關細節污染主對話上下文。

範例：research-assistant 子代理可以探索數十個檔案和文件頁面，而不會用所有中間搜尋結果混亂主對話 - 只返回相關發現。

並行化

多個子代理可以同時運行，大幅加速複雜工作流程。

範例：在程式碼審查期間，您可以同時運行 style-checker、security-scanner 和 test-coverage 子代理，將審查時間從幾分鐘縮短到幾秒鐘。

專門化指令和知識

每個子代理都可以有量身定制的系統提示，具有特定的專業知識、最佳實踐和約束。

範例：database-migration 子代理可以擁有關於 SQL 最佳實踐、回滾策略和資料完整性檢查的詳細知識，這些在主代理的指令中會是不必要的雜訊。

工具限制

子代理可以被限制為特定工具，降低意外操作的風險。

範例：doc-reviewer 子代理可能只能存取 Read 和 Grep 工具，確保它可以分析但永遠不會意外修改您的文件檔案。

建立子代理

程式化定義（推薦）

使用 agents 參數直接在您的程式碼中定義子代理：

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

const result = query({
  prompt: "Review the authentication module for security issues",
  options: {
    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'],
      }
    }
  }
});

for await (const message of result) {
  console.log(message);
}

AgentDefinition 配置

欄位	類型	必需	描述
`description`	`string`	是	何時使用此代理的自然語言描述
`prompt`	`string`	是	定義代理角色和行為的系統提示
`tools`	`string[]`	否	允許的工具名稱陣列。如果省略，繼承所有工具
`model`	`'sonnet' \| 'opus' \| 'haiku' \| 'inherit'`	否	此代理的模型覆蓋。如果省略，預設為主模型

基於檔案系統的定義（替代方案）

您也可以將子代理定義為特定目錄中的 markdown 檔案：

專案級別：.claude/agents/*.md - 僅在當前專案中可用
使用者級別：~/.claude/agents/*.md - 在所有專案中可用

每個子代理都是帶有 YAML 前置資料的 markdown 檔案：

---
name: code-reviewer
description: Expert code review specialist. Use for quality, security, and maintainability reviews.
tools: Read, Grep, Glob, Bash
---

Your subagent's system prompt goes here. This defines the subagent's
role, capabilities, and approach to solving problems.

注意：程式化定義的代理（通過 agents 參數）優先於同名的基於檔案系統的代理。

SDK 如何使用子代理

使用 Claude Agent SDK 時，子代理可以程式化定義或從檔案系統載入。Claude 將：

載入程式化代理 從您選項中的 agents 參數
自動檢測檔案系統代理 從 .claude/agents/ 目錄（如果未被覆蓋）
自動調用它們 基於任務匹配和代理的 description
使用它們的專門化提示 和工具限制
為每個子代理調用維護獨立上下文

程式化定義的代理（通過 agents 參數）優先於同名的基於檔案系統的代理。

範例子代理

SDK 整合模式

自動調用

SDK 將根據任務上下文自動調用適當的子代理。確保您代理的 description 欄位清楚地指示何時應該使用它：

const result = query({
  prompt: "Optimize the database queries in the API layer",
  options: {
    agents: {
      'performance-optimizer': {
        description: 'Use PROACTIVELY when code changes might impact performance. MUST BE USED for optimization tasks.',
        prompt: 'You are a performance optimization specialist...',
        tools: ['Read', 'Edit', 'Bash', 'Grep'],
        model: 'sonnet'
      }
    }
  }
});

明確調用

使用者可以在他們的提示中請求特定的子代理：

const result = query({
  prompt: "Use the code-reviewer agent to check the authentication module",
  options: {
    agents: {
      'code-reviewer': {
        description: 'Expert code review specialist',
        prompt: 'You are a security-focused code reviewer...',
        tools: ['Read', 'Grep', 'Glob']
      }
    }
  }
});

動態代理配置

您可以根據應用程式的需求動態配置代理：

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

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

const result = query({
  prompt: "Review this PR for security issues",
  options: {
    agents: {
      'security-reviewer': createSecurityAgent('strict')
    }
  }
});

工具限制

子代理可以通過 tools 欄位限制工具存取：

省略該欄位 - 代理繼承所有可用工具（預設）
指定工具 - 代理只能使用列出的工具

唯讀分析代理的範例：

const result = query({
  prompt: "Analyze the architecture of this codebase",
  options: {
    agents: {
      'code-analyzer': {
        description: 'Static code analysis and architecture review',
        prompt: `You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.`,
        tools: ['Read', 'Grep', 'Glob']  // No write or execute permissions
      }
    }
  }
});

常見工具組合

唯讀代理（分析、審查）：

tools: ['Read', 'Grep', 'Glob']

測試執行代理：

tools: ['Bash', 'Read', 'Grep']

程式碼修改代理：

tools: ['Read', 'Edit', 'Write', 'Grep', 'Glob']

SDK 中的子代理

概述

使用子代理的好處

上下文管理

並行化

專門化指令和知識

工具限制

建立子代理

程式化定義（推薦）

AgentDefinition 配置

基於檔案系統的定義（替代方案）

SDK 如何使用子代理

範例子代理

SDK 整合模式

自動調用

明確調用

動態代理配置

工具限制

常見工具組合

相關文件

SDK 中的子代理

概述

使用子代理的好處

上下文管理

並行化

專門化指令和知識

工具限制

建立子代理

程式化定義（推薦）

AgentDefinition 配置

基於檔案系統的定義（替代方案）

SDK 如何使用子代理

範例子代理

SDK 整合模式

自動調用

明確調用

動態代理配置

工具限制

常見工具組合

相關文件