Claude Agent SDK 如何在 Docker 上托管研究 Agent 并检查 /health 可用性？
【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks
这篇文章面向想把 Claude Agent SDK 的研究 Agent（来自00_The_one_liner_research_agent.ipynb）部署到本地 Docker 的读者。claude-cookbooks仓库的 hosting 目录 提供了三层部署（本地 Docker、Modal、Kubernetes），三者共用同一个 Agent 镜像和 HTTP 接口。本文聚焦第一层：用docker compose启动带服务的容器，并用GET /health确认实例存活。完成后的结果是：本机127.0.0.1:8000上有一个持续运行的 FastAPI + SSE 服务，/health返回200 {"status": "ok"}，且/sessions/{session_id}/messages可以续接多轮对话。
前提条件
- 一台装有 Docker 的环境。构建使用
Dockerfile.dockerignore，需要 BuildKit——Docker 23.0+ 和 Docker Desktop 的默认构建器已满足；旧版本引擎需加DOCKER_BUILDKIT=1环境变量执行构建。 - 一个有效的
ANTHROPIC_API_KEY。服务器将其列为必需环境变量。 - 已获取
claude-cookbooks仓库代码。下文命令默认在仓库根目录执行。
接口契约（三层部署共同遵守）来自 hosting/README.md：
GET /health → 200 {"status": "ok"} 编排器用的存活检查（liveness check）。 POST /sessions/{session_id}/messages Body: {"prompt": "<user message>"} → 200 text/event-stream event: message — data 是序列化的 SDK 消息 event: done — 本轮结束 event: error — data 为 {"message": "..."} session_id 必须匹配 ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$，否则返回 400。可选环境变量：MODEL（默认claude-sonnet-4-6）、CLAUDE_CONFIG_DIR（默认/data，挂载该目录可持久化会话）、AGENT_AUTH_TOKEN（设置后/sessions/*需要Authorization: Bearer <token>，/health仍保持开放）。
准备 API Key：创建 hosting/.env
docker-compose.yml 中env_file指向../.env，即claude_agent_sdk/hosting/.env。仓库提供了模板 .env.example，其注释说明：拷贝为.env后填入真实 Key（.env已被 gitignore，不要提交真实 Key）。
在claude_agent_sdk/hosting/目录下把模板复制为.env，并把ANTHROPIC_API_KEY替换为你的真实 Key。可选地在同一文件里设置MODEL=claude-opus-4-6以对齐 notebook 00 的配置；不设置则使用默认的claude-sonnet-4-6。
启动服务：docker compose up
本地 Docker 层的“混合模式”（带服务器、可续接会话）由 docker/README.md 给出最短命令：
cd claude_agent_sdk/hosting/docker/ docker compose up --build--build会在启动前先构建镜像。compose 文件的构建上下文是../..（即claude_agent_sdk/目录），因为镜像需要hosting/之外的同级目录research_agent/和utils/；Dockerfile 基于python:3.11-slim，额外安装了 Node 和@anthropic-ai/claude-code@2.1.140CLI（Agent SDK 在底层通过它驱动query()），并将WORKDIR固定在/app——固定的工作目录是resume=在容器重启后仍能按$CLAUDE_CONFIG_DIR/projects/<encoded-cwd>/找到会话记录的前提。
compose 配置中的两个关键项：
ports: "127.0.0.1:8000:8000"—— 只绑定回环地址。文件内注释说明：服务器默认没有认证，所以不要默认把端口暴露到局域网，curl localhost:8000仍然可用；生产部署必须前置带认证的反向代理。volumes: ./sessions:/data—— 把./sessions挂到/data，让会话记录在容器重启后保留。command: ["serve"]—— 让 entrypoint.sh 走uvicorn hosting.server:app --host 0.0.0.0 --port 8000分支；不带serve参数时 entrypoint 会走run_once.py的一次性模式（执行完一个$PROMPT即退出，不启动服务器，见下文可选分支）。
也可以用 07_Hosting_the_agent.ipynb 中的后台形式启动并立即探测健康：
cd claude_agent_sdk/hosting/docker docker compose up --build -d sleep 3 curl -s http://localhost:8000/health检查 /health 可用性
/health的定义在 server.py：端点有意不做鉴权，因为编排器要直接探测它做存活检查，返回{"status": "ok"}。检查命令：
curl -s http://localhost:8000/health接口契约文档（hosting/README.md）给出的预期结果是200 {"status": "ok"}。拿到这个响应，说明容器已启动、端口映射生效、服务可用；-d形式下没有输出则先docker compose logs查看容器是否仍在启动。
在另一个终端发送提示词验证消息端点（-N关闭 curl 缓冲，事件随到随显）：
curl -N -X POST http://localhost:8000/sessions/demo-1/messages \ -H 'Content-Type: application/json' \ -d '{"prompt":"What are the latest AI agent trends?"}' # 追问一轮 —— agent 记得上一轮： curl -N -X POST http://localhost:8000/sessions/demo-1/messages \ -H 'Content-Type: application/json' \ -d '{"prompt":"Tell me more about the second one."}'流中会出现message事件（序列化的 SDK 消息）、done事件（本轮结束）或error事件。追问同一session_id时 agent 能接上上文，说明会话恢复链路（/data下的记录 + 持久化的外部/SDK session_id 映射）正常工作。
验证持久化：重启后上下文仍在
docker/README.md 给出重启验证方式：停止容器，再次docker compose up，对demo-1再发一条追问——由于./sessions持久化了/data，agent 仍保留之前的上下文。这是“/data 挂载生效”的直接判据。
安全边界与限制
- 服务器默认没有任何认证（server.py 和 hosting/README.md 都明确警告）：它信任任何能到达 8000 端口的人，必须置于一个（1）认证调用方、（2）只转发属于该调用方的
session_id的网关/代理之后，不能把 8000 端口直接暴露到互联网。本地 compose 只绑定127.0.0.1正是对应这一限制。 - 没有网关的部署形态（如 Modal 公开隧道）可设置
AGENT_AUTH_TOKEN作为最小替代：/sessions/*将要求Authorization: Bearer <token>。文档强调它不是网关的替代品，不能把session_id限定到调用方。 - 服务器不会自行终止，空闲容器的清理由编排器负责。
- 请求体超过 256 KB 时（带
Content-Length的请求）返回413。
可选分支：一次性（ephemeral）模式
如果任务是批处理、一次性分析这类“没有对话需要续接”的作业，不需要服务器。hosting/README.md 的构建命令和 docker/README 的一次性命令：
cd claude_agent_sdk/ docker build -f hosting/Dockerfile -t research-agent . docker run --rm \ -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \ -e PROMPT="What is the Claude Agent SDK?" \ research-agent不带serve参数时 entrypoint 走run_once.py：用$PROMPT调一次 agent、打印结果、退出。此模式不启动 HTTP 服务，也就没有/health可查。
下一步
本地验证通过后，07_Hosting_the_agent.ipynb 指出GET /health已内置于server.py，可直接作为编排器的存活探针使用（compose 的healthcheck:、Modal 健康检查、Kubernetes 的livenessProbe）。同一镜像和接口契约下，仓库还提供了 Tier 2（Modal Sandbox，modal/）与 Tier 3（Kubernetes 每会话一个 pod，kubernetes/）两条部署路径，可对照 hosting/README.md 的目录说明继续查看。
【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
