可易

托管你的智能体

可易团队阅读约 18 分钟

同一研究智能体按 Docker、Modal、Kubernetes 三层部署。镜像与 HTTP 接口不变,变的是拉起容器、路由会话、回收空闲进程,以及把对话留在 /data。

目录

#托管你的智能体

你已经在笔记本 00 里做好了一个研究智能体(research agent)。它跑在你的笔记本电脑上。现在别人也要用它:一位同事、一个定时任务(cron job)、一个网页应用,或一位客户。这意味着它必须跑在终端以外的地方,保持在线,在重启之后仍能续上对话,并且不能泄露你的 API 密钥。

这份笔记把同一个智能体,按三个层级部署出去:

层级跑在哪里什么时候用
1. Docker你的机器 / 一台虚拟机开发循环、内部工具、单租户
2. Modal托管的无服务器(serverless)环境你要一个网址,并且希望空闲时缩到零,而不自己管基础设施
3. Kubernetes你自己的集群多租户、受监管环境、需要完全掌控

智能体代码、容器镜像和 HTTP 接口在三层里完全相同。变的只是容器外面的运维机制。一旦智能体被放进容器、放在稳定接口后面,选主机就是一次部署决策,而不是一次重写。

把这份笔记从头跑到尾的费用:大约 1–2 美元的 Anthropic API 调用,再加上几美分的 Modal 计算。每一层都有拆除步骤。

全部部署代码在这份笔记旁边的 hosting/ 目录里。

开始之前:你该不该用 Agent SDK

如果你在做面向客户的聊天产品,先看 Claude Managed Agents。托管、会话和界面都是现成的,这份笔记的大部分你可以跳过。

Agent SDK 适合你需要程序化控制的时候:批处理和作业形态的智能体、内部工具、嵌进你自己后端的智能体,或者你必须自己拥有基础设施的受监管环境。如果是这些情况,继续往下读。

心智模型

先分清三个名词:

进程(process)是一个已经加载 SDK 的 Python 解释器。它和 Anthropic API 对话。

会话(session)是一段对话:提示历史、工具调用和结果。SDK 把它们写到磁盘上,以便你稍后用 resume= 恢复。

容器(container)是打包好的进程加上它的文件系统:你的智能体代码、SDK(它捆绑了自己驱动的 Claude Code CLI),以及会话存放的位置。

进程内 SDK(例如 OpenAI Agents SDK、Google ADK)里,“智能体”是你在 Web 服务器里实例化的一个对象。Claude Agent SDK 的智能体则是一个进程。隔离因此很直接(一个容器 = 一个爆炸半径),但托管就成了分布式系统问题,而不再是一次 pip install 问题。

任何层级的每次部署,都要做同样四件事:

