Claude 平台 101：从一次 API 调用到一个托管代理

一句话

聊天和做应用是两种技能。Claude Platform 101 从第一性原理讲起：一个 API 请求里有什么、代理循环是什么、上下文窗口怎样限制 Claude 能看到的东西、工具和权限怎样限制它能做的事。然后手写一个代理循环，再用 SDK 的 Tool Runner 替换它；接着扩展到内置工具、Skills、MCP 和上下文管理；最后把循环交给 Anthropic，构建一个托管代理（Managed Agent）。每节课都有可运行的 TypeScript 示例。

这篇导读覆盖的课程

• Claude Platform 101 —— 5 个单元 + 测验；示例用 TypeScript SDK

课程结构

什么是 Claude 平台

平台全景；第一次 API 调用；按成本和延迟选 Opus、Sonnet 或 Haiku。

教会你的代理 · Teaching your Agent

代理循环原理；工具调用；扩展思考。

扩展你的代理 · Extending your Agent

内置工具（网页搜索、代码执行、网页抓取）；Skills；MCP；上下文管理。

托管代理 · Managed Agents

什么时候自己跑循环、什么时候交给 Anthropic；端到端构建第一个托管代理。

用 Claude Code 开发

让 Claude Code 帮你写 API 代码，以及你为什么仍需要懂这些代码。

精华：这门课真正要你带走的东西

一个请求 = 模型 + 指令 + 消息 + 工具。API 是无状态的：每次请求都要带上完整的对话历史。你发送 model、max_tokens、可选的 system（系统提示）、messages（对话历史）和可选的 tools（工具定义）。返回结果里的 stop_reason 告诉你模型为什么停下：说完了、到长度上限了，还是要调用工具。

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const msg = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "用一句话解释什么是 API。" }],
});
console.log(msg.content[0].text);

选模型靠实验，不靠猜。Opus 能力最强、最贵最慢；Haiku 最快最便宜；Sonnet 居中。课程建议拿你自己的真实样例，在几个模型上各跑一遍，比较质量、延迟和成本，再决定。很多任务用小模型就够了。

代理循环其实只有几行。手写一遍你就会明白：把用户请求和工具定义发给 Claude；如果 stop_reason 是 tool_use，你的代码执行对应工具，把结果作为 tool_result 加入消息再发回去；重复，直到 Claude 不再调用工具。模型负责决定，你的代码负责执行。理解这一点后，再用 SDK 的 Tool Runner，它替你写好了这个循环。

工具和思考是代理的两条腿。工具调用让 Claude 能查数据库、调接口、读文件，从“会说”变成“会做”。扩展思考让 Claude 在回答前先推理，适合复杂问题，代价是更多词元和更长延迟。

4 种扩展方式。内置工具：网页搜索、网页抓取、代码执行在 Anthropic 的服务器上运行，你不用自己实现。Skills：把一套流程打包一次，在多次调用中复用。MCP：直接连接第三方 MCP 服务器，不用自己写工具定义。上下文管理：长时间运行的代理会撑满上下文，要用压缩、清理旧工具结果、提示词缓存等办法，让它在第十轮之后依然放得下、付得起。

自己跑循环，还是交给托管代理？Messages API 给你完全控制，适合自定义循环和精细调度。托管代理由 Anthropic 提供现成的代理框架和云端沙盒：你定义代理（模型、提示、工具、MCP、Skills）和环境，启动会话，发送事件，通过事件流接收它的进展。适合跑几分钟到几小时的长任务和异步任务。官方文档目前把托管代理标注为 beta。

为什么还要学原理。最后一课演示用 Claude Code 写 API 代码。课程的立场是：代理可以替你写代码，但你得知道好代码长什么样，才能审查它写的东西。

关键概念

Messages API

Claude 的核心接口。发送对话消息，返回模型回复；无状态，每次都要带完整历史。

stop_reason

回复结束的原因，例如 end_turn（说完）、max_tokens（到上限）、tool_use（要调用工具）。

工具调用（tool use）

你用 JSON Schema 描述工具，Claude 决定何时调用、传什么参数，你的代码执行后返回结果。

Tool Runner

SDK 提供的辅助功能，自动完成“调用工具—返回结果—再请求”的循环。

扩展思考（extended thinking）

让模型在给出答案前进行可见的推理，提升复杂任务表现。

内置工具（server tools）

在 Anthropic 服务器端执行的工具，如网页搜索、网页抓取、代码执行。

Workspaces 与 Workbench

控制台里的功能：前者按项目隔离 API 密钥和花费上限，后者用来在线调试提示词。

托管代理（Managed Agents）

Anthropic 托管的代理框架和运行环境，由代理、环境、会话、事件 4 个概念组成。

学前准备

• 至少会读写一种编程语言，会用命令行。
• 课程示例用 TypeScript（Node + npm）。不必精通，能跟着跑脚本即可。也有 Python SDK。
• Anthropic 控制台账号（platform.claude.com）、API 密钥和少量预付额度。
• 不需要做过大模型应用。

动手练一遍

1. 第一次调用：运行上面的示例代码。把返回对象完整打印出来，找到 stop_reason 和 usage 两个字段。
2. 比较模型：准备 5 条你产品里的真实问题，分别用 Haiku、Sonnet、Opus 回答。做一张表：质量打分、耗时、词元数。
3. 手写代理循环：定义一个 get_weather 工具（返回假数据即可），写一个 while 循环处理 tool_use，直到 Claude 给出最终回答。打印每一轮的消息。
4. 换成 Tool Runner：用 SDK 的 Tool Runner 重写第 3 步，对比代码行数。
5. 加内置工具：启用网页搜索工具，问一个需要最新信息的问题，观察返回中的引用。

容易卡住的地方

• 以为 API 会记住上一轮对话。API 无状态，历史要自己带上。
• 一开始就用最贵的模型。先用真实样例比较，很多任务小模型足够。
• 忘了在下一轮请求里带上 tool_result。Claude 收不到工具结果，就会重复调用或卡住。
• 长对话不做上下文管理。轮数一多，成本和延迟会快速上升。
• 把 API 密钥写进前端代码或提交到仓库。密钥只放在服务器端环境变量里。

延伸阅读

• Claude 平台文档首页 —— API、SDK 和功能的完整文档（英文）
• 工具调用概览 —— 工具定义、客户端工具和服务器工具（英文）
• 托管代理概览 —— 代理、环境、会话、事件 4 个概念（英文）
• Anthropic：构建有效的代理 —— 工作流与代理的经典区分（英文）
• 下一篇：用 Claude API 构建应用 —— 更全面的 API 课程，含提示词评估和 RAG

← 返回课程目录