EP04. "Claude Platform 101：从第一次 API 调用到 Managed Agents"

• Anthropic 官方 Claude Platform 101 课程，13 节课 + 1 个结业测验，官方标注约 1.5 小时，教的是用代码调用 Claude（也就是 Claude API，官方现在统称 Claude Platform），不是网页聊天、也不是 Claude Code 这个终端工具
• 跟前三篇（EP01~EP03）的分工不一样：那三篇讲的是「怎么用好 Claude 这个产品」，这篇讲的是「怎么把 Claude 的能力写进自己的程序/产品里」——面向会写代码、想接 API 做开发的读者
• 从发出第一个 API request，讲到怎么挑模型、Agent Loop 怎么手写、Tool Use、Extended Thinking、官方内建工具、Skills、MCP、上下文管理，最后到 Managed Agents（把整个 Agent Loop 托管在 Anthropic 服务器上跑）
• 前置知识：官方定位「做过几次 API 调用，或者只在聊天窗口用过 Claude 的人都能学」，不需要很深的开发经验，但看得懂代码会顺很多

重点内容

---

Claude Platform 是什么：三层架构

跟浏览器里聊天不一样，Platform 让你「从代码发出结构化的请求，拿到结构化的回应，每个细节都能自己控制」。组成部分：REST API（任何语言都能调）、多语言 SDK、命令行工具、还有一个 Console（管 API key、看用量、部署 managed agent、测试 prompt）。

三层架构，官方口诀是「用 primitives 搭，靠 infrastructure 撑规模，靠 controls 管生产环境」：

举例：客服工单系统接 Claude——用 Messages API，选 Claude Haiku（简单任务用便宜快的模型）、设 token 上限、写 system 指令定语气和规范、传入工单内容当 user message，API 会回一份草稿回复，人审核后再发出去。

---

第一次 API 调用

先做设置：去 platform.claude.com 拿一个 API key（需要预付额度），存进 .env.local 文件、不要直接写死在代码里——⚠️「把 key 写死在源码里，是它们最后被泄漏到 GitHub 上最常见的原因」；装 SDK 用 npm install @anthropic-ai/sdk。

每个 API 调用都要有三个要素：

1. model——指定用哪个版本的 Claude 处理这次请求
2. max_tokens——限制回复最长多少
3. messages——一个对话对象的数组，每个带 role（user 或 assistant）

实例：代码审查。用 TypeScript 让 Claude 审查一段写错的代码（一个明明是减法却取名叫 add 的函数）：

• system prompt 写「You are a terse senior code reviewer. Give feedback in one paragraph.」（你是一个说话简洁的资深代码审查员，用一段话给反馈）
• 回应的 content 是一个 block 数组，要检查每个 block 的 type，循环找出 text 类型的部分
• Claude 正确抓到问题：「函数叫 add，但用的是减法逻辑」

从脚本到产品：同一个 messages.create() 模式能撑起正式产品功能，比如会议记录自动摘要——从数据库取资料、丢给 API 处理、把结果存回去，都是同一套架构反复用。

---

怎么选模型

选最强的模型成本容易爆表，选最便宜的又可能质量不够——「每个模型的取舍不一样，选对了会同时影响质量和成本」。

四个档位（用 model 参数指定）：

上线前先搭一个简易评估（Eval）：从实际工作负载里挑 20-30 个有代表性的例子，跑过每个模型，按「这个场景下好的输出长什么样」打分。流程：先用 Haiku 跑一遍，够用就停在这里省成本；不够用才升级到 Sonnet；只有任务真的需要才动用 Opus。

对比不同档位（Python）：

models = ["claude-haiku-4-5", "claude-sonnet-5", "claude-opus-5"]

for model in models:
    response = client.messages.create(
        model=model,
        max_tokens=300,
        messages=[{"role": "user", "content": prompt}],
    )
    print(model, response.usage)

循环只换 model 字段，其他条件全部一样，response.usage 会直接给出这次请求花的 input/output token 数——账单就是照这个算的。实测观察：Opus 最慢但产出最精致，Sonnet 写得更紧凑，Haiku 常常一秒内就给出还不错的回应。核心原则：「对的模型，是你真的敢拿去上线的输出里，最便宜的那一个。」