┌────────────────────────────────────────────────────────────────────┐
│  caller ──► gateway ──► [ spawn | route ] ──► agent container ──► API
│                 │                                     │
│                 └── auth (not the agent's job)        └── /data  (persist)
│                                                                      │
│  orchestrator ──────────────── lifecycle ────────────────────────────┘
└────────────────────────────────────────────────────────────────────┘

有工作到达时,拉起(spawn)一个容器。

把每个请求路由到拥有该会话的容器。

生命周期:杀掉空闲容器,重启崩溃的容器。

持久化会话记录,这样重启不会丢掉对话。

第 1 层四件事都手工做。第 2 层把拉起和生命周期交给 Modal。第 3 层把四件事都交给 Kubernetes 再加一个小网关。智能体容器始终不变。

我们要部署的智能体

我们复用笔记本 00 里的 research_agent/agent.py,那个带 WebSearch 和 Read 的一行式研究智能体。如果你还没做笔记本 00,先做那份;这份笔记假定智能体已经能工作。

hosting/ 增加的只有一个薄 HTTP 服务器和一个 Dockerfile。系统提示直接来自 research_agent.agent;我们导入它,而不是复制它。有一处故意的差别:托管服务器把工具列表收窄到只有 WebSearch。服务器上没有上传路径,所以 Read 能碰到的文件只是其他会话的记录和容器自己的环境;一条被提示注入的网页结果,可能引导智能体把它们泄露出去。server.py 里的注释写明了这个理由。

from research_agent.agent import DEFAULT_MODEL, RESEARCH_SYSTEM_PROMPT

print(f"model: {DEFAULT_MODEL}")
print(RESEARCH_SYSTEM_PROMPT)
model: claude-opus-4-6
You are a research agent specialized in AI.

When providing research findings:
- Always include source URLs as citations
- Format citations as markdown links: [Source Title](URL)
- Group sources in a "Sources:" section at the end of your response

准备环境

用你的 API 密钥创建 hosting/.env。这个文件被 git 忽略。

%%bash
test -f hosting/.env || cp hosting/.env.example hosting/.env
echo 'Edit hosting/.env and set ANTHROPIC_API_KEY, then re-run this cell.'
grep -q '^ANTHROPIC_API_KEY=sk-ant-' hosting/.env \
  && ! grep -q 'your-key-here' hosting/.env \
  && echo '✅ key looks set'
Edit hosting/.env and set ANTHROPIC_API_KEY, then re-run this cell.
✅ key looks set

第 1a 层 — 一次性:一个提示,一个容器,然后结束

最简单的部署:容器从环境变量读一个提示,跑一次智能体,打印结果,然后退出。没有服务器,没有会话,没有状态。

模型说明:托管层默认使用 claude-sonnet-5-5,这样你在走完这份笔记时,测试请求保持便宜。在 hosting/.env 里设置 MODEL=claude-opus-5-5,即可与笔记本 00 的配置完全一致。

很多真实工作到这里就够了:发票处理、夜间报告生成、批量翻译、一次性分析。如果智能体的工作是“接收输入,产出输出,然后停止”,你不需要超过这一节的任何东西。

Dockerfile 把智能体、SDK,以及 SDK 在底层驱动的 Claude Code CLI 打进包里。构建上下文是 claude_agent_sdk/(当前目录),不是 hosting/,因为镜像还需要 research_agent/ 和 utils/:

%%bash
docker build -f hosting/Dockerfile -t research-agent . | tail -n 3
#0 building with "orbstack" instance using docker driver

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 2.30kB done
#1 DONE 0.0s

#2 resolve image config for docker-image://docker.io/docker/dockerfile:1
#2 DONE 0.6s

#3 docker-image://docker.io/docker/dockerfile:1@sha256:87999aa3d42bdc6bea60565083ee17e86d1f3339802f543c0d03998580f9cb89
#3 CACHED

#4 [internal] load metadata for docker.io/library/python:3.11-slim
#4 DONE 0.5s

#5 [1/9] FROM docker.io/library/python:3.11-slim@sha256:a3ab0b966bc4e91546a033e22093cb840908979487a9fc0e6e38295747e49ac0
#5 DONE 0.0s

#6 [internal] load build context
#6 transferring context: 814.53kB 0.0s done
#6 DONE 0.0s

#7 [3/9] WORKDIR /app
#7 CACHED

#8 [6/9] COPY research_agent/ ./research_agent/
#8 CACHED

#9 [7/9] COPY utils/ ./utils/
#9 CACHED

#10 [2/9] RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && apt-get install -y --no-install-recommends nodejs && npm install -g @anthropic-ai/claude-code@2.1.140 && apt-get purge -y curl && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*
#10 CACHED

#11 [4/9] COPY hosting/requirements.txt ./hosting/requirements.txt
#11 CACHED

#12 [5/9] RUN pip install --no-cache-dir -r hosting/requirements.txt
#12 CACHED

#13 [8/9] COPY hosting/server.py hosting/run_once.py hosting/entrypoint.sh ./hosting/
#13 CACHED

#14 [9/9] RUN chmod +x hosting/entrypoint.sh && touch hosting/__init__.py
#14 CACHED

#15 exporting to image
#15 exporting layers done
#15 writing image sha256:b77b20f557cef5e4b9ef01212f3ba3a0895ee97ff8e31f79d9e1dc0cfb7414f5 done
#15 naming to docker.io/library/research-agent done
#15 DONE 0.0s
%%bash
docker run --rm --env-file hosting/.env \
  -e PROMPT='What is the Claude Agent SDK, in one paragraph?' \
  research-agent
🤖 Thinking...

🤖 Using: ToolSearch()

✓ Tool completed

🤖 Thinking...

🤖 Using: WebSearch()

✓ Tool completed

🤖 Using: WebSearch()

✓ Tool completed

🤖 Thinking...

The **Claude Agent SDK** is a developer toolkit from Anthropic — available in Python and TypeScript — that gives developers access to the same tools, agent loop, and context management that power Claude Code, enabling them to build fully autonomous AI agents that can read files, run terminal commands, search the web, edit code, and interact with external APIs without requiring developers to manually implement a tool execution loop. Unlike the standard Claude API (where the developer must handle tool-use loops themselves), the Agent SDK lets Claude manage the agentic loop autonomously, making it straightforward to build sophisticated agents such as finance assistants, personal assistants, customer support bots, and deep research agents that can operate with minimal human intervention.

---

**Sources:**
- [Agent SDK Overview – Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/overview)
- [Building Agents with the Claude Agent SDK – Anthropic Engineering](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)
- [Agent SDK Overview – Anthropic API Docs](https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview)
- [claude-agent-sdk-python – GitHub](https://github.com/anthropics/claude-agent-sdk-python)
- [claude-agent-sdk-typescript – GitHub](https://github.com/anthropics/claude-agent-sdk-typescript)

就这样。entrypoint.sh 看不到 serve 参数,于是 run_once.py 用 $PROMPT 调用 research_agent.agent.send_query(),并以退出码 0 结束。

什么时候这样就够:每次调用彼此独立的作业形态任务。从定时任务、队列工作进程、CI 步骤,或任何你会运行 CLI 的地方去跑它。

第 1b 层 — 混合:加上服务器,让对话可以继续

一次性模式留不住对话;每次 docker run 都开始一个新会话。聊天形态的智能体需要一个长期运行的进程,能接受追问,并且每次恢复正确的会话。

hosting/server.py 是一个大约 100 行的 FastAPI 应用,只做这件事,不多做。这个接口是每一层都遵守的契约:

GET  /health                            → 200 {"status": "ok"}
POST /sessions/{session_id}/messages    → 200 text/event-stream of SDK messages

server.py 里有两件事值得注意:

服务器没有认证。文档字符串把这一点写得很显眼。认证是网关的工作(第 3 层会说明它放在哪里)。服务器校验 session_id 的格式,并信任调用方。

它维护一张小映射,从你的 session_id 对应到 SDK 内部的会话标识。SDK 会生成自己的会话标识;你不能指定它们。服务器从第一轮的 ResultMessage 得知 SDK 的标识,并在后续追问时把它传给 resume=。这张映射和记录一起持久化在 /data 下。

用 docker-compose 启动。它同时把 ./sessions 挂载到 /data,这样记录能在重启后留下来:

%%bash
cd hosting/docker && docker compose up --build -d
sleep 3
curl -s http://localhost:8000/health
 Image research-agent Building
 Image research-agent Built
 Network docker_default Creating
 Network docker_default Created
 Container docker-research-agent-1 Creating
 Container docker-research-agent-1 Created
 Container docker-research-agent-1 Starting
 Container docker-research-agent-1 Started
{"status":"ok"}

发送一个提示并流式接收响应(-N 关闭 curl 的缓冲,这样事件到达时你就能看到):

%%bash
curl -N -s -X POST http://localhost:8000/sessions/demo-1/messages \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"What are the three most interesting AI agent trends right now?"}'
event: message
data: {"subtype": "init", "data": {"type": "system", "subtype": "init", "cwd": "/app", "session_id": "77597263-a169-4236-b3d4-8ec14f90fd2b", "tools": ["Task", "TaskOutput", "Bash", "Glob", "Grep", "ExitPlanMode", "Read", "Edit", "Write", "N … [truncated]

event: message
data: {"content": [{"id": "toolu_01LpCYD1mQgNAmiDYq55RHyC", "name": "WebSearch", "input": {"query": "AI agent trends 2026"}}], "model": "claude-sonnet-4-6", "parent_tool_use_id": null, "error": null, "usage": {"input_tokens": 685, "cache_cr … [truncated]

[... 6 events omitted — thinking blocks, tool loading, and web-search result payloads ...]

event: message
data: {"content": [{"text": "Great question! Based on the latest research and reports, here are the **three most interesting AI agent trends** right now in 2026:\n\n---\n\n## \ud83e\udd1d 1. Multi-Agent Systems & Orchestration\nThe era of the single, all-purpose AI agent is giving way to **coordinat … [truncated]

event: message
data: {"subtype": "success", "duration_ms": 20980, "duration_api_ms": 20812, "is_error": false, "num_turns": 3, "session_id": "77597263-a169-4236-b3d4-8ec14f90fd2b", "stop_reason": "end_turn", "total_cost_usd": 0.0502906, "usage": {"input_t … [truncated]

event: done
data:

现在对同一个 session_id 发一个追问。服务器恢复了会话,所以智能体记得第一轮:

%%bash
curl -N -s -X POST http://localhost:8000/sessions/demo-1/messages \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Tell me more about the second one."}'
event: message
data: {"subtype": "init", "data": {"type": "system", "subtype": "init", "cwd": "/app", "session_id": "77597263-a169-4236-b3d4-8ec14f90fd2b", "tools": ["Task", "TaskOutput", "Bash", "Glob", "Grep", "ExitPlanMode", "Read", "Edit", "Write", "N … [truncated]

event: message
data: {"content": [{"id": "toolu_01YU5m6b66Kh6GcSN1Kbv7zq", "name": "WebSearch", "input": {"query": "context engineering AI agents 2026 techniques best practices"}}], "model": "claude-sonnet-4-6", "parent_tool_use_id": null, "error": null, … [truncated]

[... 5 events omitted — thinking blocks, tool loading, and web-search result payloads ...]

event: message
data: {"content": [{"text": "## \ud83e\uddf1 Deep Dive: Context Engineering\n\nContext engineering has quickly become **the defining AI skill of 2026**. Here's a thorough breakdown:\n\n---\n\n### What Is It, Exactly?\n\nContext engineering is the discipline of **designing what information an AI mode … [truncated]

event: message
data: {"subtype": "success", "duration_ms": 26895, "duration_api_ms": 26791, "is_error": false, "num_turns": 3, "session_id": "77597263-a169-4236-b3d4-8ec14f90fd2b", "stop_reason": "end_turn", "total_cost_usd": 0.08444499999999999, "usage": … [truncated]

event: done
data:

重启容器,再发一次追问。卷挂载保住了 /data,所以对话还在:

%%bash
cd hosting/docker && docker compose restart && sleep 3
curl -N -s -X POST http://localhost:8000/sessions/demo-1/messages \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Summarize what we have discussed so far."}'
Container docker-research-agent-1 Restarting
 Container docker-research-agent-1 Started

event: message
data: {"subtype": "init", "data": {"type": "system", "subtype": "init", "cwd": "/app", "session_id": "77597263-a169-4236-b3d4-8ec14f90fd2b", "tools": ["Task", "TaskOutput", "Bash", "Glob", "Grep", "ExitPlanMode", "Read", "Edit", "Write", "NotebookEdit", "WebFetch", "TodoWrite", "WebSearch", "TaskStop", "AskUserQuestion", "Skill", "EnterPlanMode", "EnterWorktree", "ExitWorktree", "CronCreate", "CronDelete", "CronList", "RemoteTrigger", "ToolSearch"], "mcp_servers": [], "model": "claude-sonnet-4-6", "permissionMode": "default", "slash_commands": ["update-config", "debug", "simplify", "batch", "loop", "schedule", "claude-api", "compact", "context", "cost", "heapdump", "init", "pr-comments", "release-notes", "review", "security-review", "insights"], "apiKeySource": "ANTHROPIC_API_KEY", "claude_code_version": "2.1.81", "output_style": "default", "agents": ["general-purpose", "statusline-setup", "Explore", "Plan"], "skills": ["update-config", "debug", "simplify", "batch", "loop", "schedule", "claude-api"], "plugins": [], "uuid": "753db5ec-c432-4634-abb4-048eda1e6acd", "fast_mode_state": "off"}, "type": "SystemMessage"}

event: message
data: {"content": [{"thinking": "The user wants a summary of our conversation so far. No tools needed for this.", "signature": "EtYBCmcIDRgCIkBg3e+9ruTNyro9yQA8kMewU6BzRzlQR/MAvKWUy2kkCH0rl6bddOJ1gJBmcF4L3GPf/pgLkImzUqg1JV4RfUNgKAEyEWNsYXVkZS1zb25uZXQtNC02OABCCHRoaW5raW5nEgxfs2ACXCyvMe8OUvQaDA4MA9sG7f/fI1we2yIwQvNMoFyTGl2/Ps+arqqgLoLYtySrkCOrgNmwcZFIbzQOFWiSJIcsqA7inm8T8n90Kh0wlw1tFbJw0suOLM6okhU+eNc0gCr59ENLuBeZhBgC"}], "model": "claude-sonnet-4-6", "parent_tool_use_id": null, "error": null, "usage": {"input_tokens": 7108, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0}, "output_tokens": 0, "service_tier": "standard", "inference_geo": "global"}, "type": "AssistantMessage"}

event: message
data: {"subtype": "success", "duration_ms": 8163, "duration_api_ms": 8025, "is_error": false, "num_turns": 1, "session_id": "77597263-a169-4236-b3d4-8ec14f90fd2b", "stop_reason": "end_turn", "total_cost_usd": 0.028029, "usage": {"input_tokens": 7108, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "output_tokens": 447, "server_tool_use": {"web_search_requests": 0, "web_fetch_requests": 0}, "service_tier": "standard", "cache_creation": {"ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0}, "inference_geo": "", "iterations": [{"input_tokens": 7108, "output_tokens": 447, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0}, "type": "message"}], "speed": "standard"}, "result": "Sure! Here's a summary of our conversation so far:\n\n---\n\n### Conversation Summary\n\n**1. Top 3 AI Agent Trends (May 2026)**\nYou asked about the most interesting AI agent trends right now. Based on web research, the three highlighted were:\n\n- **Multi-Agent Systems & Orchestration** — Specialized agents working in coordinated teams, replacing single all-purpose agents. Gartner reported a 1,445% surge in multi-agent system inquiries.\n- **Context Engineering** — Designing the full information architecture around an agent (memory, retrieval, data sources, token budgets) to ensure reliable, high-quality outputs at scale.\n- **Governance & Deterministic Guardrails** — Shifting from viewing governance as a compliance burden to an enabler, combining dynamic AI with human oversight to safely deploy agents in high-stakes scenarios.\n\n---\n\n**2. Deep Dive into Context Engineering**\nYou asked for more detail on the second trend. Key takeaways included:\n\n- **Context Engineering ≠ Prompt Engineering** — It's a broader discipline covering the entire information lifecycle of an agent.\n- **Core techniques** include RAG, memory management, context compression, context offloading, state persistence, and tool output structuring.\n- **Why it matters for agents** — Unlike chatbots, agents accumulate context over many steps, making careful information design critical to avoid context rot and token blowouts.\n- **RAG alone isn't enough** — 77% of IT leaders agree RAG is insufficient for production AI on its own.\n- Proper context engineering can improve agent task completion rates dramatically (e.g., **83% → 96%**).\n\n---\n\nWould you like to explore any of these topics further?", "structured_output": null, "type": "ResultMessage"}

event: done
data:
%%bash
# Teardown tier 1
cd hosting/docker && docker compose down
Container docker-research-agent-1 Stopping
 Container docker-research-agent-1 Stopped
 Container docker-research-agent-1 Removing
 Container docker-research-agent-1 Removed
 Network docker_default Removing
 Network docker_default Removed

第 2 层 — Modal:同一镜像,现在它是一个网址

第 1 层跑在你的机器上。第 2 层通过 modal.Sandbox,把同一个 Dockerfile 跑在 Modal 上。你得到一个公开的 HTTPS 网址、空闲缩到零,并且没有服务器要管。

这个网址是公开的:谁拿到它,谁就能花掉你的 API 预算。第 1 层和第 3 层假定前面有一个做认证的网关;第 2 层没有网关,所以 modal_app.py 为每次部署生成一个不记名令牌(bearer token),并把它作为 AGENT_AUTH_TOKEN 传入。只有设置了这个环境变量时,server.py 才校验令牌,因此其他层级不受影响。

hosting/modal/modal_app.py 很短,因为智能体本身没有任何变化:

app = modal.App.lookup("research-agent-hosting", create_if_missing=True)
image = modal.Image.from_dockerfile("hosting/Dockerfile", context_dir=".")
auth_token = secrets.token_urlsafe(32)
sandbox = modal.Sandbox.create(
    "serve",  # appended to the image's ENTRYPOINT, like compose's `command:`
    app=app,
    image=image,
    secrets=[
        modal.Secret.from_name("anthropic"),
        modal.Secret.from_dict({"AGENT_AUTH_TOKEN": auth_token}),
    ],
    volumes={"/data": sessions_volume},
    encrypted_ports=[8000],
)
print(sandbox.tunnels()[8000].url)

持久化使用挂载在 /data 的 modal.Volume,和第 1 层一样的 CLAUDE_CONFIG_DIR 做法。(如果你的工作负载有很多沙箱同时写入,并且碰到 Volume 提交语义的问题,就换成 SessionStore;第 3 层和生产部署用的也是它。)

一次性准备在你的终端里做(modal setup 会打开浏览器,所以不能从笔记单元格里跑):

pip install modal
modal setup

然后创建 Modal 将作为 ANTHROPIC_API_KEY 注入的密钥:

%%bash
modal secret create anthropic ANTHROPIC_API_KEY="$(grep ANTHROPIC_API_KEY hosting/.env | cut -d= -f2)"
Created a new secret 'anthropic' with the key 'ANTHROPIC_API_KEY'

Use it in your Modal app:
%%bash
python hosting/modal/modal_app.py | tee /tmp/modal_deploy.out
MODAL_URL=$(awk '/^url:/ {print $2}' /tmp/modal_deploy.out)
MODAL_TOKEN=$(awk '/^token:/ {print $2}' /tmp/modal_deploy.out)
{ echo "MODAL_URL=$MODAL_URL"; echo "MODAL_TOKEN=$MODAL_TOKEN"; } > /tmp/modal_url.env
sandbox: sb-7R7zQ7TtX0h9eKZ8qslvwo
url:     https://ta-01ks91e217n9fymaxjtdc9k5bh-8000-kn9n102ljd7y4majwav00kwg0.w.modal.host
token:   sb-…redacted…

⚠️  The URL is public. The token is the only thing gating it — don't share both.

Try it:
  curl -N -X POST https://ta-01ks91e217n9fymaxjtdc9k5bh-8000-kn9n102ljd7y4majwav00kwg0.w.modal.host/sessions/demo-1/messages \
    -H 'Authorization: Bearer sb-…redacted…' \
    -H 'Content-Type: application/json' \
    -d '{"prompt":"What are the latest AI agent trends?"}'
%%bash
source /tmp/modal_url.env
curl -N -s -X POST "$MODAL_URL/sessions/demo-1/messages" \
  -H "Authorization: Bearer $MODAL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Give me a one-sentence summary of the Claude Agent SDK."}'
event: message
data: {"subtype": "init", "data": {"type": "system", "subtype": "init", "cwd": "/app", "session_id": "1566ffe4-2b20-4a68-82ff-283984b64451", "tools": ["Task", "TaskOutput", "Bash", "Glob", "Grep", "ExitPlanMode", "Read", "Edit", "Write", "N … [truncated]

event: message
data: {"content": [{"id": "toolu_01PPS8yzMBzMnRhG2Hnpk5VL", "name": "WebSearch", "input": {"query": "Claude Agent SDK Anthropic 2026"}}], "model": "claude-sonnet-4-6", "parent_tool_use_id": null, "error": null, "usage": {"input_tokens": 120 … [truncated]

[... 5 events omitted — thinking blocks, tool loading, and web-search result payloads ...]

event: message
data: {"content": [{"text": "The **Claude Agent SDK** is Anthropic's framework that gives developers programmatic access to the same tools, agent loop, and context management that power Claude Code \u2014 enabling the creation of AI agents that can autonomously read files, run commands, search the w … [truncated]

event: message
data: {"subtype": "success", "duration_ms": 12879, "duration_api_ms": 12871, "is_error": false, "num_turns": 3, "session_id": "1566ffe4-2b20-4a68-82ff-283984b64451", "stop_reason": "end_turn", "total_cost_usd": 0.045893199999999995, "usage" … [truncated]

event: done
data:

同一接口,同一镜像,不同主机。没有调用时,Modal 把沙箱缩到零,你不用付钱。

拆除,以免空闲资源继续计费:

%%bash
python hosting/modal/teardown.py
terminating sandbox sb-7R7zQ7TtX0h9eKZ8qslvwo
deleted volume research-agent-sessions

第 3 层 — Kubernetes:当你必须自己拥有基础设施

第 3 层用于多租户生产、受监管环境,或任何你需要对网络、隔离和成本有完全控制的地方。智能体镜像和接口仍然相同;新的是它周围的机制:

前面有一个网关,认证调用方,并且只转发他们拥有的 session_id。server.py 留空的认证,最终发生在这里。

按会话一 Pod 的路由(网关 → Redis → Pod),让每段对话有自己的爆炸半径。

一组预热好的备用 Pod,使新会话不用支付冷启动延迟。

出站封锁(NetworkPolicy 加上一个允许名单代理),让被提示注入的智能体只能到达 api.anthropic.com,别的地方都不行。

完整清单、网关,以及逐步的架构说明在 hosting/kubernetes/ 里。它在本地 kind 集群上端到端运行,不需要云账号:

cd hosting/kubernetes
ANTHROPIC_API_KEY=sk-ant-... ./kind-quickstart.sh

快速开始会打印两个演示租户(alice 和 bob)的不记名令牌。网关把每个会话限定在创建它的租户上:与第 1 层和第 2 层相同的 curl -N POST /sessions/{id}/messages,现在指向 :8080 上的网关,并带 Authorization: Bearer <alice-token> 请求头,对 alice 有效;同一请求换成 bob 的令牌会得到 403。README 的 Deploying to your own cluster 一节说明真实集群要改的镜像仓库和入口。

Kubernetes 这一层建立在 Joe Shamon 和 Ben Lehrburger 的内部工作之上。

把它做成可以上生产

有两件生产关注点,各自几行就能接上。下面的单元格给出代码;托管文档覆盖完整的生产检查清单(认证、优雅关闭、空闲超时调节、自动扩缩、成本控制)。

可观测性

SDK 为每一轮和每一次工具调用发出 OpenTelemetry 跨度(span)。用两个环境变量把它指向你的采集器,不必改 server.py 的代码:

# In docker-compose.yml / modal_app.py / your k8s Deployment:
#   OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4317
#   OTEL_SERVICE_NAME=research-agent

存活检查

GET /health 已经在 server.py 里。把编排器的存活探针指到它(compose 的 healthcheck:、Modal 健康检查、k8s 的 livenessProbe)。

超出单个卷的持久化

/data 卷挂载对单主机和 Modal 够用。多主机生产要使用 SessionStore 适配器,把记录镜像到共享存储(S3、Postgres、Redis)。注意 SessionStore 是一面镜子;本地磁盘写入总是先发生,镜像失败会发出 mirror_error,而不打断智能体。

线上格式

server.py 流式输出原始 SDK 消息类型。对一份笔记来说这没问题;真正的 API 要定义稳定的线上格式(wire format),这样 SDK 版本升级不会弄坏客户端。

选择你的层级

层级它给你什么什么时候选它什么时候往上走
1. Docker一台你控制的机器上的容器。Compose 会重启它,绑定挂载保住 /data。你运维一台 Docker 主机。开发循环、内部工具、单租户应用、定时或批处理作业。你可以手工重启,并且网络以外没有人调用它。那台机器以外的人需要一个网址,或者“手工重启”不再可接受。
2. Modal同一镜像后面是一个公开 HTTPS 网址,空闲缩到零,并且远程构建。你什么都不用运维。你今天就要一个可调用的端点,流量是突发的或大部分时间为零,并且每次部署一个不记名令牌就够做认证。你需要真正的多租户隔离、网络层出站控制,或者平台团队要求工作负载跑在他们的集群上。
3. Kubernetes按会话一 Pod 的隔离、带租户范围会话的认证网关、出站封锁,以及一组预热备用 Pod。你运维集群、网关和 Redis。多租户生产、受监管环境,或者你已经在跑 Kubernetes,并希望智能体遵循和其他一切相同的运维模型。这是这份笔记阶梯的顶端;从这里起你调节自动扩缩、多区域路由和持久会话存储,而不是再迁移。

托管指南里的部署模式直接对应这些层级。一次性会话(模式 1:一个提示,一个进程,然后退出)是第 1a 层:没有服务器,在任何主机上从定时任务或队列工作进程运行容器。长期运行和混合会话(模式 2 和模式 3,进程在多轮之间持有或重新装入对话状态)就是 server.py 用 resume= 加上 /data 卷实现的形态;第 1b、2、3 层都提供这种形态,差别只在谁维持进程存活,以及调用方如何到达它。单容器(模式 4,许多会话复用进一个容器)正是第 1b 层和第 2 层所做的;第 3 层存在的理由,是这种情况不再可接受,每一段会话都需要自己的爆炸半径。

附录 — 移植到其他提供方

同一个 hosting/Dockerfile,不同的部署命令。下面每一种都暴露 8000 端口并给你一个网址;把某个存储挂到 /data 以做持久化。

Fly Machines

fly launch --dockerfile hosting/Dockerfile --no-deploy  # run from claude_agent_sdk/
fly volumes create data --size 1
fly deploy

E2B

from e2b import Sandbox
sbx = Sandbox(template="research-agent")  # template built from hosting/Dockerfile
sbx.commands.run("./hosting/entrypoint.sh serve", background=True)
url = sbx.get_host(8000)

Daytona

from daytona import Daytona, CreateSandboxFromImageParams
sbx = Daytona().create(CreateSandboxFromImageParams(image="research-agent"))
sbx.process.exec("./hosting/entrypoint.sh serve")

Cloudflare Containers

// wrangler.toml points at hosting/Dockerfile
export class Agent extends Container { defaultPort = 8000 }

Vercel Sandbox

import { Sandbox } from "@vercel/sandbox";
const sbx = await Sandbox.create({ image: "research-agent", ports: [8000] });
await sbx.runCommand({ cmd: "./hosting/entrypoint.sh", args: ["serve"], detached: true });

PRIMARY_SOURCE: https://platform.claude.com/cookbook/claude-agent-sdk-07-hosting-the-agent

  • #Agent SDK
  • #容器部署
  • #Kubernetes
  • #会话持久化