AgentKit智能体生产环境部署注意事项(完整代码)

这三类高频故障点，容器镜像构建陷阱、权限校验断连、状态持久化丢失，必须绕过去，不然上线之后，502错误、会话中断、工具调用静默失败这些问题就会出现。部署的时候，得按照VeADK/非VeADK路径来区分，环境变量、镜像标签、Redis状态后端、MCP工具白名单都要严格配置，健康检查和冷启动预热也要启用。

将本地开发完成的AgentKit智能体推入生产环境时，必须绕过容器镜像构建陷阱、权限校验断连、状态持久化丢失这三类高频故障点，否则服务上线后会出现502错误、会话中断或工具调用静默失败。

确认运行时依赖与模型接入方式

检查当前Agent是否使用VeADK框架开发：若pyproject.toml中存在volcengine-veadk依赖且主入口含@agentkit.entry装饰器，则走VeADK原生部署路径；否则进入通用容器托管模式。

VeADK项目需确保agent.yaml中model.provider字段明确指定为volcengine或openai等平台已纳管的供应商，不可填写本地Ollama地址——

。

非VeADK项目（如LangChain/LangGraph构建）必须提供Dockerfile，且基础镜像必须继承python:3.11-slim或更轻量版本，避免因glibc版本不兼容导致工具调用崩溃。

配置生产级环境变量

在AgentKit控制台创建环境变量组，按以下顺序设置：

① AGENTKIT_ENV=production —— 触发平台启用熔断、重试、日志采样等生产策略；

② LOG_LEVEL=WARNING —— 关闭DEBUG日志，防止敏感上下文泄露至云日志服务；

③ MEMORY_BACKEND=redis://:password@redis-prod:6379/0 —— 必须显式声明Redis连接串，

；

④ MCP_TOOL_WHITELIST=database_query,file_upload,http_request —— 限制可调用MCP工具范围，未列入清单的工具在运行时直接拒绝执行。

构建并推送容器镜像（非VeADK项目必选）

方法一：使用AgentKit CLI自动构建

执行agentkit build --context ./my-agent --tag mycorp/inventory-agent:v1.2，CLI将自动识别requirements.txt和entrypoint.sh生成符合平台规范的镜像。

方法二：手动构建并推送至私有仓库

首先要在项目的根目录下编写Dockerfile，注意哦，首行必须写为FROM python:3.11-slim，最后还要添加CMD ["uvicorn", "app:app", "--host", "0.0.0.0:8000", "--port", "8000"]；构建完成后接着执行docker tag my-agent:latest harbor.mycorp.com/ai/my-agent:v1.2 && docker push harbor.mycorp.com/ai/my-agent:v1.2。

注意：镜像标签必须为语义化版本号（如v1.2），不能使用latest——

。

设置弹性扩缩容与健康检查

在AgentKit控制台「部署配置」页签中：

将最小副本数设为2，最大副本数设为10，CPU请求值填500m，内存请求值填1Gi；

健康检查路径填/healthz，超时时间设为3秒，失败阈值设为3次；

启用「冷启动预热」开关，预热请求并发数设为5——该功能会在新副本就绪前主动发起5次空载请求，避免首个真实请求遭遇长尾延迟。

绑定MCP工具并验证权限

第一步：进入「工具管理」→「MCP注册中心」，点击「同步存量工具」，等待平台扫描出所有已声明的mcp-server端点；

第二步：勾选需要授权给当前Agent使用的工具，点击「批量授权」；

第三步：在「服务调用审计」页签中，触发一次测试对话，输入“查询库存大于100的商品”，观察日志中是否出现mcp://database_query?params=...调用记录及返回状态码200；

若日志中仅显示tool not authorized，说明第二步授权未生效，需退出控制台重新登录后再操作一次。