不是整个产品只用一个模型，按任务路由：一个运营看板的例子——每个新进来的文件先用 Haiku 分类；客户更新用 Sonnet 起草；只有 RFP（招标响应）这类真正复杂的任务才动用 Opus。一条队列，三个模型，按任务各自分派。

---

Agent Loop 是什么

Agent 就是 Claude 在一个消息循环里自主运作，不需要人在中间插手：接到任务、选合适的工具、迭代执行代码直到完成。实作套路：

1. 发一条带「可用工具清单」的消息给 Claude
2. Claude 回「最终答案」或「请求调用某个工具」
3. 你的代码执行这个工具请求
4. 把结果传回给 Claude
5. 重复，直到 stop_reason 变成 end_turn

最小可跑示例（Python，查天气场景）：定义一个 tools 数组（含 name/description/输入 JSON schema）；写一个 run_tool 函数（写死的查找逻辑模拟工具执行，正式产品会接真的数据库/API）；Agent Loop 反复发消息、检查 stop_reason——遇到 tool_use 就执行工具、把结果塞回消息历史；遇到 end_turn 就代表任务做完了。实测跑两轮：第一轮 stop_reason = tool_use（Claude 要奥斯汀的天气数据），第二轮 stop_reason = end_turn（Claude 根据天气结果给出穿衣建议）。

正式产品的循环结构完全一样，只是工具是真的、结果会用 server-sent event 串流给前端界面、数据会存进数据库（比如合规审查场景里的风险发现记录）。

---

Tool Use：工具怎么定义

工具就是「你自己定义、暴露给 Claude 用的一个函数」——Claude 请求调用，你的代码执行，结果传回给 Claude 继续处理。

工具定义用 JSON schema，三部分：name、description、input_schema。description 尤其关键——Claude 靠读这段文字判断这个工具该不该用，⚠️「描述写得含糊」是 agent 表现失常的头号原因。

{
  "name": "lookup_building_code",
  "description": "Look up a specific building code section by its identifier...",
  "input_schema": {
    "type": "object",
    "properties": {"...": "..."},
    "required": ["section"]
  }
}

Claude 判断要用工具时会回 stop_reason: "tool_use"，你的代码要：执行对应函数 → 把结果包成 tool result block（对应回原本的 tool call ID）传回去 → Claude 继续处理。

多个工具：Claude 会自己根据每个工具的描述挑合适的用，加新工具只需要往 tools 数组里加一条、再加一个对应的处理分支。

Tool Runner：SDK 自带的辅助工具，能直接从你写的函数生成 schema，不用手写 JSON schema、也不用自己管循环——TypeScript/Python/Ruby/C#/Go/Java/PHP 都支持。

---

Extended Thinking：让 Claude 先想再答

Extended Thinking（扩展思考）让 Claude 在正式回答前生成一段内部推理——「思维链」（chain of thought），这段推理会跟最终答案一起呈现，过程是透明的。

Opus 5 上默认是自适应思考，不用手动配置 token 预算，Claude 自己判断要想多少。控制思考深度的是 output_config 底下的 effort 参数，五档：low／medium／high（默认）／xhigh／max。

什么时候该用：数学和多步骤逻辑、代码调试、法规分析、权衡比较这类任务。什么时候该跳过：简单分类、抽取、样板化任务——这类场景思考「只会加延迟和成本，不会真正改善结果」。

实例（Python）：一个带天气工具、规划旧金山公路旅行的 agent loop，配置 model: claude-opus-5、thinking: {"type": "adaptive", "display": "summarized"}，输出里会同时看到 thinking block、工具调用、最终建议。生产环境的价值：能帮 agent 把散落在不同上下文里的发现串起来——比如合规审查里发现文档不同章节之间互相矛盾，单独分析很容易漏掉。

---

内建工具：不用自己写、不用自己托管

Anthropic 提供几个现成工具，「你不用写代码、不用自己托管沙盒环境，只要声明要用这个工具，Anthropic 负责跑」。

Server tools（跑在 Anthropic 服务器上）：

• Web search——带引用来源的联网搜索
• Code execution——Python 沙盒执行环境
• Web fetch——抓取 URL 内容

