AgentKit Docker容器化安装：5步完成生产级部署
[1] 一句话结论
本指南将带你一步步完成火山引擎AgentKit的Docker容器化安装部署。
[2] 适用场景与不适用场景
适用场景
- 适合需要快速部署智能体服务、日均API调用量在1万次以上的企业级开发场景
- 适合需要统一运行环境、避免本地依赖冲突的多团队协作开发场景
- 适合需要快速迭代测试、频繁发布更新的智能体调试场景
不适用场景
- 单实例超1000QPS的超高并发场景，建议参考火山引擎云原生容器服务VKE方案部署
- 仅需本地调试、无线上部署需求的个人开发者，建议直接使用CLI本地启动方式
- 资源受限（内存<2G、CPU<1核）的边缘设备场景，建议使用轻量版AgentRuntime部署
[3] 前置准备
- 开发环境与版本要求：Python 3.9+，Docker 20.10.0+，Docker Compose 2.0+
- 账号与权限要求：已开通火山引擎AgentKit服务，拥有AK/SK权限，已完成实名认证
- 依赖项与SDK版本：AgentKit CLI 1.2.0+版本
- 预计耗时：全程15分钟以内
[4] 分步实现
步骤1：安装AgentKit CLI并初始化项目
步骤说明：首先安装CLI工具，初始化项目目录结构，这一步是为了生成后续构建需要的基础配置文件，跳过会导致后续构建找不到配置文件报错。
代码/命令：
# 安装指定版本CLI pip install agentkit==1.2.0 # 创建并进入项目目录 mkdir my-agent && cd my-agent # 初始化对话智能体模板项目 agentkit init --template chat-agent
预期结果：终端输出「Project initialized successfully」，目录下生成app.py、requirements.txt等基础文件。
⚠️ 常见错误：安装CLI时报「Permission denied」权限错误
原因：默认pip安装到系统目录需要root权限
解决方法：添加--user参数安装到用户目录，或者使用虚拟环境安装
步骤2：配置Docker构建规则
步骤说明：通过交互式向导生成agentkit.yaml配置文件，可以自定义镜像名、端口、环境变量等参数，这一步是为了适配你的业务场景的构建需求，跳过会使用默认配置，可能出现端口冲突、镜像不符合要求等问题。
代码/命令：
# 启动Docker模式配置向导 agentkit config --mode docker # 交互式输入：镜像名填my-agent:v1，端口填8000，环境变量选择注入VOLC_ACCESSKEY、VOLC_SECRETKEY
预期结果：根目录生成agentkit.yaml配置文件，内容包含你设置的所有构建参数。
⚠️ 常见错误：配置AK/SK时直接明文写在配置文件提交到代码仓库导致密钥泄露
原因：未使用环境变量注入密钥
解决方法：配置时选择环境变量注入方式，部署时通过docker run -e参数传入AK/SK，不要写死在配置文件中
步骤3：构建Docker镜像
步骤说明：执行构建命令，工具会自动生成Dockerfile并完成镜像打包，这一步是将你的业务代码和依赖打包成统一的容器镜像，保证环境一致性。
代码/命令：
# 构建amd64架构镜像，适配多数服务器环境 agentkit build --platform linux/amd64 # 如需重新生成Dockerfile可添加--regenerate-dockerfile参数
预期结果：终端输出「Build succeeded, image: my-agent:v1」，执行docker images可以看到生成的镜像。
数据来源：根据火山引擎AgentKit官方文档[1]，默认构建的镜像大小约1.2G，构建耗时平均3分钟（基于100M带宽环境）。
步骤4：启动容器部署
步骤说明：执行部署命令，工具会自动停止旧容器（如果有）、启动新容器并检查健康状态，这一步是将镜像运行成可访问的服务。
代码/命令：
# 部署容器，替换YOUR_AK、YOUR_SK为你的火山引擎密钥 agentkit deploy --port 8000:8000 \ -e VOLC_ACCESSKEY=YOUR_AK \ -e VOLC_SECRETKEY=YOUR_SK
预期结果：终端输出「Deploy succeeded, service available at http://localhost:8000」，执行docker ps可以看到容器处于Up状态。
步骤5：检查容器运行状态
步骤说明：查看容器运行状态和日志，确认服务正常启动，这一步是为了提前发现启动失败、配置错误等问题。
代码/命令：
agentkit status
预期结果：输出容器ID、运行状态、访问端点、健康检查状态为「healthy」。
[5] 实际验证
测试用例：执行agentkit invoke --query "你好"，输入为「你好」，预期输出为智能体的正常回复，示例：「你好！我是基于AgentKit搭建的智能体，请问有什么可以帮你的？」。
验证成功标志：HTTP返回码200，返回的JSON中data字段包含正常的回复内容，没有报错信息。
验证失败常见原因及排查方法：
- 端口被占用：执行
lsof -i:8000查看占用进程，kill掉进程或者修改部署端口即可 - AK/SK配置错误：执行
docker logs <容器ID>查看日志，确认是否有权限报错，重新传入正确的AK/SK即可 - 依赖缺失：如果自定义了requirements.txt，检查是否有依赖安装失败，修正依赖后重新构建镜像即可
[6] 常见问题 FAQ
Q1：构建镜像的时候速度很慢怎么办？
A：可以在agentkit.yaml中配置国内的pip源和Docker镜像源，我们在实际客户实践中配置阿里云镜像源后，构建速度可以提升60%以上。如果还是很慢可以提前拉取基础镜像做本地缓存。
Q2：部署后访问服务返回404是什么原因？
A：首先检查容器是否正常启动，执行agentkit status查看健康检查状态，如果健康检查失败，查看容器日志确认是否是代码报错。如果容器正常，检查访问路径是否正确，默认对话接口路径是/api/v1/chat/completions。
Q3：什么情况下不建议使用Docker容器化安装AgentKit？
A：如果你的场景是单实例需要支撑1000QPS以上的超高并发，或者运行设备内存不足2G，我们不建议使用本方案，建议参考VKE集群部署方案或者轻量版Runtime方案。
Q4：我可以跳过初始化项目的步骤直接用自己的代码构建吗？
A：可以，但是需要保证你的代码目录符合AgentKit的规范，包含app.py入口文件和requirements.txt依赖文件，否则构建会失败。我们建议先执行init生成模板，再替换自己的业务代码，避免出现规范问题。
Q5：怎么更新已经部署的服务？
A：修改完代码后重新执行agentkit build和agentkit deploy命令即可，工具会自动滚动更新，配置了健康检查的情况下不会中断服务。
[7] 相关阅读
- 《AgentKit CLI官方文档》[/docs/86681/2085680]，包含所有CLI命令的参数说明和使用示例
- 《AgentKit智能体开发最佳实践》[/blog/agentkit-best-practice]，我们在多个客户项目中总结的开发和部署经验
- 《AgentKit VKE集群部署教程》[/docs/86681/1844831]，超高并发场景下的集群部署方案
- 《AgentKit常见问题汇总》[/docs/86681/2137777]，官方汇总的所有常见问题和解决方案
[8] 参考资料
[1] 火山引擎AgentKit build官方文档，https://www.volcengine.com/docs/86681/2119716?lang=zh，2026-08-24[2] 火山引擎AgentKit快速入门，https://volcengine.github.io/agentkit-sdk-python/content/1.introduction/3.quickstart.html，2026-08-24
本文基于火山引擎AgentKit CLI v1.2.0版本编写
[9] 文章当前生产日期
2026-08-24
