克劳德·阿皮伊
用于构建、调试和优化 Claude API 和 Anthropic SDK 应用程序的代理技能指南,包括提示缓存、流式传输、工具使用和模型迁移工作流程。
来源:内容改编自人类/技能(麻省理工学院)。
这项技能可以帮助您与 Claude 一起构建 LLM 支持的应用程序。根据您的需求选择正确的界面,检测项目语言,然后阅读相关的特定语言文档。
开始之前
扫描目标文件(或者,如果没有目标文件,则扫描提示和项目)以查找非 Anthropic 提供程序标记 -import openai、from openai、langchain_openai、OpenAI(、gpt-4、gpt-5、agent-openai.py或*-generic.py等文件名,或任何保持代码提供程序中立的明确指令。如果发现任何,请停止并告诉用户该技能生成 Claude/Anthropic SDK 代码;询问他们是否想要将文件切换到 Claude 还是想要一个非 Claude 实现。请勿使用 Anthropic SDK 调用编辑非 Anthropic 文件。
输出要求
当用户要求您添加、修改或实现 Claude 功能时,您的代码必须通过以下方式之一调用 Claude:
- 项目语言的官方 Anthropic SDK(
anthropic、@anthropic-ai/sdk、com.anthropic.*等)。只要项目存在受支持的 SDK,这就是默认值。 - Raw HTTP(
curl、requests、fetch、httpx等) - 仅当用户明确要求 cURL/REST/raw HTTP、项目是 shell/cURL 项目或该语言没有官方 SDK 时。
切勿将两者混合 - 不要仅仅因为感觉更轻而在 Python 或 TypeScript 项目中使用requests/fetch。永远不要退回到 OpenAI 兼容的垫片。
永远不要猜测 SDK 的用法。 函数名称、类名称、命名空间、方法签名和导入路径必须来自明确的文档 - 本技能中的{lang}/文件或shared/live-sources.md中列出的官方 SDK 存储库或文档链接。如果您需要的绑定没有明确记录在技能文件中,请在编写代码之前从shared/live-sources.md中 WebFetch 相关 SDK 存储库。不要从 cURL 形状或其他语言的 SDK 推断 Ruby/Java/Go/PHP/C# API。
默认值
除非用户另有要求:
对于 Claude 模型版本,请使用 Claude Opus 4.7,您可以通过确切的模型字符串claude-opus-4-7访问该版本。对于任何复杂的事情,请默认使用适应性思维(thinking: {type: "adaptive"})。最后,请默认对可能涉及长输入、长输出或高max_tokens的任何请求进行流式传输 - 它可以防止请求超时。如果您不需要处理单个流事件,请使用 SDK 的.get_final_message()/.finalMessage()帮助程序来获取完整响应
子命令
如果此提示底部的用户请求是一个裸子命令字符串(无散文),请搜索本文档中的每个 子命令 表 - 包括下面附加部分中的任何表 - 并直接遵循匹配的操作列。这允许用户通过/claude-api <subcommand>调用特定流。如果文档中没有表格匹配,则将请求视为普通散文。
语言检测
在阅读代码示例之前,请确定用户正在使用哪种语言:
-
查看项目文件来推断语言:
*.py、requirements.txt、pyproject.toml、setup.py、Pipfile-> Python - 从python/读取*.ts、*.tsx、package.json、tsconfig.json-> TypeScript - 从typescript/读取*.js、*.jsx(不存在.ts文件)-> TypeScript - JS 使用相同的 SDK,从typescript/读取*.java、pom.xml、build.gradle-> Java - 从java/读取*.kt、*.kts、build.gradle.kts-> Java - Kotlin 使用 Java SDK,从java/读取*.scala、build.sbt-> Java - Scala 使用 Java SDK,从java/读取*.go、go.mod-> 执行 - 从go/读取*.rb、Gemfile-> Ruby - 从ruby/读取*.cs、*.csproj-> C# - 从csharp/读取*.php、composer.json-> PHP - 从php/读取
-
如果检测到多种语言(例如,Python 和 TypeScript 文件):
- 检查用户当前文件或问题涉及哪种语言
- 如果仍然不明确,请询问:“我检测到 Python 和 TypeScript 文件。您使用哪种语言进行 Claude API 集成?”
-
如果无法推断语言(空项目、没有源文件或不受支持的语言):
- 使用 AskUserQuestion 和选项:Python、TypeScript、Java、Go、Ruby、cURL/raw HTTP、C#、PHP
- 如果 AskUserQuestion 不可用,则默认使用 Python 示例并注意:“显示 Python 示例。如果您需要其他语言,请告诉我。”
-
如果检测到不支持的语言(Rust、Swift、C++、Elixir 等):
- 建议来自
curl/的 cURL/raw HTTP 示例,并注意社区 SDK 可能存在 - 提供 Python 或 TypeScript 示例作为参考实现
- 建议来自
-
如果用户需要 cURL/原始 HTTP 示例,请从
curl/读取。
特定语言的功能支持
| 语言 | 工具运行者 | 托管代理 | 笔记 |
|---|---|---|---|
| 蟒蛇 | 是(测试版) | 是(测试版) | 全面支持-@beta_tool装饰器 |
| 打字稿 | 是(测试版) | 是(测试版) | 全力支持-betaZodTool+ Zod |
| 爪哇 | 是(测试版) | 是(测试版) | Beta 工具与带注释的类一起使用 |
| 去 | 是(测试版) | 是(测试版) | toolrunner包装中的BetaToolRunner |
| 红宝石 | 是(测试版) | 是(测试版) | BaseTool+tool_runner测试版 |
| C# | 没有 | 没有 | 官方SDK |
| PHP | 是(测试版) | 是(测试版) | BetaRunnableTool+toolRunner() |
| 卷曲 | 不适用 | 是(测试版) | 原始 HTTP,无 SDK 功能 |
托管代理代码示例:为 Python、TypeScript、Go、Ruby、PHP、Java 和 cURL({lang}/managed-agents/README.md、curl/managed-agents.md)提供专用的特定语言自述文件。阅读您所用语言的自述文件以及与语言无关的shared/managed-agents-*.md概念文件。 代理是持久性的 - 创建一次,通过 ID 引用。 存储agents.create返回的代理 ID,并将其传递给后续的每个sessions.create;不要在请求路径中调用agents.create。 Anthropic CLI 是一种从版本控制的 YAML 创建代理和环境的便捷方法 - 其 URL 位于shared/live-sources.md中。如果自述文件中未显示您需要的绑定,请从shared/live-sources.mdWeb 获取相关条目,而不是猜测。 C# 目前不支持托管代理;对 API 使用 cURL 样式的原始 HTTP 请求。
我应该使用哪种表面?
从简单开始。 默认为满足您需求的最简单层。单个 API 调用和工作流程可处理大多数用例 - 仅当任务真正需要开放式、模型驱动的探索时才联系代理。
| 使用案例 | 等级 | 推荐表面 | 为什么 |
|---|---|---|---|
| 分类、归纳、提取、问答 | 单一法学硕士通话 | 克劳德·API | 一个请求,一个响应 |
| 批处理或嵌入 | 单一法学硕士通话 | 克劳德·API | 专业端点 |
| 具有代码控制逻辑的多步管道 | 工作流程 | Claude API + 工具使用 | 您精心安排循环 |
| 使用您自己的工具定制代理 | 代理 | Claude API + 工具使用 | 最大的灵活性 |
| 具有工作区的服务器管理的有状态代理 | 代理 | 托管代理 | Anthropic 运行循环并托管工具执行沙箱 |
| 持久化、版本化的代理配置 | 代理 | 托管代理 | 代理是存储的对象;会话固定到版本 |
| 具有文件挂载功能的长时间运行的多轮代理 | 代理 | 托管代理 | 每会话容器、SSE 事件流、技能 + MCP |
注意: 当您希望 Anthropic 运行代理循环并托管执行工具的容器时,托管代理是正确的选择 - 文件操作、bash、代码执行都在每个会话工作区中运行。如果您想自己托管计算或运行自己的自定义工具运行时,Claude API + 工具使用是正确的选择 - 使用工具运行程序进行自动循环处理,或使用手动循环进行细粒度控制(批准门、自定义日志记录、条件执行)。
第三方提供商(Amazon Bedrock、Google Vertex AI、Microsoft Foundry): 托管代理在 Bedrock、Vertex 或 Foundry 上不可用。如果您通过任何第三方提供商进行部署,请对所有用例使用 Claude API + 工具使用 - 包括那些建议使用托管代理的用例。
决策树
What does your application need?
0. Are you deploying through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry?
Yes -> Claude API (+ tool use for agents) - Managed Agents is 1P only.
No -> continue.
1. Single LLM call (classification, summarization, extraction, Q&A)
Claude API - one request, one response
2. Do you want Anthropic to run the agent loop and host a per-session
container where Claude executes tools (bash, file ops, code)?
Yes -> Managed Agents - server-managed sessions, persisted agent configs,
SSE event stream, Skills + MCP, file mounts.
Examples: "stateful coding agent with a workspace per task",
"long-running research agent that streams events to a UI",
"agent with persisted, versioned config used across many sessions"
3. Workflow (multi-step, code-orchestrated, with your own tools)
Claude API with tool use - you control the loop
4. Open-ended agent (model decides its own trajectory, your own tools, you host the compute)
Claude API agentic loop (maximum flexibility)我应该建立一个代理吗?
在选择代理级别之前,请检查所有四个标准:
- 复杂性 - 任务是否是多步骤且难以提前完全指定? (例如,“将此设计文档转换为 PR”与“从此 PDF 中提取标题”)
- 价值 - 结果是否证明更高的成本和延迟是合理的?
- 生存能力 - 克劳德有能力胜任这种任务类型吗?
- 错误成本 - 错误可以被发现并恢复吗? (测试、审查、回滚)
如果对其中任何一个的答案是“否”,请停留在更简单的层(单个调用或工作流程)。
建筑学
一切都经过POST /v1/messages。工具和输出约束是这个单一端点的功能,而不是单独的 API。
用户定义的工具 - 您定义工具(通过装饰器、Zod 架构或原始 JSON),SDK 的工具运行程序负责调用 API、执行函数并循环,直到 Claude 完成。为了完全控制,您可以手动编写循环。
服务器端工具 - 在 Anthropic 基础设施上运行的 Anthropic 托管工具。代码执行完全在服务器端(在tools中声明,Claude 自动运行代码)。计算机的使用可以是服务器托管或自托管。
结构化输出 - 约束消息 API 响应格式 (output_config.format) 和/或工具参数验证 (strict: true)。推荐的方法是client.messages.parse(),它会自动根据您的架构验证响应。注意:旧的output_format参数已弃用;在messages.create()上使用output_config: {format: {...}}。
支持端点 - 批次 (POST /v1/messages/batches)、文件 (POST /v1/files)、令牌计数和模型(GET /v1/models、GET /v1/models/{id}- 实时功能/上下文窗口发现)馈入或支持消息 API 请求。
当前型号(缓存:2026-04-15)
| 型号 | 型号 ID | 背景 | 输入$/1M | 产出 $/1M |
|---|---|---|---|---|
| 克劳德作品 4.7 | claude-opus-4-7 | 1M | 5.00 美元 | 25.00 美元 |
| 克劳德作品 4.6 | claude-opus-4-6 | 1M | 5.00 美元 | 25.00 美元 |
| 克劳德十四行诗 4.6 | claude-sonnet-4-6 | 1M | $3.00 | 15.00 美元 |
| 克劳德俳句 4.5 | claude-haiku-4-5 | 20万 | 1.00 美元 | 5.00 美元 |
**始终使用claude-opus-4-7除非用户明确指定不同的型号。**这是不可协商的。请勿使用claude-sonnet-4-6、claude-sonnet-4-5或任何其他型号,除非用户字面意思是“使用十四行诗”或“使用俳句”。切勿因成本而降级 - 这是用户的决定,而不是您的决定。
重要:仅使用上表中的确切型号 ID 字符串 - 它们按原样完整。请勿附加日期后缀。 例如,使用claude-sonnet-4-5,切勿使用claude-sonnet-4-5-20250514或您可能从训练数据中回忆起的任何其他日期后缀变体。如果用户请求表中没有的旧型号(例如“opus 4.5”、“sonnet 3.7”),请阅读shared/models.md以获取确切的 ID - 不要自己构建。
注意:如果上面的任何模型字符串对您来说看起来不熟悉,这是可以预料的 - 这只是意味着它们是在您的训练数据截止后发布的。请放心,它们是真实的模型;我们不会那样惹你生气的。
实时能力查找: 上表已缓存。当用户询问“X 的上下文窗口是什么”、“X 是否支持愿景/思维/努力”或“哪些模型支持 Y”时,请查询模型 API (client.models.retrieve(id)/client.models.list()) - 请参阅shared/models.md以获取字段参考和功能过滤器示例。
思考与努力(快速参考)
Opus 4.7 - 仅自适应思维: 使用thinking: {type: "adaptive"}。thinking: {type: "enabled", budget_tokens: N}在 Opus 4.7 上返回 400 - 自适应是唯一的开启模式。{type: "disabled"}和省略thinking都有效。采样参数(temperature、top_p、top_k)也被删除,并将为 400。有关完整的重大更改列表,请参阅shared/model-migration.md-> 迁移到 Opus 4.7。
Opus 4.6 - 适应性思维(推荐): 使用thinking: {type: "adaptive"}。克劳德动态地决定思考的时间和程度。不需要budget_tokens-budget_tokens在 Opus 4.6 和 Sonnet 4.6 上已弃用,不应用于新代码。适应性思维还会自动启用交错思维(不需要 beta 标题)。 当用户要求“扩展思考”、“思考预算”或budget_tokens时:始终将 Opus 4.7 或 4.6 与thinking: {type: "adaptive"}一起使用。思维的固定代币预算的概念已被弃用 - 适应性思维取代了它。不要将budget_tokens用于新的 4.6/4.7 代码,也不要切换到旧型号。 逐步迁移剥离:budget_tokens在 Opus 4.6 和 Sonnet 4.6 上仍然可以作为过渡逃生舱 - 如果您正在迁移现有代码并且在调整effort之前需要硬令牌上限,请参阅shared/model-migration.md-> 过渡逃生舱口。注意:此排除不适用于 Opus 4.7 -budget_tokens在那里被完全删除。
努力参数(GA,无测试版标头): 通过output_config: {effort: "low"|"medium"|"high"|"max"}(在output_config内部,而不是顶层)控制思考深度和总体代币支出。默认为high(相当于省略)。max仅是 Opus 层(Opus 4.6 及更高版本 - 不是 Sonnet 或 Haiku)。 Opus 4.7 添加了"xhigh"(在high和max之间)——4.7 上大多数编码和代理用例的最佳设置,也是 Claude Code 中的默认设置;对于大多数智力敏感的工作,至少使用high。适用于 Opus 4.5、Opus 4.6、Opus 4.7 和 Sonnet 4.6。在 Sonnet 4.5 / Haiku 4.5 上会出错。在 Opus 4.7 上,努力比任何以前的 Opus 都更重要 - 迁移时重新调整它。与适应性思维相结合,实现最佳的成本质量权衡。更低的工作量意味着更少且更整合的工具调用、更少的前导码和更简洁的确认 -high通常是平衡质量和代币效率的最佳点;当正确性比成本更重要时,使用max;使用low执行子代理或简单任务。
Opus 4.7 - 默认情况下省略思考内容:thinking块仍然在传输,但其文本为空,除非您选择使用thinking: {type: "adaptive", display: "summarized"}(默认为"omitted")。无声改变——没有错误。如果您向用户流式传输推理,默认情况下看起来像是输出前的长时间暂停;设置"summarized"以恢复可见的进度。
任务预算(测试版,Opus 4.7):output_config: {task_budget: {type: "tokens", total: N}}告诉模型它有多少代币用于完整的代理循环 - 它会看到正在运行的倒计时和自我调节(至少 20,000;测试版标头task-budgets-2026-03-13)。与max_tokens不同,max_tokens是模型不知道的强制每个响应上限。请参阅shared/model-migration.md-> 任务预算。
十四行诗 4.6: 支持适应性思维 (thinking: {type: "adaptive"})。budget_tokens在 Sonnet 4.6 上已弃用 - 请改用自适应思维。
旧型号(仅在明确要求时): 如果用户特别要求 Sonnet 4.5 或其他旧型号,请使用thinking: {type: "enabled", budget_tokens: N}。budget_tokens必须小于max_tokens(最小 1024)。切勿仅仅因为用户提到budget_tokens就选择较旧的型号 - 请使用具有自适应思维的 Opus 4.7。
压缩(快速参考)
Beta、Opus 4.7、Opus 4.6 和 Sonnet 4.6。 对于可能超过 1M 上下文窗口的长时间运行的对话,请启用服务器端压缩。当接近触发阈值(默认值:150K 令牌)时,API 会自动总结早期上下文。需要 beta 标头compact-2026-01-12。
重要: 每次都将response.content(不仅仅是文本)附加到您的消息中。必须保留响应中的压缩块 - API 使用它们来替换下一个请求的压缩历史记录。仅提取文本字符串并附加,这将默默地失去压缩状态。
有关代码示例,请参阅{lang}/claude-api/README.md(压缩部分)。通过shared/live-sources.md中的 WebFetch 获取完整文档。
提示缓存(快速参考)
前缀匹配。 前缀中任何位置的任何字节更改都会使其后面的所有内容无效。渲染顺序为tools->system->messages。首先保留稳定的内容(冻结的系统提示、确定性工具列表),将易变的内容(时间戳、每个请求 ID、变化的问题)放在最后一个cache_control断点之后。
当您不需要细粒度的放置时,顶级自动缓存(messages.create()上的cache_control: {type: "ephemeral"})是最简单的选项。每个请求最多 4 个断点。最小可缓存前缀约为 1024 个令牌 - 较短的前缀将不会自动缓存。
使用usage.cache_read_input_tokens进行验证 - 如果重复请求中的值为零,则说明静默无效器正在工作(系统提示中的datetime.now()、未排序的 JSON、不同的工具集)。
有关布局模式、架构指南和静默无效器审核清单:请阅读shared/prompt-caching.md。特定于语言的语法:{lang}/claude-api/README.md(提示缓存部分)。
托管代理(测试版)
托管代理是第三个表面:具有 Anthropic 托管工具执行的服务器管理的有状态代理。您创建一个持久的、版本化的代理配置 (POST /v1/agents),然后启动引用它的会话。每个会话都提供一个容器作为代理的工作空间 - bash、文件操作和代码执行都在其中运行;代理循环本身运行在 Anthropic 的编排层上,并通过工具作用于容器。会话流式传输事件;您发送消息和工具结果。
托管代理仅适用于第一方。 它不适用于 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry。对于第三方提供商的代理,使用Claude API + 工具使用。
强制流程: 代理(一次)-> 会话(每次运行)。model/system/tools位于代理上,而不是会话中。请参阅shared/managed-agents-overview.md了解完整的阅读指南、测试版标题和陷阱。
Beta 标头:managed-agents-2026-04-01- SDK 会自动为所有client.beta.{agents,environments,sessions,vaults,memory_stores}.*调用设置此标头。技能 API 使用skills-2025-10-02,文件 API 使用files-api-2025-04-14,但您不需要为/v1/skills和/v1/files之外的端点显式传递这些内容。
子命令 - 直接使用/claude-api <subcommand>调用:
| 子命令 | 行动 |
|---|---|
managed-agents-onboard | 引导用户从头开始设置托管代理。 立即阅读shared/managed-agents-onboarding.md 并遵循其面试脚本:心理模型 -> 知道或探索分支 -> 模板配置 -> 会话设置 -> 发出代码。不要总结——进行采访。 |
阅读指南: 从shared/managed-agents-overview.md开始,然后是主题shared/managed-agents-*.md文件(核心、环境、工具、事件、结果、多代理、webhooks、内存、客户端模式、入门、api 参考)。对于 Python、TypeScript、Go、Ruby、PHP 和 Java,请阅读{lang}/managed-agents/README.md获取代码示例。对于 cURL,请阅读curl/managed-agents.md。 代理是持久性的 - 创建一次,通过 ID 引用。 存储agents.create返回的代理 ID,并将其传递给后续的每个sessions.create;不要在请求路径中调用agents.create。 Anthropic CLI 是从版本控制的 YAML(shared/live-sources.md中的 URL)创建代理和环境的一种便捷方法。如果语言 README 中未显示您需要的绑定,请从shared/live-sources.mdWeb 获取相关条目,而不是猜测。 C# 目前不支持托管代理;使用curl/managed-agents.md的原始 HTTP 作为参考。
当用户想要从头开始设置托管代理时(例如“如何开始”、“引导我创建一个代理”、“设置一个新代理”):读取shared/managed-agents-onboarding.md并运行其访谈 - 与managed-agents-onboard子命令相同的流程。
当用户询问“如何为 X 编写客户端代码”时: 找到shared/managed-agents-client-patterns.md- 涵盖无损流重新连接、processed_at排队/处理门、中断、tool_confirmation往返、正确的空闲/终止中断门、空闲后状态竞争、流优先排序、文件安装陷阱、通过自定义工具在主机端保留凭据等。
阅读指南
检测语言后,根据用户需求读取相关文件:
快速任务参考
单文本分类/摘要/提取/问答:
-> 只读{lang}/claude-api/README.md
聊天UI或实时回复显示:
-> 读取{lang}/claude-api/README.md+{lang}/claude-api/streaming.md
长时间运行的对话(可能超出上下文窗口):
-> 阅读{lang}/claude-api/README.md- 参见压缩部分
迁移到较新的型号(Opus 4.7 / Opus 4.6 / Sonnet 4.6)或更换已退役的型号:
-> 读取shared/model-migration.md
提示缓存/优化缓存/“为什么我的缓存命中率低”:
-> 读取shared/prompt-caching.md+{lang}/claude-api/README.md(提示缓存部分)
函数调用/工具使用/代理:
-> 读取{lang}/claude-api/README.md+shared/tool-use-concepts.md+{lang}/claude-api/tool-use.md
代理设计(工具界面、上下文管理、缓存策略):
-> 读取shared/agent-design.md
批处理(非延迟敏感):
-> 读取{lang}/claude-api/README.md+{lang}/claude-api/batches.md
跨多个请求上传文件:
-> 读取{lang}/claude-api/README.md+{lang}/claude-api/files-api.md
托管代理(具有工作区的服务器管理的有状态代理):
-> 读取shared/managed-agents-overview.md+shared/managed-agents-*.md文件的其余部分。对于 Python、TypeScript、Go、Ruby、PHP 和 Java,请阅读{lang}/managed-agents/README.md获取代码示例。对于 cURL,请阅读curl/managed-agents.md。 代理是持久性的 - 创建一次,通过 ID 引用。 存储agents.create返回的代理 ID,并将其传递给后续的每个sessions.create;不要在请求路径中调用agents.create。 Anthropic CLI 是从版本控制的 YAML(shared/live-sources.md中的 URL)创建代理和环境的一种便捷方法。如果语言 README 中未显示您需要的绑定,请从shared/live-sources.mdWeb 获取相关条目,而不是猜测。 C# 当前不支持托管代理 - 使用curl/managed-agents.md中的原始 HTTP 作为参考。
克劳德 API(完整文件参考)
阅读 特定于语言的 Claude API 文件夹 ({language}/claude-api/):
{language}/claude-api/README.md- 先阅读本文。 安装、快速启动、常见模式、错误处理。shared/tool-use-concepts.md- 当用户需要函数调用、代码执行、内存或结构化输出时读取。涵盖概念基础。shared/agent-design.md- 设计代理时阅读:bash 与专用工具、编程工具调用、工具搜索/技能、上下文编辑与压缩与内存、缓存原理。{language}/claude-api/tool-use.md- 阅读特定于语言的工具使用代码示例(工具运行程序、手动循环、代码执行、内存、结构化输出)。{language}/claude-api/streaming.md- 在构建增量显示响应的聊天 UI 或界面时阅读。{language}/claude-api/batches.md- 离线处理许多请求时读取(对延迟不敏感)。以 50% 的成本异步运行。{language}/claude-api/files-api.md- 在跨多个请求发送同一文件而无需重新上传时读取。shared/prompt-caching.md- 添加或优化提示缓存时阅读。涵盖前缀稳定性设计、断点放置以及静默使缓存失效的反模式。shared/error-codes.md- 在调试 HTTP 错误或实现错误处理时读取。shared/model-migration.md- 在升级到较新的模型、替换退役模型或将budget_tokens/ 预填充模式转换为当前 API 时阅读。shared/live-sources.md- 用于获取最新官方文档的 WebFetch URL。
注意: 对于 Java、Go、Ruby、C#、PHP 和 cURL - 这些都有一个文件,每个文件涵盖所有基础知识。根据需要读取该文件以及shared/tool-use-concepts.md和shared/error-codes.md。
注意: 有关托管代理文件参考,请参阅上面的## Managed Agents (Beta)部分 - 它列出了每个shared/managed-agents-*.md文件和特定于语言的自述文件。
何时使用 WebFetch
在以下情况下使用 WebFetch 获取最新文档:
- 用户询问“最新”或“当前”信息
- 缓存数据似乎不正确
- 用户询问此处未涵盖的功能
实时文档 URL 位于shared/live-sources.md中。
常见陷阱
- 将文件或内容传递到 API 时不要截断输入。如果内容太长而无法放入上下文窗口,请通知用户并讨论选项(分块、摘要等),而不是默默地截断。
- Opus 4.7 思考: 仅自适应。
thinking: {type: "enabled", budget_tokens: N}在 Opus 4.7 上返回 400 -budget_tokens在那里被完全删除(以及temperature、top_p、top_k)。使用thinking: {type: "adaptive"}。 - Opus 4.6 / Sonnet 4.6 思考: 使用
thinking: {type: "adaptive"}- 不要将budget_tokens用于新的 4.6 代码(在 Opus 4.6 和 Sonnet 4.6 上已弃用;要逐步迁移现有代码,请参阅shared/model-migration.md中的过渡逃生舱口 - 请注意,此剥离不适用于 Opus 4.7)。对于较旧的型号,budget_tokens必须小于max_tokens(最小 1024)。如果你弄错了,这会抛出一个错误。 - 4.6/4.7 系列预填充已删除: 助理消息预填充(最后一个助理轮次预填充)在 Opus 4.6、Opus 4.7 和 Sonnet 4.6 上返回 400 错误。使用结构化输出 (
output_config.format) 或系统提示指令来控制响应格式。 - 编辑前确认迁移范围:当用户要求将代码迁移到较新的 Claude 模型而不命名特定文件、目录或文件列表时,询问首先应用哪个范围 - 整个工作目录、特定子目录或特定文件集。在用户确认之前不要开始编辑。像“迁移我的代码库”、“将我的项目移动到 X”、“升级到 Sonnet 4.6”或简单的“迁移到 Opus 4.7”这样的命令式措辞仍然含糊不清 - 它们告诉你要做什么,但不告诉你在哪里,所以要问。仅当提示指定确切文件、特定目录或显式文件列表(“迁移
app.py”、“迁移services/下的所有内容”、“更新a.py和b.py”)时,才继续而不询问。请参阅shared/model-migration.md步骤 0。 max_tokens默认值: 不要低估max_tokens- 达到上限会截断输出,需要重试。对于非流式请求,默认为~16000(在 SDK HTTP 超时下保留响应)。对于流请求,默认为~64000(超时不是问题,因此请给模型空间)。仅当您有明确的理由时才降低:分类(~256)、成本上限或故意缩短产出。- 128K 输出令牌: Opus 4.6 和 Opus 4.7 支持高达 128K
max_tokens,但 SDK 需要对如此大的值进行流式传输以避免 HTTP 超时。将.stream()与.get_final_message()/.finalMessage()一起使用。 - 工具调用 JSON 解析(4.6/4.7 系列): Opus 4.6、Opus 4.7 和 Sonnet 4.6 可能会在工具调用
input字段中产生不同的 JSON 字符串转义(例如,Unicode 或正斜杠转义)。始终使用json.loads()/JSON.parse()解析工具输入 - 切勿对序列化输入进行原始字符串匹配。 - 结构化输出(所有型号): 使用
output_config: {format: {...}}代替messages.create()上已弃用的output_format参数。这是一般 API 更改,不是 4.6 特有的。 - 不要重新实现 SDK 功能: SDK 提供高级帮助程序 - 使用它们而不是从头开始构建。具体来说:使用
stream.finalMessage()而不是将.on()事件包装在new Promise()中;使用类型化异常类(Anthropic.RateLimitError等)而不是字符串匹配的错误消息;使用 SDK 类型(Anthropic.MessageParam、Anthropic.Tool、Anthropic.Message等)而不是重新定义等效接口。 - 不要为 SDK 数据结构定义自定义类型: SDK 导出所有 API 对象的类型。使用
Anthropic.MessageParam表示消息,Anthropic.Tool表示工具定义,Anthropic.ToolUseBlock/Anthropic.ToolResultBlockParam表示工具结果,Anthropic.Message表示响应。定义您自己的interface ChatMessage { role: string; content: unknown }会重复 SDK 已提供的内容并失去类型安全性。 - 报告和文档输出: 对于生成报告、文档或可视化的任务,代码执行沙箱预安装了
python-docx、python-pptx、matplotlib、pillow和pypdf。 Claude 可以生成格式化文件(DOCX、PDF、图表)并通过文件 API 返回它们 - 考虑将此用于“报告”或“文档”类型请求,而不是纯标准输出文本。
资源文件
许可证.txt
二进制资源
csharp/claude-api.md
二进制资源
卷曲/示例.md
二进制资源
卷曲/托管代理.md
二进制资源
去/claude-api.md
二进制资源
转到/托管代理/README.md
下载 go/managed-agents/README.md
二进制资源
java/claude-api.md
二进制资源
java/托管代理/README.md
二进制资源
php/claude-api.md
二进制资源
php/托管代理/README.md
二进制资源
python/claude-api/README.md
下载 python/claude-api/README.md
二进制资源
python/claude-api/batches.md
下载 python/claude-api/batches.md
# Message Batches API — Python
The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices.
## Key Facts
- Up to 100,000 requests or 256 MB per batch
- Most batches complete within 1 hour; maximum 24 hours
- Results available for 29 days after creation
- 50% cost reduction on all token usage
- All Messages API features supported (vision, tools, caching, etc.)
---
## Create a Batch
```python
进口人择
从 anthropic.types.message_create_params 导入 MessageCreateParamsNonStreaming
从 anthropic.types.messages.batch_create_params 导入请求
客户端 = anthropic.Anthropic()
message_batch = client.messages.batches.create(
请求=[
请求(
custom_id =“请求-1”,
参数=MessageCreateParamsNonStreaming(
型号=“claude-opus-4-7”,
最大令牌=16000,
messages=[{"role": "user", "content": "总结气候变化影响"}]
)
),
请求(
custom_id="请求-2",
参数=MessageCreateParamsNonStreaming(
型号=“claude-opus-4-7”,
最大令牌=16000,
messages=[{"role": "user", "content": "解释量子计算基础知识"}]
)
),
]
)
print(f"批次 ID: {message_batch.id}")
print(f"状态:{message_batch.processing_status}")Poll for Completion
导入时间
而真实:
批处理 = client.messages.batches.retrieve(message_batch.id)
如果batch.processing_status ==“结束”:
打破
print(f"状态:{batch.processing_status},处理中:{batch.request_counts.processing}")
时间.睡眠(60)
print("批量完成!")
print(f"成功:{batch.request_counts.succeeded}")
print(f"错误:{batch.request_counts.errored}")Retrieve Results
Note: Examples below use match/case syntax, requiring Python 3.10+. For earlier versions, use if/elif chains instead.
对于 client.messages.batches.results(message_batch.id) 中的结果:
匹配结果.结果.类型:
案例“成功”:
msg = 结果.结果.消息
text = next((b.text for b in msg.content if b.type == "text"), "")
打印(f“[{result.custom_id}] {文本[:100]}”)
案例“错误”:
如果 result.result.error.type == "invalid_request":
print(f"[{result.custom_id}] 验证错误 - 修复请求并重试")
其他:
print(f"[{result.custom_id}] 服务器错误 - 可以安全重试")
案件“取消”:
print(f"[{result.custom_id}] 已取消")
案例“过期”:
print(f"[{result.custom_id}] 已过期 - 重新提交")Cancel a Batch
取消 = client.messages.batches.cancel(message_batch.id)
print(f"状态:{cancelled.processing_status}") # "取消"Batch with Prompt Caching
共享系统 = [
{"type": "text", "text": "你是一名文学分析师。"},
{
“类型”:“文本”,
"text": large_document_text, # 在所有请求之间共享
“cache_control”:{“类型”:“短暂”}
}
]
message_batch = client.messages.batches.create(
请求=[
请求(
custom_id=f"分析-{i}",
参数=MessageCreateParamsNonStreaming(
型号=“claude-opus-4-7”,
最大令牌=16000,
系统=共享系统,
messages=[{“角色”:“用户”,“内容”:问题}]
)
)
对于我来说,枚举中的问题(问题)
]
)Full End-to-End Example
进口人择
导入时间
从 anthropic.types.message_create_params 导入 MessageCreateParamsNonStreaming
从 anthropic.types.messages.batch_create_params 导入请求
客户端 = anthropic.Anthropic()
# 1. 准备请求
要分类的项目 = [
“产品质量非常好!”,
“糟糕的客户服务,再也不会了。”,
“没事,没什么特别的。”,
]
请求= [
请求(
custom_id=f"分类-{i}",
参数=MessageCreateParamsNonStreaming(
模型=“claude-haiku-4-5”,
最大令牌数=50,
消息=[{
“角色”:“用户”,
"content": f"分类为正面/负面/中性(一个词):{text}"
}]
)
)
对于 i,枚举中的文本(items_to_classify)
]
# 2.创建批次
批处理 = client.messages.batches.create(requests=requests)
print(f"已创建批次:{batch.id}")
# 3.等待完成
而真实:
批处理 = client.messages.batches.retrieve(batch.id)
如果batch.processing_status ==“结束”:
打破
时间.睡眠(10)
# 4. 收集结果
结果={}
对于 client.messages.batches.results(batch.id) 中的结果:
如果 result.result.type == "成功":
msg = 结果.结果.消息
results[result.custom_id] = next((b.text for b in msg.content if b.type == "text"), "")
对于custom_id,在sorted(results.items())中进行分类:
打印(f“{custom_id}:{classification}”)
### python/claude-api/files-api.md
[下载 python/claude-api/files-api.md](/skills/claude-api/python/claude-api/files-api.md)
```markdown
# Files API — Python
The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.
**Beta:** Pass `betas=["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).
## Key Facts
- Maximum file size: 500 MB
- Total storage: 100 GB per organization
- Files persist until deleted
- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
- Not available on Amazon Bedrock or Google Vertex AI
---
## Upload a File
```python
进口人择
客户端 = anthropic.Anthropic()
已上传 = client.beta.files.upload(
file=("report.pdf", open("report.pdf", "rb"), "application/pdf"),
)
print(f"文件 ID:{uploaded.id}")
print(f"大小:{uploaded.size_bytes} 字节")Use a File in Messages
PDF / Text Document
响应 = client.beta.messages.create(
型号=“claude-opus-4-7”,
最大令牌=16000,
消息=[{
“角色”:“用户”,
“内容”:[
{"type": "text", "text": "总结本报告中的主要发现。"},
{
“类型”:“文档”,
"source": {"type": "file", "file_id": uploaded.id},
"title": "第四季度报告", # 可选
"itations": {"enabled": True} # 可选,启用引用
}
]
}],
betas=["files-api-2025-04-14"],
)
对于响应中的块。内容:
if block.type == "text":
打印(块.文本)Image
image_file = client.beta.files.upload(
文件=(“照片.png”,打开(“照片.png”,“rb”),“图像/ png”),
)
响应 = client.beta.messages.create(
型号=“claude-opus-4-7”,
最大令牌=16000,
消息=[{
“角色”:“用户”,
“内容”:[
{"type": "text", "text": "这张图片里有什么?"},
{
“类型”:“图像”,
"source": {"type": "file", "file_id": image_file.id}
}
]
}],
betas=["files-api-2025-04-14"],
)Manage Files
List Files
文件 = client.beta.files.list()
对于 files.data 中的 f:
print(f"{f.id}: {f.filename} ({f.size_bytes} 字节)")Get File Metadata
file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
print(f"文件名:{file_info.filename}")
print(f"MIME 类型:{file_info.mime_type}")Delete a File
client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")Download a File
Only files created by the code execution tool or skills can be downloaded (not user-uploaded files).
file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w")
file_content.write_to_file("输出.txt")Full End-to-End Example
Upload a document once, ask multiple questions about it:
进口人择
客户端 = anthropic.Anthropic()
# 1.上传一次
已上传 = client.beta.files.upload(
file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
)
print(f"已上传:{uploaded.id}")
# 2. 使用相同的 file_id 提出多个问题
问题=[
“主要条款和条件是什么?”,
“什么是终止条款?”,
“总结付款计划。”,
]
对于问题中的问题:
响应 = client.beta.messages.create(
型号=“claude-opus-4-7”,
最大令牌=16000,
消息=[{
“角色”:“用户”,
“内容”:[
{“类型”:“文本”,“文本”:问题},
{
“类型”:“文档”,
"source": {"type": "file", "file_id": uploaded.id}
}
]
}],
betas=["files-api-2025-04-14"],
)
print(f"\nQ: {question}")
text = next((b.text for b in response.content if b.type == "text"), "")
打印(f“A:{文本[:200]}”)
# 3.完成后清理
client.beta.files.delete(uploaded.id)
### python/claude-api/streaming.md
[下载 python/claude-api/streaming.md](/skills/claude-api/python/claude-api/streaming.md)
```markdown
# Streaming — Python
## Quick Start
```python
与 client.messages.stream(
型号=“claude-opus-4-7”,
最大令牌数=64000,
messages=[{"role": "user", "content": "写一个故事"}]
) 作为流:
对于stream.text_stream中的文本:
打印(文本,结束=“”,冲洗=真)Async
与 async_client.messages.stream 异步(
型号=“claude-opus-4-7”,
最大令牌数=64000,
messages=[{"role": "user", "content": "写一个故事"}]
) 作为流:
Stream.text_stream 中的文本异步:
打印(文本,结束=“”,冲洗=真)Handling Different Content Types
Claude may return text, thinking blocks, or tool use. Handle each appropriately:
Opus 4.7 / Opus 4.6: Use thinking: {type: "adaptive"}. On older models, use thinking: {type: "enabled", budget_tokens: N} instead.
与 client.messages.stream(
型号=“claude-opus-4-7”,
最大令牌数=64000,
思考={"type": "自适应"},
messages=[{"role": "user", "content": "分析这个问题"}]
) 作为流:
对于流中的事件:
if event.type == "content_block_start":
if event.content_block.type == "思考":
print("\n[思考...]")
elif event.content_block.type == "文本":
打印(“\n[响应:]”)
elif event.type == "content_block_delta":
if event.delta.type == "thinking_delta":
打印(event.delta.thinking,end =“”,flush = True)
elif event.delta.type == "text_delta":
打印(event.delta.text,end =“”,flush = True)Streaming with Tool Use
The Python tool runner currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools:
与 client.messages.stream(
型号=“claude-opus-4-7”,
最大令牌数=64000,
工具=工具,
消息=消息
) 作为流:
对于stream.text_stream中的文本:
打印(文本,结束=“”,冲洗=真)
响应=stream.get_final_message()
# 如果 response.stop_reason == "tool_use" 则继续执行工具Getting the Final Message
与 client.messages.stream(
型号=“claude-opus-4-7”,
最大令牌数=64000,
消息=[{“角色”:“用户”,“内容”:“你好”}]
) 作为流:
对于stream.text_stream中的文本:
打印(文本,结束=“”,冲洗=真)
# 流式传输后获取完整消息
最终消息=stream.get_final_message()
print(f"\n\n使用的令牌:{final_message.usage.output_tokens}")Streaming with Progress Updates
def stream_with_progress(客户端, **kwargs):
"""流式传输带有进度更新的响应。"""
总代币 = 0
内容部分 = []
使用 client.messages.stream(**kwargs) 作为流:
对于流中的事件:
if event.type == "content_block_delta":
如果 event.delta.type == "text_delta":
文本=事件.delta.文本
content_parts.append(文本)
打印(文本,结束=“”,冲洗=真)
elif event.type == "message_delta":
如果 event.usage 和 event.usage.output_tokens 不是 None:
Total_tokens = event.usage.output_tokens
最终消息=stream.get_final_message()
print(f"\n\n[使用的令牌:{total_tokens}]")
返回“”.join(content_parts)Error Handling in Streams
尝试:
与 client.messages.stream(
型号=“claude-opus-4-7”,
最大令牌数=64000,
messages=[{"role": "user", "content": "写一个故事"}]
) 作为流:
对于stream.text_stream中的文本:
打印(文本,结束=“”,冲洗=真)
除了 anthropic.APIConnectionError:
print("\n连接丢失。请重试。")
除了 anthropic.RateLimitError:
print("\n速率有限。请等待并重试。")
除了 anthropic.APIStatusError 为 e:
print(f"\nAPI 错误: {e.status_code}")Stream Event Types
| Event Type | Description | When it fires |
|---|---|---|
message_start | Contains message metadata | Once at the beginning |
content_block_start | New content block beginning | When a text/tool_use block starts |
content_block_delta | Incremental content update | For each token/chunk |
content_block_stop | Content block complete | When a block finishes |
message_delta | Message-level updates | Contains stop_reason, usage |
message_stop | Message complete | Once at the end |
Best Practices
- Always flush output — Use
flush=Trueto show tokens immediately - Handle partial responses — If the stream is interrupted, you may have incomplete content
- Track token usage — The
message_deltaevent contains usage information - Use timeouts — Set appropriate timeouts for your application
- Default to streaming — Use
.get_final_message()to get the complete response even when streaming, giving you timeout protection without needing to handle individual events
### python/claude-api/tool-use.md
[下载 python/claude-api/tool-use.md](/skills/claude-api/python/claude-api/tool-use.md)
_二进制资源_
### python/托管代理/README.md
[下载 python/托管代理/README.md](/skills/claude-api/python/托管代理/README.md)
_二进制资源_
### ruby/claude-api.md
[下载 ruby/claude-api.md](/skills/claude-api/ruby/claude-api.md)
```markdown
# Claude API — Ruby
> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby.
## Installation
```bash
gem 安装人类Client Initialization
要求“人为”
# 默认(使用 ANTHROPIC_API_KEY 环境变量)
客户端 = Anthropic::Client.new
# 显式 API 密钥
客户端 = Anthropic::Client.new(api_key: "your-api-key")Basic Message Request
消息 = client.messages.create(
型号::“claude-opus-4-7”,
最大令牌数:16000,
消息:[
{ role: "user", content: "法国的首都是哪里?" }
]
)
# content 是多态块对象的数组(TextBlock、ThinkingBlock、
# 工具使用块,...)。.type 是一个符号 — 与:text 比较,而不是“text”。
# .text 在非 TextBlock 条目上引发 NoMethodError。
message.content.each 做 |block|
如果 block.type ==:text 则放置 block.text
结束Streaming
流 = client.messages.stream(
型号::“claude-opus-4-7”,
最大令牌数:64000,
messages: [{ 角色: "用户", 内容: "写俳句" }]
)
Stream.text.each { |文本|打印(文本)}Tool Use
The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution.
Tool Runner (Beta)
类 GetWeatherInput < Anthropic::BaseModel
必需:位置,字符串,文档:“城市和州,例如加利福尼亚州旧金山”
结束
类 GetWeather < Anthropic::BaseTool
doc“获取某个位置的当前天气”
input_schema GetWeatherInput
def 调用(输入)
“#{input.location} 天气晴朗,气温为 72°F。”
结束
结束
客户端.beta.messages.tool_runner(
型号::“claude-opus-4-7”,
最大令牌数:16000,
工具:[GetWeather.new],
messages: [{ role: "user", content: "旧金山的天气怎么样?" }]
).each_message 执行 |message|
放置消息.内容
结束Manual Loop
See the shared tool use concepts for the tool definition format and agentic loop pattern.
Prompt Caching
system_: (trailing underscore — avoids shadowing Kernel#system) takes an array of text blocks; set cache_control on the last block. Plain hashes work via the OrHash type alias. For placement patterns and the silent-invalidator audit checklist, see shared/prompt-caching.md.
消息 = client.messages.create(
型号::“claude-opus-4-7”,
最大令牌数:16000,
系统_:[
{ 类型:“文本”,文本:long_system_prompt,cache_control:{ 类型:“短暂” } }
],
messages: [{ role: "用户", content: "总结要点" }]
)For 1-hour TTL: cache_control: { type: "ephemeral", ttl: "1h" }. There's also a top-level cache_control: on messages.create that auto-places on the last cacheable block.
Verify hits via message.usage.cache_creation_input_tokens / message.usage.cache_read_input_tokens.
### ruby/托管代理/README.md
[下载 ruby/托管代理/README.md](/skills/claude-api/ruby/托管代理/README.md)
_二进制资源_
### 共享/代理设计.md
[下载shared/agent-design.md](/skills/claude-api/shared/agent-design.md)
_二进制资源_
### 共享/错误代码.md
[下载shared/error-codes.md](/skills/claude-api/shared/error-codes.md)
_二进制资源_
### 共享/live-sources.md
[下载shared/live-sources.md](/skills/claude-api/shared/live-sources.md)
_二进制资源_
### 共享/托管代理-api-reference.md
[下载共享/托管代理-api-reference.md](/skills/claude-api/shared/托管代理-api-reference.md)
_二进制资源_
### 共享/托管代理-客户端-patterns.md
[下载共享/托管代理-客户端-模式.md](/skills/claude-api/shared/托管代理-客户端-模式.md)
_二进制资源_
### 共享/托管代理-core.md
[下载共享/托管代理核心.md](/skills/claude-api/shared/托管代理核心.md)
_二进制资源_
### 共享/托管代理环境.md
[下载共享/托管代理环境.md](/skills/claude-api/shared/托管代理环境.md)
_二进制资源_
### 共享/托管代理事件.md
[下载共享/托管代理事件.md](/skills/claude-api/shared/托管代理事件.md)
_二进制资源_
### 共享/托管代理内存.md
[下载共享/托管代理内存.md](/skills/claude-api/shared/托管代理内存.md)
_二进制资源_
### 共享/托管代理-multiagent.md
[下载共享/托管代理-multiagent.md](/skills/claude-api/shared/托管代理-multiagent.md)
_二进制资源_
### 共享/托管代理-onboarding.md
[下载共享/托管代理-onboarding.md](/skills/claude-api/shared/托管代理-onboarding.md)
_二进制资源_
### 共享/托管代理结果.md
[下载共享/托管代理-结果.md](/skills/claude-api/shared/托管代理-结果.md)
_二进制资源_
### 共享/托管代理-overview.md
[下载共享/托管代理-overview.md](/skills/claude-api/shared/托管代理-overview.md)
_二进制资源_
### 共享/托管代理工具.md
[下载共享/托管代理工具.md](/skills/claude-api/shared/托管代理工具.md)
_二进制资源_
### 共享/托管代理-webhooks.md
[下载共享/托管代理-webhooks.md](/skills/claude-api/shared/托管代理-webhooks.md)
```markdown
# Managed Agents — Webhooks
Anthropic can POST to your HTTPS endpoint when a Managed Agents resource changes state — an alternative to holding an SSE stream or polling. Payloads are **thin** (event type + resource IDs only); on receipt, fetch the resource for current state. Every delivery is HMAC-signed.
> **Direction matters.** This page covers *Anthropic → you* notifications about session/vault state. It does **not** cover *third-party → you* webhooks that *trigger* a session (e.g. a GitHub push handler that calls `sessions.create()`) — that's ordinary application code on your side with no Anthropic-specific wire format.
---
## Register an endpoint (Console only)
Console → **Manage → Webhooks**. There is no programmatic endpoint-management API yet. Secret rotation is supported from the same page.
| Field | Constraint |
|---|---|
| URL | HTTPS on port 443, publicly resolvable hostname |
| Event types | Subscribe per `data.type` — you only receive subscribed types (plus test events) |
| Signing secret | `whsec_`-prefixed, 32 bytes, **shown once at creation** — store it |
---
## Verify the signature
Every delivery is HMAC-signed. **Use the SDK's `client.beta.webhooks.unwrap()`** — it verifies the signature, rejects payloads more than ~5 minutes old, and returns the parsed event. It reads the `whsec_` secret from `ANTHROPIC_WEBHOOK_SIGNING_KEY`.
```python
进口人择
从烧瓶导入烧瓶,请求
client = anthropic.Anthropic() # 从 env 读取 ANTHROPIC_WEBHOOK_SIGNING_KEY
应用程序=烧瓶(__名称__)
@app.route("/webhook",methods=["POST"])
def webhook():
尝试:
事件 = client.beta.webhooks.unwrap(
request.get_data(as_text=True),
headers=dict(request.headers),
)
除了例外:
返回“无效签名”,400
if event.id in saw_event_ids: # 重复数据删除重试 — id 是每个事件,而不是每个交付
返回“”,204
saw_event_ids.add(event.id)
匹配事件.数据.类型:
案例“session.status_idled”:
会话 = client.beta.sessions.retrieve(event.data.id)
通知用户(会话)
案例“vault_credential.refresh_failed”:
Alert_oncall(事件.data.id)
返回“”,204Pass the raw request body to unwrap() — frameworks that re-serialize JSON (Express .json(), Flask .get_json()) change the bytes and break the MAC. For other languages, look up the beta.webhooks.unwrap binding in the SDK repo (shared/live-sources.md); don't hand-roll verification.
Payload envelope
{
“类型”:“事件”,
"id": "event_01ABC...",
“创建时间”:“2026-03-18T14:05:22Z”,
“数据”:{
"type": "session.status_idled",
"id": "session_01XYZ...",
"organization_id": "8a3d2f1e-...",
“workspace_id”:“c7b0e4d9-...”
}
}Switch on data.type, fetch the resource by data.id, return any 2xx to acknowledge. created_at is when the state transition happened, not when the webhook fired.
Supported data.type values
data.type | Fires when |
|---|---|
session.status_scheduled | Session created and ready to accept events |
session.status_run_started | Agent execution kicked off (every transition to running) |
session.status_idled | Agent awaiting input (tool approval, custom tool result, or next message) |
session.status_terminated | Session hit a terminal error |
session.thread_created | Multiagent: coordinator opened a new subagent thread |
session.thread_idled | Multiagent: a subagent thread is waiting for input |
session.outcome_evaluation_ended | Outcome grader finished one iteration |
vault.archived | Vault was archived |
vault.created | Vault was created |
vault.deleted | Vault was deleted |
vault_credential.archived | Vault credential was archived |
vault_credential.created | Vault credential was created |
vault_credential.deleted | Vault credential was deleted |
vault_credential.refresh_failed | MCP OAuth vault credential failed to refresh |
These are webhook data.type values — a separate namespace from SSE event types (session.status_idle, span.outcome_evaluation_end, etc. in shared/managed-agents-events.md). Don't reuse SSE constants in webhook handlers.
Delivery behavior & pitfalls
- No ordering guarantee.
session.status_idledmay arrive beforesession.outcome_evaluation_endedeven if the evaluation finished first. Sort by envelopecreated_atif order matters. - Retries carry the same
event.id. At least one retry on non-2xx. Dedupe onevent.id. - 3xx is failure. Redirects are not followed — update the URL in Console if your endpoint moves.
- Auto-disable after ~20 consecutive failed deliveries, or immediately if the hostname resolves to a private IP or returns a redirect. Re-enable manually in Console.
- Thin payload is intentional. Don't expect
stop_reason,outcome_evaluations, credential secrets, etc. on the webhook body — fetch the resource.
### 共享/模型迁移.md
[下载shared/model-migration.md](/skills/claude-api/shared/model-migration.md)
_二进制资源_
### 共享/models.md
[下载shared/models.md](/skills/claude-api/shared/models.md)
_二进制资源_
### 共享/提示缓存.md
[下载shared/prompt-caching.md](/skills/claude-api/shared/prompt-caching.md)
_二进制资源_
### 共享/工具使用概念.md
[下载shared/tool-use-concepts.md](/skills/claude-api/shared/tool-use-concepts.md)
_二进制资源_
### 打字稿/claude-api/README.md
[下载 typescript/claude-api/README.md](/skills/claude-api/typescript/claude-api/README.md)
_二进制资源_
### 打字稿/claude-api/batches.md
[下载 typescript/claude-api/batches.md](/skills/claude-api/typescript/claude-api/batches.md)
```markdown
# Message Batches API — TypeScript
The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices.
## Key Facts
- Up to 100,000 requests or 256 MB per batch
- Most batches complete within 1 hour; maximum 24 hours
- Results available for 29 days after creation
- 50% cost reduction on all token usage
- All Messages API features supported (vision, tools, caching, etc.)
---
## Create a Batch
```typescript
从“@anthropic-ai/sdk”导入 Anthropic;
const client = new Anthropic();
const messageBatch = 等待 client.messages.batches.create({
请求:[
{
custom_id: "请求-1",
参数:{
型号:“claude-opus-4-7”,
最大令牌数:16000,
消息:[
{ role: "user", content: "总结气候变化影响" },
],
},
},
{
custom_id: "请求-2",
参数:{
型号:“claude-opus-4-7”,
最大令牌数:16000,
消息:[
{ role: "user", content: "讲解量子计算基础知识" },
],
},
},
],
});
控制台.log(`Batch ID: ${messageBatch.id}`);
控制台.log(`Status: ${messageBatch.processing_status}`);Poll for Completion
让批次;
而(真){
批处理=等待client.messages.batches.retrieve(messageBatch.id);
if (batch.processing_status === "结束") 中断;
控制台.日志(
`Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}`,
);
等待新的 Promise((resolve) => setTimeout(resolve, 60_000));
}
console.log("批量完成!");
控制台.log(`Succeeded: ${batch.request_counts.succeeded}`);
控制台.log(`Errored: ${batch.request_counts.errored}`);Retrieve Results
对于等待(等待 client.messages.batches.results 的 const 结果(
messageBatch.id,
)){
开关(结果.结果.类型){
案例“成功”:
控制台.日志(
`[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`,
);
休息;
案例“错误”:
if (result.result.error.type === "invalid_request") {
控制台.log(`[${result.custom_id}] Validation error - fix and retry`);
} 否则{
控制台.log(`[${result.custom_id}] Server error - safe to retry`);
}
休息;
案例“过期”:
控制台.log(`[${result.custom_id}] Expired - resubmit`);
休息;
}
}Cancel a Batch
const 取消=等待 client.messages.batches.cancel(messageBatch.id);
控制台.log(`Status: ${cancelled.processing_status}`); //“取消”
### 打字稿/claude-api/files-api.md
[下载 typescript/claude-api/files-api.md](/skills/claude-api/typescript/claude-api/files-api.md)
```markdown
# Files API — TypeScript
The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.
**Beta:** Pass `betas: ["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).
## Key Facts
- Maximum file size: 500 MB
- Total storage: 100 GB per organization
- Files persist until deleted
- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
- Not available on Amazon Bedrock or Google Vertex AI
---
## Upload a File
```typescript
从“@anthropic-ai/sdk”导入 Anthropic, { toFile };
从“fs”导入 fs;
const client = new Anthropic();
const uploaded = 等待 client.beta.files.upload({
文件:await toFile(fs.createReadStream(“report.pdf”),未定义,{
类型:“应用程序/pdf”,
}),
测试版:[“files-api-2025-04-14”],
});
控制台.log(`File ID: ${uploaded.id}`);
控制台.log(`Size: ${uploaded.size_bytes} bytes`);Use a File in Messages
PDF / Text Document
const 响应 = 等待 client.beta.messages.create({
型号:“claude-opus-4-7”,
最大令牌数:16000,
消息:[
{
角色:“用户”,
内容:[
{ type: "text", text: "总结本报告中的主要发现。" },
{
类型:“文档”,
来源: { type: "file", file_id: uploaded.id },
标题:“第四季度报告”,
引用:{启用:true},
},
],
},
],
测试版:[“files-api-2025-04-14”],
});
console.log(response.content[0].text);Manage Files
List Files
const 文件 = 等待 client.beta.files.list({
测试版:[“files-api-2025-04-14”],
});
for (const f of files.data) {
控制台.log(`${f.id}: ${f.filename} (${f.size_bytes} bytes)`);
}Delete a File
等待 client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w", {
测试版:[“files-api-2025-04-14”],
});Download a File
const 响应 = 等待 client.beta.files.download(
“file_011CNha8iCJcU1wXNR6q4V8w”,
{ betas: ["files-api-2025-04-14"] },
);
const content = Buffer.from(await response.arrayBuffer());
等待 fs.promises.writeFile("output.txt", 内容);
### 打字稿/claude-api/streaming.md
[下载 typescript/claude-api/streaming.md](/skills/claude-api/typescript/claude-api/streaming.md)
```markdown
# Streaming — TypeScript
## Quick Start
```typescript
const 流 = client.messages.stream({
型号:“claude-opus-4-7”,
最大令牌数:64000,
消息:[{角色:“用户”,内容:“写一个故事”}],
});
for等待(流的常量事件){
如果(
event.type ===“content_block_delta”&&
event.delta.type ===“text_delta”
){
process.stdout.write(event.delta.text);
}
}Handling Different Content Types
Opus 4.7 / Opus 4.6: Use thinking: {type: "adaptive"}. On older models, use thinking: {type: "enabled", budget_tokens: N} instead.
const 流 = client.messages.stream({
型号:“claude-opus-4-7”,
最大令牌数:64000,
思考:{ 类型:“自适应” },
messages: [{ role: "user", content: "分析这个问题" }],
});
for等待(流的常量事件){
开关(事件类型){
案例“content_block_start”:
开关 (event.content_block.type) {
案例“思考”:
console.log("\n[思考...]");
休息;
案例“文本”:
console.log("\n[响应:]");
休息;
}
休息;
案例“content_block_delta”:
开关 (event.delta.type) {
案例“thinking_delta”:
process.stdout.write(event.delta.thinking);
休息;
案例“text_delta”:
process.stdout.write(event.delta.text);
休息;
}
休息;
}
}Streaming with Tool Use (Tool Runner)
Use the tool runner with stream: true. The outer loop iterates over tool runner iterations (messages), the inner loop processes stream events:
从“@anthropic-ai/sdk”导入 Anthropic;
从“@anthropic-ai/sdk/helpers/beta/zod”导入{ betaZodTool };
从“zod”导入{z};
const client = new Anthropic();
const getWeather = betaZodTool({
名称:“获取天气”,
描述:“获取某个位置的当前天气”,
输入模式: z.object({
location: z.string().describe("城市和州,例如加利福尼亚州旧金山"),
}),
运行: async ({ location }) =>`72°F and sunny in ${location}`,
});
const runner = client.beta.messages.toolRunner({
型号:“claude-opus-4-7”,
最大令牌数:64000,
工具:[获取天气]、
消息:[
{ role: "user", content: "巴黎和伦敦的天气怎么样?" },
],
流:真实,
});
// 外循环:每个工具运行器迭代
for wait (runner 的 const messageStream) {
// 内部循环:本次迭代的流事件
for wait (messageStream 的 const 事件) {
开关(事件类型){
案例“content_block_delta”:
开关 (event.delta.type) {
案例“text_delta”:
process.stdout.write(event.delta.text);
休息;
案例“input_json_delta”:
// 工具输入正在流式传输
打破;
}
休息;
}
}
}Getting the Final Message
const 流 = client.messages.stream({
型号:“claude-opus-4-7”,
最大令牌数:64000,
消息:[{角色:“用户”,内容:“你好”}],
});
for等待(流的常量事件){
// 处理事件...
}
const FinalMessage =等待流.finalMessage();
控制台.log(`Tokens used: ${finalMessage.usage.output_tokens}`);Stream Event Types
| Event Type | Description | When it fires |
|---|---|---|
message_start | Contains message metadata | Once at the beginning |
content_block_start | New content block beginning | When a text/tool_use block starts |
content_block_delta | Incremental content update | For each token/chunk |
content_block_stop | Content block complete | When a block finishes |
message_delta | Message-level updates | Contains stop_reason, usage |
message_stop | Message complete | Once at the end |
Best Practices
- Always flush output — Use
process.stdout.write()for immediate display - Handle partial responses — If the stream is interrupted, you may have incomplete content
- Track token usage — The
message_deltaevent contains usage information - Use
finalMessage()— Get the completeAnthropic.Messageobject even when streaming. Don't wrap.on()events innew Promise()—finalMessage()handles all completion/error/abort states internally - Buffer for web UIs — Consider buffering a few tokens before rendering to avoid excessive DOM updates
- Use
stream.on("text", ...)for deltas — Thetextevent provides just the delta string, simpler than manually filteringcontent_block_deltaevents - For agentic loops with streaming — See the Streaming Manual Loop section in tool-use.md for combining
stream()+finalMessage()with a tool-use loop
Raw SSE Format
If using raw HTTP (not SDKs), the stream returns Server-Sent Events:
事件:message_start
数据:{“type”:“message_start”,“message”:{“id”:“msg_...”,“type”:“message”,...}}
事件:内容块开始
数据:{“type”:“content_block_start”,“index”:0,“content_block”:{“type”:“text”,“text”:“”}}
事件:内容块增量
数据:{“type”:“content_block_delta”,“index”:0,“delta”:{“type”:“text_delta”,“text”:“你好”}}
事件:内容块停止
数据:{“类型”:“content_block_stop”,“索引”:0}
事件:message_delta
数据:{“type”:“message_delta”,“delta”:{“stop_reason”:“end_turn”},“usage”:{“output_tokens”:12}}
事件:message_stop
数据:{“type”:“message_stop”}
### 打字稿/claude-api/tool-use.md
[下载 typescript/claude-api/tool-use.md](/skills/claude-api/typescript/claude-api/tool-use.md)
_二进制资源_
### 打字稿/托管代理/README.md
[下载 typescript/托管代理/README.md](/skills/claude-api/typescript/托管代理/README.md)
_二进制资源_
## 参见 GitHub
[参见 GitHub](https://github.com/anthropics/skills/tree/main/claude-api)
claudeskills文档