关键区别：「这些不是你执行的——是 Anthropic 执行的，意味着这类调用不需要你自己管 agent loop」。

# Web search
tools=[{"type": "web_search_20260209", "name": "web_search"}]

# Code execution
tools=[{"type": "code_execution_20260120", "name": "code_execution"}]

回应里会看到 server_tool_use（工具调用）、bash_code_execution_tool_result（执行输出）、普通 text block（Claude 的文字回应）——结果已经包含在回应里，不用自己再手动跑一轮 agent loop 去处理。

Client tools（跑在你自己的应用环境里）：Memory（跨会话持久化）、Bash（持久化的 shell 执行）。

生产场景：Web search 能撑起一个「事实核查」端点，把草稿里每一个数字和法规相关的说法都拿去跟实时网络内容核对——⚠️ 但核实的准确度本身仍然要留意。

---

Skills（Platform 版）：教 Claude 怎么做，不是给它工具

跟 Tool 的区别：Tool 负责让 Claude 接上外部数据和动作（「查这个法条」「发这封邮件」），管的是 Claude 能做什么；Skill 是教 Claude 照着某套流程走的「playbook」，把组织的偏好和工作流程直接写进去（「照这个模板生成每日状态报告」），管的是要怎么做。

渐进式载入：一开始只载入 Skill 的名字和描述，agent 判断确实需要用到，才把完整内容载进上下文——就算挂了很多个 Skill，上下文也能保持精简。

上传（一次性，存进 workspace）：

skill = client.skills.create(
    display_name="Status Report Generator",
    files=files_from_dir("status-report-skill"),
)
print(skill.id)

挂到请求上（用 container.skills）：

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "custom", "skill_id": skill.id, "version": "latest"}
        ]
    },
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[{
        "role": "user",
        "content": f"Generate the daily status report from this activity log:\n\n{activity_log}",
    }],
)

几个实作细节：不需要额外的 beta header，Skills 在 Claude API 上已经是正式功能（不是测试版）；container.skills 是个列表，一次请求能叠加多个 Skill；必须开着 Code Execution——Skill 是在 code execution 工具的容器里运行的，这样才能真正执行操作，不只是纸上谈兵。

实例：一个状态报告生成器，章节结构、语气、遇到卡点怎么写这些组织内部标准，全部放进 Skill 本身，而不是每次都在 prompt 里重新交代——不管谁点「Generate report」按钮，产出格式都是统一的。

---

MCP（Platform 版）：接别人维护的服务

要解决的问题：假设 agent 要一口气从 Asana 拉任务、查 Google Calendar、搜 Slack——与其自己维护这些整合，MCP 把维护责任转移给服务提供方：Asana 自己发布一个 MCP server，Slack 也发布一个。

Tool／Skill／MCP 三者怎么分：

官方总结：「Tools 管你自己的东西，Skills 管你的流程，MCP 管别人的东西。」

接一个 MCP server（以 Linear 为例）：用 mcp_servers 这个 key 声明连接（带 type、URL、名字、认证 token），在 tools 数组里配 mcp_toolset 控制能用哪些工具，Claude 能自己内省这个 server、自动发现有哪些工具可用。

过滤工具权限：可以先把所有工具默认关掉，再手动开需要的——比如 Slack 只开 search_messages、list_channels，避免 Claude 不小心执行你不想要的写入类操作。

---

Context Management（Platform 版）：四种管理手法

什么算「上下文」：「Claude 在这一轮里看到的所有东西」——system prompt、消息历史、工具定义和工具结果、附加的文件和 Skill、thinking block。input 和 output 都会消耗上下文，窗口满了请求就会失败，策略目标是「塞进对的东西」，不是塞进所有东西。

四种手法：

生产环境通常四种手法叠加使用，各自解决不同的问题：成本、窗口大小、无状态这三个层面。

---

Managed Agents 是什么

Claude Managed Agents 是「一整套用来大规模构建和部署 agent 的 API」——定义 agent 该用什么工具、什么人设、什么能力，配好沙盒环境（装什么包、网络怎么管），从自己的应用发起 session，Claude 在隔离容器里执行（有文件系统、bash、web search），整套 Agent Loop（推理→调工具→处理结果→重复）跑在 Anthropic 服务器上，不用自己维护这套循环。

