将 Agent 从开发环境推进到生产，远不止打包一个镜像或上传一段代码。生产环境要求服务具备稳定的启动流程、严格的配置隔离、可追踪的调用链路以及可快速恢复的发布策略。本文按照上线前、部署中、运行后三个阶段，整理一份可落地的清单，并给出关键配置示例，帮助团队在发布前逐项核查。
环境隔离与配置管理
开发、测试、生产三个环境绝不能共用同一份配置文件，更不能把生产数据库地址或第三方服务密钥硬编码在代码中。推荐的做法是使用环境变量注入运行时配置，本地开发可以借助 .env 文件快速切换，但生产环境必须通过容器编排的 Secret 或配置中心分发。这样即使代码仓库发生泄漏，攻击者拿到的也只是变量名，而不是真实的凭证。
配置管理还要区分启动配置与业务配置。启动配置包括监听端口、日志级别、模型调用超时等，适合用环境变量；业务配置如 Agent 可用的工具列表、提示词模板、模型别名等，可以放在配置中心或数据库中，支持动态更新而不必重新发布镜像。下面是一个读取环境变量的最小示例，展示了如何避免默认值导致生产环境误用开发配置。
import os
AGENT_API_KEY = os.environ.get("AGENT_API_KEY")
if not AGENT_API_KEY:
raise RuntimeError("AGENT_API_KEY is required in production")
MODEL_ALIAS = os.environ.get("MODEL_ALIAS", "gpt-4o-mini")
TOOL_CALL_TIMEOUT = int(os.environ.get("TOOL_CALL_TIMEOUT", "10"))
注意，这里的 MODEL_ALIAS 虽然给了默认值，但生产环境应通过部署清单明确禁止使用默认模型别名，因为开发环境的默认值往往指向测试模型或非生产网关。建议在部署流水线中加入配置校验步骤，检查所有必需变量是否存在且非空。
密钥管理与模型版本锁定
密钥管理是生产部署中最容易出事的环节。不要把 API Key、数据库密码或模型访问令牌写入 Dockerfile、docker-compose 文件或应用的配置文件。容器编排平台提供的 Secret 机制可以把敏感信息以文件或环境变量形式挂载到容器中，且不会出现在镜像构建历史里。对于 Kubernetes，可以使用 Secret 资源配合环境变量引用；对于 Docker Compose，可以使用 secrets 配置块。
除了存储，还要制定密钥轮换策略。大模型服务的访问令牌建议每 90 天轮换一次，数据库密码建议按季度轮换。轮换时要保证旧密钥在过渡期内仍然有效，避免直接删除导致线上调用全部失败。可以使用密钥管理服务如 Vault 或云厂商的 KMS，让应用在启动时动态获取凭证，而不是静态配置。
模型版本锁定同样关键。Agent 的提示词工程和工具调用逻辑往往针对某个模型版本做了调优，如果上游模型供应商悄悄升级底层权重，可能导致输出格式变化或工具调用失败。在生产环境中，应通过模型别名或部署配置锁定具体版本，例如 gpt-4o-2024-11-20，而不是使用 latest 或 default。发布前要确认模型版本是否与测试阶段一致，必要时在配置中心保留版本快照。
依赖固化也不能忽视。Python 项目应提交 requirements.txt 或 poetry.lock，Node 项目提交 package-lock.json，确保构建出的镜像在任何时间点都能复现相同的依赖树。下面是一个 Docker Compose 中挂载 Secret 的片段。
services:
agent-api:
image: agent-api:1.4.2
secrets:
- agent_api_key
environment:
- MODEL_ALIAS=gpt-4o-2024-11-20
- TOOL_CALL_TIMEOUT=15
deploy:
replicas: 2
secrets:
agent_api_key:
external: true
这个示例中，agent_api_key 来自 Docker 的 external secret，不会写入 Compose 文件。模型别名也通过环境变量固定，避免使用动态 latest 版本。
可观测性与健康检查
生产 Agent 必须具备可观测性，否则出现问题时只能靠猜测。健康检查分为存活探针和就绪探针：存活探针用于判断进程是否还活着，就绪探针用于判断服务是否已经准备好接收流量。对于 Agent 服务，就绪检查可以包含外部模型网关的连通性测试，但不要因为外部依赖暂时不可用就让 Pod 反复重启；更好的做法是存活检查只探测本地端口，就绪检查探测关键依赖并返回明确状态。
日志方面，应当输出结构化 JSON，而不是无格式的文本行。每条日志至少包含 trace_id、agent_id、operation、latency_ms 和 error_code。这样在排查某次调用失败时，可以用 trace_id 串联起 Agent 内部推理、工具调用、模型请求的完整链路。避免在日志中打印完整的 API 响应，尤其是包含用户输入或敏感业务数据的内容。
指标采集建议暴露 Prometheus 格式的 /metrics 端点，核心指标包括请求量、请求延迟分位数、模型调用失败率、Token 消耗量以及工具调用超时次数。告警阈值可以设置为：错误率超过 5% 持续 5 分钟触发 P2，超过 15% 触发 P1。下面给出一个 FastAPI 健康检查端点的示例。
from fastapi import FastAPI
from fastapi.responses import JSONResponse
import time
app = FastAPI()
@app.get("/health")
def liveness():
return {"status": "alive"}
@app.get("/readiness")
def readiness():
model_ok = check_model_gateway()
db_ok = check_database_connection()
ready = model_ok and db_ok
status_code = 200 if ready else 503
return JSONResponse(
status_code=status_code,
content={
"ready": ready,
"model_gateway": model_ok,
"database": db_ok,
},
)
这个示例中 check_model_gateway 和 check_database_connection 应实现为带超时的轻量级探测，避免探针本身拖垮服务。就绪检查失败时返回 503，反向代理或编排系统会自动把流量摘除，但不会重启容器。
资源限制、超时与灰度发布
Agent 服务常常需要调用外部模型或执行工具，单次请求可能持续数秒甚至更久。如果不设置资源限制和超时控制，突发流量会迅速耗尽连接池和内存，导致雪崩。容器层应设置 CPU 和内存上限，例如单实例限制 1 核 CPU、1024 MiB 内存，并在应用层实现请求超时、连接池上限和重试策略。
对于模型调用，建议设置三层超时：连接超时、读取超时和总超时。连接超时可以设为 3 秒，读取超时根据模型响应速度设为 30 到 60 秒，总超时设为 120 秒。工具调用同样要有超时，并区分可重试错误和不可重试错误。例如网络抖动导致的超时可以重试一次，但模型返回格式错误不应盲目重试，否则会放大故障。
灰度发布是降低生产风险的关键手段。不要一次性将所有流量切到新版本，可以按 5% 到 10% 的比例逐步放量，观察错误率、延迟和 Token 消耗是否正常。对于 Kubernetes，可以使用 Ingress 的权重路由；对于通用反向代理，可以用 Nginx 的 upstream 权重。下面是一个 Nginx 灰度配置片段。
upstream agent_backend {
server 10.0.0.11:8000 weight=90;
server 10.0.0.12:8000 weight=10;
}
server {
listen 80;
location / {
proxy_pass http://agent_backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_read_timeout 120s;
proxy_connect_timeout 3s;
}
}
上面配置中，新版本实例只承接 10% 的流量。灰度期间要保存好旧版本镜像，一旦新版本在真实流量下暴露出问题，可以快速切回。资源限制可以在 Docker Compose 或 Kubernetes 中配置，下面给一个 Compose 的简例。
services:
agent-api:
image: agent-api:1.4.2
deploy:
resources:
limits:
cpus: "1.0"
memory: 1024M
reservations:
cpus: "0.25"
memory: 256M
environment:
- TOOL_CALL_TIMEOUT=15
- MODEL_CALL_TIMEOUT=60
回滚策略与应急预案
发布前必须明确回滚条件：当错误率超过阈值、P95 延迟显著增加、或核心工具调用连续失败时，立即停止灰度并切回旧版本。回滚操作不应依赖重新构建镜像，而是直接修改路由权重或使用上一版本的镜像标签。所以每次构建镜像时都要保留版本标签，禁止使用 latest 覆盖旧镜像。
数据库迁移要遵循向前兼容原则：先加字段，再在新代码中读取；确认稳定后再删除旧字段。避免在迁移脚本中直接删除列或修改约束，否则旧版本服务可能无法启动。如果使用外部模型服务，回滚时要同步检查模型版本是否与旧版本匹配，必要时将模型别名切回上一版本。
应急预案还应包括降级方案。例如当模型网关不可用时，Agent 可以切换为本地缓存响应或直接返回明确错误，而不是无限重试。为关键工具调用准备降级路径，如将实时搜索降级为历史知识库查询。定期演练故障场景，确保团队熟悉回滚命令和告警处理流程。发布检查表可以固化在 CI/CD 流水线中，包括：配置校验、密钥存在性、镜像扫描、健康检查通过、灰度比例确认、回滚预案评审。