📘 第 12 课：Building your first managed agent（构建你的第一个托管智能体）

官方课程名：Building your first managed agent（Curriculum 第三段「Managed Agents」第二课 · 动手课） 官方地址：https://anthropic.skilljar.com/claude-platform-101 归档路径：Claudeexams/20-课程/课程003 the AI Platform 101/ 针对认证：CCAR-P（架构师 Professional） 归档日期：2026-10-14 ⚠️ 语料来源：官方 Skilljar 课程正文（用户提供，需登录）。CC BY-NC-SA 4.0，仅供个人学习。

⭐⭐ 本课权重提示：领域 3（19%）的动手落地课。四个 API 原语（Agent / Environment / Session / Events）按序创建是机制默写题；「先开流、后发送」是官方点名的时序陷阱（stream 只投递开流之后的事件）；三个事件类型（agent.message / agent.tool_use / session.status_idle）是辨识题；Recap 末句给出自建 vs 托管的官方判据（领域 1）。另有一个考点彩蛋：Managed Agents 默认对每个 API 账户启用，无需特殊权限。 🔗 与第 4 课成对：第 4 课教你自己写 while 循环（You own the loop and the tools），本课教你怎么把循环委派出去——两句官方判语对照背。

🎯 本课学习目标

⚠️ 本课官方未提供 What you'll learn 区块。以下按文稿结构反推：

1. 能说出何时委派循环：跑得久（分钟到小时）、跨多工具、要留状态、要写文件、断网要能续跑。
2. ⭐⭐ 能按序默写四原语：Agent（人格：模型＋系统提示＋工具集，可复用）→ Environment（在哪跑）→ Session（一次运行＝工作单元）→ Events（进出的消息流）。
3. ⭐⭐ 能完成五步最小托管 agent：建 agent → 建环境 → 建 session → 先开流 → 发 kickoff → 消费流。
4. ⭐⭐ 能辨三个事件类型：agent.message（文本）、agent.tool_use（选了哪个工具）、session.status_idle（完成）。
5. ⭐ 能复述 The trade：委派循环、沙箱与可恢复性，换来的只是消费事件流。
6. 能识别生产形态：长时、碰文件、「帮我整理一下」型任务（文件共享清理例）。

📖 一、什么时候该委派循环（引子）

官方原句： If you've built an agent loop by hand, you know the drill: while loops, stop reason switches, tool executions. That works, and for a lot of features it's actually the right shape. But sometimes that loop is going to run for a very long time — minutes, maybe even hours — across many tools, with state to keep, files to write, and work to resume after a network hiccup. At that point, you don't want to run the loop on your server. You want to delegate it. That's what managed agents are.

精译：手工写过 agent loop 的都懂那套流程：while 循环、stop reason 分支、工具执行。那没问题，对很多功能来说那恰恰是对的形状。但有时这个循环要跑很久 —— 几分钟甚至几小时 —— 跨多个工具，要留状态、要写文件、断了网还得续跑。到那个份上，你就不想在自己服务器上跑这个循环了。你想把它委派出去。这就是 managed agents。

⭐⭐ 委派判据（Recap 6 官方原句拆开背）

Reach for managed agents when the loop would run too long, do too much, or need to survive a hiccup. Reach for a manual loop when you want full control. 「循环会跑太久、干太多、或要扛住故障中断——用托管；想要完全控制——用手动循环。」 * 考点：决策题三分——时长 / 工作量 / 可恢复性 vs 完全控制。与第 7 课「托管光谱」、第 11 课「你仍拥有验收权」连成一个完整决策框架。

📖 二、什么是托管 agent ＋ 四原语

官方原句： A managed agent is an agent loop that runs on the AI provider's infrastructure instead of yours.* You describe the agent once, you give it an environment to work in, and you start a session. the AI provider runs the loop, and you just stream the events back out as it works*.

精译：托管 agent 就是跑在官方基础设施上而非你服务器上的 agent 循环。你把 agent 描述一次，给它一个工作环境，启动一个 session。官方跑循环，你只在它干活时把事件流接出来。