三个实例场景：

1. 看板自动触发：工单拖进「进行中」自动开一个 agent session，session 挂载预配置好 Lighthouse/Puppeteer 的环境和 GitHub repo，agent 拿到一份成功标准（Lighthouse 分数 90 以上、没有阻塞渲染的资源、所有图片都懒加载），做审计、压图、内联 CSS、延后加载脚本，工具调用即时串流回看板；另有一个独立的评分器（grader）按标准打分反馈，agent 据此改进；多个 session 能在各自独立的容器里并行跑
2. 带记忆的定期研究 agent：追踪 SaaS 工具的定价变化，会前自动整理报告——每次跑都先联网查最新定价页面和方案变化，在沙盒里用 Python 做成本分析，用 Excel 相关 Skill 写执行摘要，透过 MCP server 发到 Slack、在 Asana 建 review 任务；靠读写 memory store，开始前先看上次的发现、结束后存下这次的变化，才能做出「运算成本比上周低了 15%」这类比较型报告
3. 事故响应的多 agent 协作：监控告警触发时，自定义后端工具把告警内容送进新 session——一个协调者（coordinator）agent 接收告警，分派给三个专家 agent，各自在独立上下文窗口、共享文件系统上工作，把发现汇报给协调者综合成事故摘要；权限策略要求敏感操作前必须人工批准；协调者能靠 memory 搜过去的事故记录、找出规律，缩短重复性问题的诊断时间

构成要素：Agents（定义）、Sessions（单次运行）、Environments（沙盒环境）、Tools（含自定义后端工具）、MCP（接 Slack/Asana 这类服务）、Memory（跑前读、跑完写）、Outcomes（评分标准和评分器）、多 agent 协作（协调者分派给专家）。

---

动手搭第一个 Managed Agent

四个原语，按顺序：

1. Agent——model、system prompt、工具集的组合，可重复用于多次运行
2. Environment——执行环境（云端或自托管），含网络配置
3. Session——某个 agent 在某个 environment 里的一次具体运行，是最小工作单位
4. Events——双向流动的消息，含 agent 的动作、工具调用、结果、回复

架构是：你的应用跟一个 session 通信，session 驱动 environment 里的工作，所有结果透过 event stream 流回你的应用——这是从传统 while 循环换成事件驱动模型的根本转变。

最小可跑示例（在临时目录建一个文件、数行数、报告结果，用官方打包好的 agent toolset）：

# 第 1 步：建 Agent
import anthropic
client = anthropic.Anthropic()

agent = client.beta.agents.create(
    name="Line Counter",
    model="claude-opus-5",
    system="You are a helpful agent that completes small file tasks.",
    tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}],
)

# 第 2 步：建 Environment
environment = client.beta.environments.create(
    name="line-counter-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

# 第 3 步：建 Session
session = client.beta.sessions.create(
    agent=agent.id, environment_id=environment.id, title="Count lines demo",
)

# 第 4 步：先开 stream，再发送启动消息
with client.beta.sessions.events.stream(session_id=session.id) as stream:
    client.beta.sessions.events.send(
        session_id=session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text", "text": "Create a file in the temp directory, count its lines, and report back."}],
        }],
    )

    # 第 5 步：消费 stream
    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                if block.type == "text":
                    print(block.text, end="", flush=True)
        elif event.type == "agent.tool_use":
            print(f"\n[tool] {event.name}")
        elif event.type == "session.status_idle":
            print("\n--- Agent done ---")
            break

⚠️ 关键顺序：一定要先打开 event stream，再发送启动消息——stream 只会传送它打开之后发生的事件，先发消息再开 stream 会漏掉最早的那批事件。三个要盯的事件类型：agent.message（文字输出）、agent.tool_use（工具选择）、session.status_idle（完成信号）。

这笔交易换到了什么：传统实作要自己完整掌控循环；Managed Agents 把循环本身、沙盒管理、断点续跑能力都交出去，你只需要消费 event stream。适合长时间跑、大量碰文件的任务，比如「帮我整理这个」这类操作。

生产实例：文件共享清理——一个 managed agent 读取目录规范，穿梭进乱糟糟的收件文件夹，把文件搬到对的项目文件夹，把重复文件和零字节文件归档，拿不准的标记出来待人工确认，整个 session 跑几分钟、处理几千个文件，活动过程实时串流给一个 dashboard。

