Claude Agent SDK 是 Anthropic 推出的用于构建自定义 AI Agent 的软件开发工具包。它提供了一套完整的工具和接口，让开发者可以基于 Claude 模型构建自己的智能代理应用。与 Claude Code 内置的 Agent 不同，Agent SDK 是面向开发者的编程框架，用于创建独立运行的 AI 代理应用程序。
Agent SDK 的核心设计理念是将 Claude 强大的语言理解能力与自定义工具调用能力相结合。开发者可以通过 SDK 定义 Agent 的行为模式、注册外部工具、配置记忆系统以及编排复杂的多步骤任务。这使得 Agent 不再局限于简单的问答对话，而是能够主动执行任务、调用外部API、处理数据并做出决策。
Agent SDK 支持工具定义、任务编排、记忆管理、多代理协作等核心功能。工具定义允许开发者将任意 Python 函数注册为 Agent 可调用的工具；任务编排支持串行执行、并行执行和条件分支等多种模式；记忆管理系统提供了短期和长期两种记忆机制；多代理协作则允许多个 Agent 协同完成复杂工作流。
SDK 的设计充分考虑了生产环境的实际需求。它内置了完善的错误处理机制、日志监控能力、安全控制策略以及流式输出支持。开发者可以通过简单的配置启用这些功能，无需从零搭建基础设施。Agent SDK 还提供了丰富的可定制选项，从模型选择到系统提示词，从记忆存储方式到并发控制策略，都可以灵活配置。
与市面上其他 Agent 框架相比，Claude Agent SDK 的优势在于与 Claude 模型的深度集成。它充分利用了 Claude 的函数调用能力、长上下文窗口支持以及安全对齐特性。开发者可以专注于业务逻辑的实现，而不必关注底层模型调用的细节。SDK 封装了请求构建、响应解析、上下文管理、重试策略等复杂操作，提供了简洁而强大的 API 接口。
Agent SDK 围绕几个核心抽象概念构建，理解这些概念是使用 SDK 的基础。每个概念都对应 SDK 中的一个类或模块，开发者通过组合这些概念来构建完整的 Agent 应用。下面逐一介绍这些核心概念及其用法。
Agent 是 SDK 中最核心的抽象，代表一个独立的 AI 代理实例。每个 Agent 拥有自己的模型配置、工具列表、系统提示词和行为参数。Agent 负责接收用户输入、调用大模型、执行工具函数并返回结果。开发者可以创建多个 Agent 实例，每个实例专注于不同的任务领域。一个 Agent 实例通常通过指定模型名称、系统提示词和可用工具列表来初始化。
Tool 是 Agent 可以调用的外部功能单元。工具可以是简单的计算函数、API 调用封装、数据库查询操作或任何可编程的功能模块。SDK 提供了多种定义工具的方式，最常见的是使用 @function_tool 装饰器将普通 Python 函数注册为工具。工具定义包括函数名称、参数描述和返回值类型，Claude 模型会根据这些信息决定何时调用哪个工具。
Task 是 Agent 需要完成的工作单元。一个 Task 包含明确的目标、输入参数和预期输出。SDK 支持将复杂工作分解为多个 Task，并通过编排策略控制 Task 的执行顺序和依赖关系。Task 可以串行执行（一个接一个）、并行执行（同时进行）或按条件分支执行（根据结果选择路径）。Task 的执行结果可以被后续 Task 引用，形成完整的工作流。
Memory 是 Agent 的记忆系统，负责保存和管理 Agent 与用户的交互历史。记忆系统分为短期记忆和长期记忆两个层次。短期记忆保存在当前会话上下文中，Agent 在对话过程中可以实时访问；长期记忆则跨会话持久化存储，Agent 在后续会话中可以检索和引用之前的交互信息。记忆系统还负责处理上下文窗口的 Token 限制，自动管理历史记录的保留和裁剪。
Orchestrator 是管理多 Agent 协作的协调组件。当应用需要多个 Agent 协同工作时，Orchestrator 负责任务分配、结果汇总、冲突解决和流程控制。它可以按照预定义的工作流图（DAG）调度多个 Agent 的任务执行，也可以根据实时情况动态调整执行策略。Orchestrator 是构建复杂多Agent 系统的关键组件。
Agent SDK 的核心能力是让开发者自定义工具。工具是 Agent 与外部世界交互的桥梁，通过工具 Agent 可以获取实时信息、执行计算操作、查询数据库、调用第三方 API 等。SDK 提供了多种灵活的工具定义方式，以适应不同的开发场景和需求。
Function Tool 是最简单、最常用的工具定义方式。开发者只需编写一个普通的 Python 函数，并使用 @function_tool 装饰器将其标记为工具。函数的参数类型注解会被自动解析为工具的 JSON Schema，函数的文档字符串（docstring）则作为工具的描述信息。Claude 模型会根据工具的名称、参数描述和返回值来决定何时调用该工具。
对于需要更精细控制的场景，SDK 提供了 Custom Tool 接口。开发者可以创建一个继承自 BaseTool 的类，实现 execute 方法。这种方式允许开发者自定义工具的参数校验逻辑、错误处理策略、执行前后钩子以及权限控制。Custom Tool 适合需要复杂初始化、资源管理或安全控制的工具。
工具的参数定义支持两种方式：Python 类型注解和 JSON Schema。类型注解方式更简洁直观，适合大部分场景；JSON Schema 方式更灵活，支持复杂的参数校验规则，如枚举值、正则表达式、嵌套结构等。SDK 会自动将类型注解转换为 JSON Schema 格式发送给模型。
工具执行过程中可能遇到各种错误，如网络超时、数据格式异常、权限不足等。SDK 提供了完善的错误处理机制：工具函数内可以抛出特定异常，SDK 会捕获这些异常并将错误信息返回给模型，让模型决定如何处理。开发者还可以配置重试策略，指定最大重试次数和重试间隔。工具执行的错误不会导致整个 Agent 崩溃，Agent 可以继续运行并尝试其他方案。
定义好的工具需要注册到 Agent 实例才能被调用。工具注册在 Agent 初始化时通过 tools 参数完成，也可以在 Agent 运行过程中动态添加或移除。工具注册后会生成一个工具描述列表，该列表会随每次模型调用一并发送，让模型了解当前可用的工具集。
| 特性 | Function Tool | Custom Tool |
|---|---|---|
| 定义复杂度 | 低（一个装饰器即可） | 中（需要定义类） |
| 参数解析 | 自动（基于类型注解） | 手动（需实现参数校验） |
| 错误处理 | 基础（try/except） | 高级（自定义异常策略） |
| 生命周期管理 | 无 | 有（init/execute/cleanup） |
| 资源管理 | 不适用 | 支持（数据库连接等） |
| 适用场景 | 简单功能、无状态操作 | 复杂逻辑、有状态操作 |
在大多数场景下优先使用 Function Tool，它更简洁易用。只有当工具需要管理外部资源（如数据库连接、文件句柄）、需要复杂的初始化逻辑或者需要精细的错误恢复策略时，才考虑使用 Custom Tool。好的工具设计应该职责单一，每个工具只做一件事并做好。
创建和配置 Agent 是使用 SDK 的核心环节。Agent 的配置决定了其行为方式、能力边界和运行表现。SDK 提供了丰富的配置选项，开发者可以根据应用场景灵活调整。下面详细介绍 Agent 的主要配置项和运行模式。
Agent 可以指定使用的 Claude 模型版本。不同的模型在性能、速度和成本上各有侧重。开发者可以根据任务的复杂度和实时性要求选择合适的模型。例如，复杂的分析任务可以选择推理能力更强的 Sonnet 模型，而简单的对话任务则可以使用响应更快的 Haiku 模型。模型选择直接影响 Agent 的行为质量、响应速度和运营成本。
系统提示词定义了 Agent 的行为准则和角色定位。通过精心设计的系统提示词，开发者可以控制 Agent 的语气风格、知识范围、决策逻辑和安全边界。好的系统提示词应当清晰地描述 Agent 的角色、能力边界、交互方式和输出格式要求。系统提示词还可以包含一些约束规则，如禁止执行的操作、必须遵循的流程等。
工具列表是 Agent 可调用工具的集合。在 Agent 初始化时通过 tools 参数传入工具列表。工具列表中的每个工具都会生成对应的工具描述，随每次请求发送给模型。开发者可以根据场景需要动态调整工具列表，例如在特定任务中添加临时工具，或在安全敏感场景中限制可用工具。
Agent 的记忆功能可以通过 memory 参数启用或关闭。开启记忆后，Agent 会记录对话历史，在后续交互中引用之前的上下文。记忆的存储方式可以配置为内存存储（进程内）、文件存储（本地持久化）或数据库存储（远程持久化）。记忆配置还包括历史窗口大小、自动裁剪策略等参数。
Agent SDK 支持三种运行模式，满足不同的交互需求。单次执行模式（run）接受一次输入并返回一次输出，适用于一次性任务处理。流式输出模式（stream）实时输出 Agent 的推理过程和工具调用结果，适用于需要实时反馈的场景。多轮对话模式（chat）保持对话上下文，支持连续多轮交互，适用于对话式应用场景。
| 运行模式 | 方法 | 特点 | 适用场景 |
|---|---|---|---|
| 单次执行 | run() |
一次性输入输出，无状态 | 批处理、API调用 |
| 流式输出 | stream() |
实时显示推理过程，低延迟 | 聊天界面、实时监控 |
| 多轮对话 | chat() |
保持上下文，支持历史引用 | 客服系统、AI助手 |
生产环境中建议使用低温度值（0.1-0.3）以获得更稳定、可预测的输出。对于创意性任务可以适当提高温度（0.7-0.9）。系统提示词中明确列出 Agent 可用的工具和它们的功能描述，可以让模型更准确地选择合适的工具。
任务编排是 Agent SDK 的高级功能，允许开发者将复杂的工作流程分解为多个可管理的任务单元，并通过编排策略控制它们的执行顺序和依赖关系。良好的任务编排可以显著提升 Agent 系统的可靠性、可维护性和执行效率。
单任务模式是最简单的编排方式，一个 Agent 执行一个独立的任务。Agent 接收输入后，自主决定如何调用工具、何时完成任务，并返回最终结果。单任务模式适用于功能单一、不需要多步骤协作的场景，如信息查询、文本翻译、数据格式化等。
并行执行模式允许将多个任务同时分配给一个或多个 Agent 执行。这些任务之间没有依赖关系，可以独立运行。并行执行可以显著缩短总体处理时间，特别适合需要同时处理多个独立数据源的场景，如同时查询多个数据库、同时分析多个文档等。SDK 的并行执行基于 Python 的异步机制实现，开发者可以通过简单的配置控制并发度。
流水线模式将任务组织成链式结构，前一个任务的输出作为后一个任务的输入。这种模式适合数据加工流程，如"数据采集 -> 数据清洗 -> 数据分析 -> 报告生成"的完整流水线。每个环节的输出都经过明确定义，便于调试和优化。流水线中的每个任务可以由不同的 Agent 执行，各 Agent 专注于自己擅长的环节。
条件分支允许根据前一个任务的执行结果动态选择下一步的执行路径。例如，在代码审查场景中，如果审查未通过则进入修改任务，如果审查通过则进入合并任务。条件分支使工作流可以应对复杂多变的业务逻辑，避免了将所有可能性硬编码在单个任务中。SDK 支持基于结果值、状态码、异常类型等多种条件判断。
循环与重试策略用于处理任务执行失败的情况。SDK 提供了可配置的重试机制，包括最大重试次数、重试间隔、退避策略（固定间隔/指数退避）等。对于可能因临时故障失败的任务（如网络请求），自动重试可以显著提高系统的鲁棒性。重试策略可以按任务单独配置，精细控制每个任务的容错级别。
| 编排模式 | 执行方式 | 依赖关系 | 典型场景 |
|---|---|---|---|
| 单任务 | 一个 Agent 执行一个任务 | 无 | 信息查询、简单计算 |
| 并行执行 | 多个任务同时执行 | 无依赖 | 批量数据采集、多源分析 |
| 流水线 | 任务链式执行 | 前序依赖 | 数据处理流程、ETL |
| 条件分支 | 根据结果选择路径 | 条件依赖 | 审批流程、质量检查 |
| 循环重试 | 失败后自动重试 | 时间依赖 | 网络请求、外部API调用 |
记忆系统是 Agent 实现连贯对话和持续学习的基础。Agent SDK 提供了多层次的记忆机制，让 Agent 能够在单次会话内保持上下文连贯性，也能跨会话积累知识和经验。有效的记忆管理可以显著提升 Agent 的实用性和用户体验。
短期记忆保存在当前会话上下文中，Agent 在整个对话过程中可以实时访问。短期记忆记录了当前会话的所有交互历史，包括用户输入、Agent回复、工具调用及其结果。这些信息被组织成消息列表，在每次模型调用时作为上下文发送给模型。短期记忆的生命周期与会话绑定，会话结束则记忆清除。短期记忆的容量受模型的上下文窗口限制，SDK 会自动管理消息的取舍策略。
长期记忆跨会话持久化存储，允许 Agent 在不同的会话之间保持信息连续性。长期记忆可以存储用户偏好、历史决策记录、领域知识等重要信息。这些信息被存储在外部存储器中（文件或数据库），在每次会话开始时自动加载到上下文中。长期记忆的使用需要开发者配置合适的存储后端和检索策略，以确保记忆信息的有效存取。
SDK 支持多种记忆存储方式，开发者可以根据应用规模和性能要求选择合适的存储后端。内存存储是最简单的存储方式，数据保存在进程内存中，进程退出则数据丢失，适合开发和测试场景。文件存储将记忆数据序列化到本地文件系统中，支持跨进程持久化，适合单机部署场景。数据库存储使用关系型或非关系型数据库保存记忆数据，支持分布式部署和海量数据管理，适合生产级应用场景。
由于模型存在上下文窗口的 Token 数量限制，当对话历史过长时需要进行管理和裁剪。SDK 提供了自动的上下文管理策略：当历史消息接近 Token 上限时，会自动裁剪较早的对话内容，保留最近的消息和关键上下文信息。开发者可以配置裁剪策略的参数，如保留的最小消息数量、关键信息的标记规则等。合理的上下文管理策略可以在有限的 Token 预算内最大化有效信息的保留。
记忆检索机制允许 Agent 按需加载相关历史信息，而不是将所有历史都塞入上下文。SDK 支持基于关键词、语义相似度和时间范围的检索方式。当 Agent 需要参考历史信息时，可以通过检索接口查询相关的历史记录。检索式记忆访问可以更有效地利用上下文窗口的 Token 资源，避免无关信息占用宝贵的上下文空间。
| 存储方式 | 持久化 | 访问速度 | 适用规模 | 场景 |
|---|---|---|---|---|
| 内存存储 | 否 | 极快 | 小（< 1000条） | 开发调试、单次会话 |
| 文件存储 | 是 | 快 | 中（< 10万条） | 单机部署、个人应用 |
| 数据库存储 | 是 | 中 | 大（> 10万条） | 生产环境、多实例部署 |
在开发阶段使用内存存储即可，简单高效。进入生产环境后建议切换为数据库存储，并使用检索机制避免将全部历史加载到上下文中。对于需要长期记忆的应用，定期对记忆数据进行清理和归档也是必要的维护工作，可以防止存储空间无限增长。
除了核心功能外，Agent SDK 还提供了一系列高级特性，帮助开发者构建更强大、更安全、更可靠的 Agent 应用。这些高级特性涵盖了多 Agent 协作、人机交互、安全控制、监控日志和流式输出等关键领域。
多代理协作允许多个 Agent 协同工作，共同完成复杂任务。每个 Agent 可以专注于特定的领域或功能，通过 Orchestrator 统一调度。例如，在一个智能客服系统中，查询 Agent 负责检索信息，推荐 Agent 负责生成建议，投诉 Agent 负责处理用户投诉，各 Agent 之间通过消息传递机制交换信息。多代理架构特别适合需要多种专业能力的复杂业务场景。
人机交互机制允许在 Agent 执行流程中插入需要人类确认或干预的环节。当 Agent 遇到需要人类判断的决策点时（如确认是否执行高风险操作、解释模糊的用户意图），可以暂停执行并等待人类反馈。这种机制在需要人工审核的场景中非常重要，如金融交易审批、医疗建议生成、合同条款审核等。人机交互环节可以配置超时策略和默认处理方式。
Agent SDK 提供了多层安全控制机制。权限控制允许限制 Agent 可访问的资源和可执行的操作，通过工具级别的权限管理实现最小权限原则。内容审核机制可以过滤 Agent 生成的敏感内容，避免输出不当信息。速率控制可以限制 Agent 的 API 调用频率和资源消耗，防止异常行为导致的服务过载。这些安全机制共同构建了 Agent 应用的安全防线。
监控与日志功能帮助开发者追踪 Agent 的运行状态和行为轨迹。SDK 内置了结构化日志系统，记录 Agent 的每次模型调用、工具执行、错误发生和决策路径等关键信息。这些日志可以输出到控制台、文件或外部日志收集系统（如 ELK、Datadog）。通过分析日志，开发者可以了解 Agent 的行为模式、发现潜在问题并持续优化 Agent 的表现。
流式输出功能允许 Agent 实时显示其思考过程和工具调用结果。与等待完整输出不同，流式输出可以让用户实时看到 Agent 的推理过程，提升交互体验和透明度。对于工具调用，流式输出不仅可以显示最终结果，还可以展示中间步骤的状态，如"正在查询数据库..."、"正在分析数据..."等。
Agent SDK 的应用范围非常广泛，从简单的工具自动化到复杂的多 Agent 协作系统，都能充分发挥其能力优势。下面介绍四个典型的实际应用场景，帮助开发者理解如何将 SDK 的能力落地到真实业务中。
需求分析：传统客服系统依赖人工处理大量重复性问题，成本高效率低。通过 Agent SDK 构建智能客服 Agent，可以自动回答用户常见问题，仅将复杂问题转接人工。
实现方案：创建一个客服 Agent，配置产品知识库查询工具、订单状态查询工具和常见问题检索工具。Agent 收到用户问题后，首先检索知识库寻找答案，必要时查询订单系统获取个性化信息。对于无法处理的问题，Agent 自动生成工单并转接人工客服。系统采用流式输出模式，让用户实时看到 Agent 的响应过程。
效果评估：智能客服 Agent 可以处理约 80% 的常见问题，平均响应时间从人工的 3 分钟缩短到 10 秒以内。用户满意度保持稳定，人工客服的工作量显著降低。
需求分析：代码审查是保证代码质量的重要环节，但人工审查耗时耗力且容易遗漏问题。通过 Agent SDK 构建代码审查 Agent，可以自动分析 Pull Request 并提供审查意见。
实现方案：创建一个代码审查 Agent，配置代码差异分析工具、静态检查工具、安全漏洞扫描工具和性能分析工具。Agent 获取 PR 的代码变更后，逐一调用分析工具进行检查，然后汇总所有发现的问题，按严重程度分级给出修改建议。Agent 还可以结合项目的历史代码风格和规范，提供个性化的审查意见。
效果评估：代码审查 Agent 可以检测出约 70% 的常见代码问题，包括潜在的 Bug、安全漏洞和性能瓶颈。每轮审查耗时约 30 秒，大大减轻了人工审查的工作负担。
需求分析：数据分析工作通常需要编写 SQL 查询、执行统计分析、生成可视化图表，过程繁琐且重复。通过 Agent SDK 构建数据分析 Agent，可以用自然语言交互完成数据分析全流程。
实现方案：创建一个数据分析 Agent，配置数据库查询工具、数据清洗工具、统计分析工具和图表生成工具。用户用自然语言描述分析需求，Agent 自动将其转换为 SQL 查询语句，执行查询后对结果进行清洗和分析，最后生成可视化图表和分析报告。Agent 采用流水线编排模式，确保数据处理流程的可追溯性和可重复性。
效果评估：数据分析 Agent 将一次典型数据分析任务的完成时间从天级别缩短到分钟级别。非技术团队成员也可以自助完成数据分析，无需依赖数据工程师。
需求分析：复杂的业务流程往往需要多个专业角色的协作，如市场调研、产品设计、技术评估和风险评估等环节。通过 Agent SDK 构建多 Agent 协作系统，可以模拟团队协作完成复杂项目。
实现方案：创建多个专业 Agent——调研 Agent 负责收集和分析市场信息，设计 Agent 负责生成产品方案，技术 Agent 负责评估技术可行性，风险 Agent 负责识别潜在风险。Orchestrator 协调器负责管理各 Agent 的协作流程：先由调研 Agent 输出市场报告，设计 Agent 基于报告生成方案，技术 Agent 和风险 Agent 并行评估方案，最后由协调器汇总所有意见生成综合建议。
效果评估：多 Agent 协作系统可以在 10 分钟内完成需要跨部门团队数天才能完成的初始调研和方案评估工作。各 Agent 的专业分工保证了输出的全面性和深度。
通过以上内容的学习，我们对 Claude Agent SDK 有了全面的认识。下面总结最关键的知识点，便于在实际开发中快速回顾和应用。