官方原句： Managed agents are enabled by default for every API account — no special access needed.

精译：托管智能体对每个 API 账户默认启用 —— 不需要任何特殊权限。

⭐⭐ 四原语（The four primitives · 按序必背）

官方原句： There are four primitives, and they come in order: 1. Agent — the persona: model, system prompt, and toolset. This is reusable across many runs. 2. Environment — where the agent runs: cloud or local, networking config, and so on. 3. Session — a single run of an agent inside a certain environment. **The session is the unit of work. 4. Events — the messages flowing in and out: the agent's actions, the tool calls, the results, the replies.

官方原句： Here's how the pieces fit together: your app talks to a session, the session drives work inside the environment, and everything that happens flows back out through the event stream. Notice the shift here: you're not running a while loop. You're sending events and reading events.**

精译：拼装关系：你的应用与 session 对话，session 驱动环境里的工作，一切发生的事经事件流回流。注意这个转变：你不再跑 while 循环了——你是在发事件、读事件。

⭐⭐ 考点：① 顺序题——四原语「come in order」，乱序选项直接排除；② 定义配对题——「可复用」只属于 Agent，「工作单元」只属于 Session（第 11 课构件定义在此精确化）；③ 范式转变句——「发事件、读事件」取代「跑 while 循环」。

📖 三、最小可用托管 agent（五步 · 代码全解）

任务：在临时目录建一个文件、数行数、汇报结果。工具用 agent toolset（官方捆绑的文件、bash、网页工具）——不用自己定义任何工具。

Step 1：建 Agent（可复用的定义）

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

官方原句：Remember: the agent is reusable. Create it once and run it across many sessions. 精译：记住：agent 是可复用的。建一次，跨多个 session 跑。

Step 2：建 Environment（容器模板）

environment = client.beta.environments.create(
    name="line-counter-env",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)

官方原句：This spins up the container template — cloud, with unrestricted networking. This is the sandbox where the file actually gets written. 精译：这一步旋起容器模板 —— 云端、网络不设限。这就是文件真正被写入的那个沙箱。 ⭐ 领域 5 对照钩子：unrestricted（不设限）网络在本课是演示默认；生产上应按需收紧（第 9 课过滤思想同样适用于环境配置）。

Step 3：建 Session（工作单元）

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Count lines demo",
)

官方原句：Then we create a session with our agent and environment, plus an optional title. The session is the unit of work. 精译：用 agent 与 environment 建 session，外加可选标题。session 就是工作单元。

Step 4：⭐⭐ 先开流，再发送（官方时序陷阱）

官方原句： Now we open the event stream — and notice that we do this first. The stream only delivers events that occur after it opens, so always open it before sending the kickoff message. Then we send the user message into the live stream.

精译：现在打开事件流 —— 注意这一步在最前面。流只会投递开流之后发生的事件，所以永远先开流、再发 kickoff 消息。然后我们把用户消息送进活着的流：

with client.beta.sessions.events.stream(session_id=session.id) as stream:
    # Stream is open — now send the kickoff
    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.",
                    }
                ],
            }
        ],
    )

官方原句：Notice it's events — plural. Events are how everything flows in this API. 精译：注意是 events —— 复数。这个 API 里一切皆经事件流动。 ⭐⭐ 考点：时序题几乎必出——「先 send 再 stream」的顺序就是错误答案；丢事件的机理正是「流只投递开流之后的事件」。

Step 5：消费流（三个事件类型）

官方原句： Finally, we consume the stream. There are three event types that matter for this demo: agent.message — the AI's text ／ agent.tool_use — what tool the AI picked ／ session.status_idle — the agent is done.

精译：最后消费流。本例要盯三种事件：agent.message（AI 的文本）、agent.tool_use（AI 选了哪个工具）、session.status_idle（干完了）。

    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

