Agent SDK

Claude Agent SDK 是 Anthropic 官方提供的框架，把 Claude Code 的 Agent 能力集成到你自己的应用中。

安装

Python

pip install claude-agent-sdk

需要 Python 3.10+。

TypeScript

npm install @anthropic-ai/claude-agent-sdk

快速开始

简单查询

from claude_agent_sdk import query

result = await query(
    prompt="分析这个项目的依赖安全性",
    options={
        "cwd": "/path/to/project",
        "permission_mode": "plan"  # 只读模式
    }
)
print(result)

多轮对话

from claude_agent_sdk import ClaudeSDKClient

client = ClaudeSDKClient(
    cwd="/path/to/project",
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="default"
)

response = await client.send("这个项目用了什么框架？")
response = await client.send("帮我找到所有 API 路由")

自定义工具

用 @tool 装饰器定义 Python 函数作为工具：

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool
def query_database(sql: str) -> str:
    """执行 SQL 查询并返回结果"""
    # 你的数据库查询逻辑
    return execute_sql(sql)

server = create_sdk_mcp_server(tools=[query_database])

这种方式比外部 MCP 服务器更轻量：

无需子进程管理
无 IPC 开销
单进程部署
完整类型安全

自定义 Subagents

Subagents 是运行在独立上下文中的专门化 AI 助手。

方式一：Markdown 文件

在 .claude/agents/ 下创建 .md 文件：

---
name: code-reviewer
description: 专门审查代码质量和安全性的 Agent
model: sonnet
tools:
  - Read
  - Glob
  - Grep
maxTurns: 10
permissionMode: plan
---

你是一个代码审查专家。审查代码时关注：
1. 安全漏洞（SQL 注入、XSS 等）
2. 性能问题
3. 代码规范

方式二：交互式创建

在 Claude Code 中输入 /agents，通过引导式设置创建。

Subagent 配置字段

字段	说明
`name`	Agent 名称（必需）
`description`	Agent 描述（必需）
`model`	模型：sonnet / opus / haiku
`tools`	可用工具列表
`disallowedTools`	禁用工具列表
`maxTurns`	最大交互轮次
`permissionMode`	权限模式
`mcpServers`	MCP 服务器配置
`hooks`	生命周期钩子
`memory`	持久记忆（user/project/local）
`background`	是否后台运行
`isolation`	worktree 隔离

内置 Subagents

Agent	模型	用途
Explore	Haiku	只读，快速代码搜索
Plan	继承	计划模式研究
General-purpose	继承	完整工具，复杂任务

SDK Hooks

在 Python 中定义 Hooks 拦截 Agent 行为：

from claude_agent_sdk import HookMatcher

def check_bash_command(event):
    command = event.tool_input.get("command", "")
    if "rm -rf" in command:
        return {"decision": "deny", "reason": "危险命令被阻止"}
    return {"decision": "allow"}

hooks = {
    "PreToolUse": [
        {
            "matcher": HookMatcher("Bash"),
            "handler": check_bash_command
        }
    ]
}

使用场景

CI/CD 集成 — 在流水线中自动审查代码
批量处理 — 同时处理多个文件或项目
自定义工作流 — 构建特定领域的 AI 工具
内部工具 — 为团队构建专属的 AI 助手

On this page