Agent SDK 概览

安装

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

pip install claude-agent-sdk

SDK 选项

Claude Agent SDK 提供多种形式以满足不同的用例需求：

• TypeScript SDK - 适用于 Node.js 和 Web 应用程序
• Python SDK - 适用于 Python 应用程序和数据科学
• 流式传输与单一模式 - 了解输入模式和最佳实践

为什么使用 Claude Agent SDK？

Claude Agent SDK 建立在支持 Claude Code 的代理框架之上，提供了构建生产就绪代理所需的所有构建块。

利用我们在 Claude Code 上所做的工作，包括：

• 上下文管理：自动压缩和上下文管理，确保您的代理不会耗尽上下文。
• 丰富的工具生态系统：文件操作、代码执行、网络搜索和 MCP 可扩展性
• 高级权限：对代理功能的细粒度控制
• 生产必需品：内置错误处理、会话管理和监控
• 优化的 Claude 集成：自动提示缓存和性能优化

您可以使用 SDK 构建什么？

以下是您可以创建的一些代理类型示例：

编码代理：

• SRE 代理，诊断和修复生产问题
• 安全审查机器人，审计代码中的漏洞
• 值班工程助手，对事件进行分类
• 代码审查代理，强制执行风格和最佳实践

业务代理：

• 法律助手，审查合同和合规性
• 财务顾问，分析报告和预测
• 客户支持代理，解决技术问题
• 营销团队的内容创建助手

核心概念

身份验证

对于基本身份验证，从 Claude 控制台 检索 Claude API 密钥，并设置 ANTHROPIC_API_KEY 环境变量。

SDK 还支持通过第三方 API 提供商进行身份验证：

• Amazon Bedrock：设置 CLAUDE_CODE_USE_BEDROCK=1 环境变量并配置 AWS 凭证
• Google Vertex AI：设置 CLAUDE_CODE_USE_VERTEX=1 环境变量并配置 Google Cloud 凭证

有关第三方提供商的详细配置说明，请参阅 Amazon Bedrock 和 Google Vertex AI 文档。

完整的 Claude Code 功能支持

SDK 提供对 Claude Code 中所有默认功能的访问权限，利用相同的基于文件系统的配置：

• 子代理：启动存储为 ./.claude/agents/ 中 Markdown 文件的专用代理
• 代理技能：通过存储在 ./.claude/skills/ 中的 SKILL.md 文件扩展 Claude 的专业功能
• 钩子：执行在 ./.claude/settings.json 中配置的自定义命令，这些命令响应工具事件
• 斜杠命令：使用定义为 ./.claude/commands/ 中 Markdown 文件的自定义命令
• 插件：使用 plugins 选项以编程方式加载自定义插件，以扩展 Claude Code 的自定义命令、代理、技能、钩子和 MCP 服务器。有关详细信息，请参阅插件。
• 内存 (CLAUDE.md)：通过项目目录中的 CLAUDE.md 或 .claude/CLAUDE.md 文件，或 ~/.claude/CLAUDE.md 用于用户级说明来维护项目上下文。要加载这些文件，您必须在选项中明确设置 settingSources: ['project']（TypeScript）或 setting_sources=["project"]（Python）。有关详细信息，请参阅修改系统提示。

这些功能与其 Claude Code 对应功能的工作方式相同，通过从相同的文件系统位置读取。

系统提示

系统提示定义您的代理的角色、专业知识和行为。这是您指定要构建的代理类型的地方。

工具权限

使用细粒度权限控制您的代理可以使用哪些工具：

• allowedTools - 明确允许特定工具
• disallowedTools - 阻止特定工具
• permissionMode - 设置总体权限策略

模型上下文协议 (MCP)

通过 MCP 服务器使用自定义工具和集成扩展您的代理。这允许您连接到数据库、API 和其他外部服务。

报告错误

如果您在 Agent SDK 中遇到错误或问题：

• TypeScript SDK：在 GitHub 上报告问题
• Python SDK：在 GitHub 上报告问题

更新日志

查看 SDK 更新、错误修复和新功能的完整更新日志：

• TypeScript SDK：查看 CHANGELOG.md
• Python SDK：查看 CHANGELOG.md

相关资源

• CLI 参考 - 完整的 CLI 文档
• GitHub Actions 集成 - 自动化您的 GitHub 工作流
• MCP 文档 - 使用自定义工具扩展 Claude
• 常见工作流 - 分步指南
• 故障排除 - 常见问题和解决方案