---

用 Claude Code 生成 API 集成代码

这是这门课唯一一节讲 Claude Code（而不是 API 本身）的内容：从一份没写完的 TypeScript 天气 app 桩代码开始——getWeather（传城市、回温度和天气状况）已经写好，run 函数（该实现 Tool Runner + Claude SDK 逻辑，Tool Runner 会自动处理 agent loop）还没写。

Claude Code 内建一个 Claude API Skill，能用 /claude-api 手动叫出来，检测到项目用 TypeScript SDK 时也会自动触发。

一句 prompt 换来能跑的代码：写 prompt 的时候把三件事讲清楚——目标文件是哪个、要用什么模式（pattern）、期待的结果是什么。Claude Code 会补完实现、跑一遍脚本、自己修掉冒出来的错误。这次生成的结果包含：一个用 Zod 做输入校验的 tool、Tool Runner 的实现、写好的 run 函数，跑起来会显示 agent loop 的结果。

该记住的模式：定义一个 tool → 传给 runner → 返回结果——这个三步结构不用死记，直接把文件搭好桩、交给 Claude Code 去补完就行。

常见错误

• ❌ 把 API key 直接写死在源码文件里——这是 key 最后泄漏到 GitHub 的最常见原因，一律存进 .env.local 这类不进版本控制的文件
• ❌ 图省事整个产品都固定用最贵的 Opus/Fable——先花时间跑一个 20-30 个例子的简易 Eval，从 Haiku 开始往上测，找到「敢拿去上线」的最便宜档位，正式产品再按任务分别路由到不同模型
• ❌ 工具的 description 写得含糊笼统——这是 agent 判断错该不该调用工具的头号原因，description 要写清楚这个工具具体做什么、什么时候该用
• ❌ 简单分类/抽取这类任务也开 Extended Thinking——只会加延迟和成本，不会让结果更好，思考模式留给数学推理、多步骤逻辑、代码调试这类真正需要的场景
• ❌ 用 Skills 却没开 Code Execution 工具——Skill 是在 code execution 的容器里运行的，没开等于 Skill 里要求的实际操作跑不动
• ❌ Managed Agent 先发送启动消息、后打开 event stream——stream 只传送它打开之后的事件，顺序反了会漏掉最早那批（包括 agent 一开始的推理过程）
• ❌ 接了 MCP server 却不过滤工具权限——默认可能连不想要的写入类操作（比如帮你发消息）都一起开着，先全部关掉、只手动开确实要用的
• 💡 判断该用手写 Agent Loop 还是 Managed Agents：任务简单、需要精细控制每一步，自己写循环；任务长、复杂、容易出岔子（大量碰文件、要断点续跑、要多 agent 协作），交给 Managed Agents 托管

Sources

官方文档：

1. Claude Platform 101（课程总览）— https://academy.claude.com/courses/claude-platform-101
2. What is the Claude Platform? — https://academy.claude.com/courses/claude-platform-101/what-is-the-claude-platform
3. Your first API call — https://academy.claude.com/courses/claude-platform-101/your-first-api-call
4. Choosing the right model — https://academy.claude.com/courses/claude-platform-101/choosing-the-right-model
5. The agent loop explained — https://academy.claude.com/courses/claude-platform-101/the-agent-loop-explained
6. What is tool use? — https://academy.claude.com/courses/claude-platform-101/what-is-tool-use
7. What is thinking? — https://academy.claude.com/courses/claude-platform-101/what-is-thinking
8. Built-in tools — https://academy.claude.com/courses/claude-platform-101/built-in-tools
9. Skills — https://academy.claude.com/courses/claude-platform-101/skills
10. MCP — https://academy.claude.com/courses/claude-platform-101/mcp
11. Context management — https://academy.claude.com/courses/claude-platform-101/context-management
12. What are managed agents? — https://academy.claude.com/courses/claude-platform-101/what-are-managed-agents
13. Building your first managed agent — https://academy.claude.com/courses/claude-platform-101/building-your-first-managed-agent
14. Building with Claude Code — https://academy.claude.com/courses/claude-platform-101/building-with-claude-code