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_BUILDKIT1环境变量执行构建。一个有效的ANTHROPIC_API_KEY。服务器将其列为必需环境变量。已获取claude-cookbooks仓库代码。下文命令默认在仓库根目录执行。接口契约三层部署共同遵守来自 hosting/README.mdGET /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/.envdocker-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。可选地在同一文件里设置MODELclaude-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-code2.1.140CLIAgent 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持久化了/dataagent 仍保留之前的上下文。这是“/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 PROMPTWhat 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 2Modal Sandboxmodal/与 Tier 3Kubernetes 每会话一个 podkubernetes/两条部署路径可对照 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），仅供参考