Claude Code Agent SDK 入门

Claude Code Agent SDK 入门

SDK 概览

8 分钟阅读

Agent SDK 概览

使用 Claude Code 作为库构建生产级 AI 智能体

构建能够自主读取文件、运行命令、搜索网络、编辑代码等的 AI 智能体。Agent SDK 为您提供了与 Claude Code 相同的工具、智能体循环和上下文管理,可在 Python 和 TypeScript 中编程。有关智能体工具设计背后的思考,请参阅博客上的 A harness for every task: dynamic workflows in Claude Code

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)  # Claude reads the file, finds the bug, edits it


asyncio.run(main())

Agent SDK 包含用于读取文件、运行命令和编辑代码的内置工具,因此您的智能体可以立即开始工作,无需您实现工具执行。深入了解快速入门或探索使用 SDK 构建的真实智能体:

开始使用

1

安装 SDK

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

TypeScript SDK 为您的平台捆绑了一个本地 Claude Code 二进制文件作为可选依赖项,因此您无需单独安装 Claude Code。

2

设置您的 API 密钥

控制台获取 API 密钥,然后将其设置为环境变量。

在 macOS 或 Linux 上:

export ANTHROPIC_API_KEY=sk-ant-xxxxx

在 Windows PowerShell 上:

$env:ANTHROPIC_API_KEY = "sk-ant-xxxxx"

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

  • Amazon Bedrock:设置 CLAUDE_CODE_USE_BEDROCK=1 环境变量并配置 AWS 凭证
  • Claude Platform on AWS:设置 CLAUDE_CODE_USE_ANTHROPIC_AWS=1ANTHROPIC_AWS_WORKSPACE_ID,然后配置 AWS 凭证
  • Google Cloud 的 Agent Platform:设置 CLAUDE_CODE_USE_VERTEX=1 环境变量并配置 Google Cloud 凭证
  • Microsoft Azure:设置 CLAUDE_CODE_USE_FOUNDRY=1 环境变量并配置 Azure 凭证

有关详细信息,请参阅 Amazon BedrockClaude Platform on AWSGoogle Cloud 的 Agent PlatformMicrosoft Foundry 的设置指南。

除非事先获得批准,否则 Anthropic 不允许第三方开发人员为其产品(包括基于 Claude Agent SDK 构建的智能体)提供 claude.ai 登录或速率限制。请改用本文档中描述的 API 密钥身份验证方法。

3

运行您的第一个智能体

此示例创建一个智能体,该智能体使用内置工具列出当前目录中的文件。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="What files are in this directory?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

准备好构建了吗? 按照快速入门在几分钟内创建一个查找和修复 bug 的智能体。

功能

使 Claude Code 强大的一切都可在 SDK 中使用:

您的智能体可以开箱即用地读取文件、运行命令和搜索代码库。关键工具包括:

工具功能
Read读取工作目录中的任何文件
Write创建新文件
Edit对现有文件进行精确编辑
Bash运行终端命令、脚本、git 操作
Monitor监视后台脚本并对每个输出行作为事件做出反应
Glob按模式查找文件(**/*.tssrc/**/*.py
Grep使用正则表达式搜索文件内容
WebSearch搜索网络以获取当前信息
WebFetch获取并解析网页内容
AskUserQuestion向用户提出带有多选选项的澄清问题

此示例创建一个智能体,该智能体在您的代码库中搜索 TODO 注释:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Find all TODO comments and create a summary",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

Claude Code 功能

SDK 还支持 Claude Code 的基于文件系统的配置。使用默认选项,SDK 从您的工作目录中的 .claude/~/.claude/ 加载这些。要限制加载哪些源,请在您的选项中设置 setting_sources(Python)或 settingSources(TypeScript)。

功能描述位置
SkillsClaude 自动使用或您使用 /name 调用的专门功能.claude/skills/*/SKILL.md
Commands旧格式的自定义命令。为新的自定义命令使用 skills.claude/commands/*.md
Memory项目上下文和说明CLAUDE.md.claude/CLAUDE.md
Plugins使用 skills、智能体、hooks 和 MCP 服务器扩展通过 plugins 选项编程

将 Agent SDK 与其他 Claude 工具进行比较

Claude 平台提供了多种使用 Claude 构建的方式。以下是 Agent SDK 的适用场景:

Anthropic Client SDK 为您提供直接 API 访问:您发送提示并自己实现工具执行。Agent SDK 为您提供具有内置工具执行的 Claude。

使用 Client SDK,您实现工具循环。使用 Agent SDK,Claude 处理它:

# Client SDK: You implement the tool loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

# Agent SDK: Claude handles tools autonomously
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

更新日志

查看完整的更新日志以了解 SDK 更新、bug 修复和新功能:

报告 bug

如果您在 Agent SDK 中遇到 bug 或问题:

品牌指南

对于集成 Claude Agent SDK 的合作伙伴,使用 Claude 品牌是可选的。在您的产品中引用 Claude 时:

允许:

  • "Claude Agent"(首选用于下拉菜单)
  • "Claude"(当已在标记为"Agents"的菜单中时)
  • "{YourAgentName} Powered by Claude"(如果您有现有的智能体名称)

不允许:

  • "Claude Code" 或 "Claude Code Agent"
  • Claude Code 品牌的 ASCII 艺术或模仿 Claude Code 的视觉元素

您的产品应保持自己的品牌,不应显示为 Claude Code 或任何 Anthropic 产品。如有关于品牌合规性的问题,请联系 Anthropic 销售团队

许可证和条款

Claude Agent SDK 的使用受 Anthropic 商业服务条款管制,包括当您使用它为您自己的客户和最终用户提供的产品和服务时,除非特定组件或依赖项由该组件的 LICENSE 文件中指示的不同许可证覆盖。

后续步骤

博极客AI是专业人工智能学习平台,提供通俗易懂的AI入门教程、大模型应用、实战项目与行业动态,全站内容免费阅览,零基础也能轻松学AI,适配学生、职场新人及技术爱好者。

© 版权所有 2026 博极客AI,保留一切权利。