官方原句：Run it, and the output is the agent reasoning out loud — actual text, the tools it picks, and a final answer. All of it running inside the AI provider's container, not yours. 精译：跑起来，输出就是 agent 边想边说——真实文本、选的工具、最终答案。全部跑在官方容器里，不是你的。** ⭐ 呼应第 6 课：思考文本可见（reasoning 可见性），这里连「边想边说」都经 agent.message 流出来。

📖 四、The trade（交换了什么）

官方原句： Usually with agents, we have our own loop where we have to control everything. With managed agents, you delegate that loop, the sandbox, and the resumability — and just consume the event stream as it comes in.

精译：通常自己做 agent，循环在你手里，一切都要自己控制。换到托管模式，你把循环、沙箱、可恢复性一并委派出去 —— 只需要来什么事件就消费什么事件。

官方原句： In a production app, this is the shape for long-running, file-touching, "go organize this for me" tasks. Picture a file share cleanup: a managed agent reads a target directory structure spec, walks the messy incoming folder, moves files into the right project folders, archives duplicates and zero-byte garbage, and flags anything it can't confidently place — all in a session that can run for minutes against thousands of files.

精译：在生产应用里，这就是长时、碰文件、「帮我把这个整理一下」型任务的形状。想象一次文件共享清理：托管 agent 读一份目标目录结构规范，遍历乱糟糟的收件文件夹，把文件移进正确的项目目录，归档重复文件和零字节垃圾，拿不准的打上标记 —— 整场跑在一个可能持续几分钟、面对上千文件的 session 里。

⭐⭐ 考点：委派三件套连背——循环（loop）＋沙箱（sandbox）＋可恢复性（resumability）；换回的是事件流消费这一件事。「flags anything it can't confidently place」呼应第 6 课 confidently get it wrong 的反面：没把握的就标记交人，而不是自信地乱放（领域 5 fail-safe 姿态）。

📌 五、Recap（官方六条要点）

🧠 本课 → CCAR-P 考点映射

⭐ 战略结论：本课是领域 3 机制默写的主战场——四原语顺序、五步流水线、三事件类型、先开流时序，全部是可直接出题的「官方钦定清单」。与第 11 课合读：第 11 课给「是什么与为什么」，本课给「怎么建与怎么选」。

🔤 本课新生词（已回灌 30-单词表/03，2026-10-14）

✅ 本课进度

• [x] 全文精译与架构师级拆解（2026-10-14）
• [x] ⭐⭐ 记录四原语顺序、五步流水线、先开流时序陷阱与三事件类型
• [x] 记录 The trade 三件套（loop / sandbox / resumability）与自建 vs 托管官方判据
• [x] 生词回灌 30-单词表/03-考试核心生词与术语表.md（2026-10-14：新增速查 37 条 → 全表 505 条（与表内重复 8 词追加「第 12 课复现」）；新升级精讲 6 条 053–058）
• [x] 保存本课英文原文（27-English-12-Building-your-first-managed-agent.md）
• [ ] 跑通本课 runnable demo（需 Console 账号；Managed Agents 默认启用，无需特殊权限）
• [ ] 官方未提供 What you'll learn 与练习区块 —— 若后续页面补全，需回填

🔗 关联

• 本课英文原文：27-English-12-Building-your-first-managed-agent.md ✅ 已存（2026-10-14）
• 上一课对照：第 11 课 What are managed agents?（是什么为什么 → 本课怎么建怎么选）
• 第 4 课对照：The agent loop explained（You own the loop → 本课委派循环）
• 第 9 课对照：MCP 工具过滤（default_config 默认全关 → 本课 agent_toolset 默认全开）
• 课程大纲：01-课程导读与大纲全景
• 考纲：00-CCAR-P备考蓝图
• 生词表：30-单词表/03-
• 下一课预告：第 13 课 Building with AI Code Assistant（正文需提供）

⚠️ 语料说明：英文原文中的 anthropic.the AI provider() 与 model="current-model" 为抓取/去品牌化残留；其余英文引句均为官方原句，未作改动。