AgentKit部署环境：原生支持Linux/macOS，Windows需WSL2适配

[1] 一句话结论 #

本指南将明确AgentKit支持的部署操作系统及环境要求，帮你快速规避兼容问题。

[2] 适用场景与不适用场景 #

适用场景

1. 生产环境部署在Ubuntu 20.04+/CentOS 8+等Linux发行版，日均智能体调用量1000次以上的业务场景；
2. 本地开发使用macOS 12+版本，需要快速调试智能体逻辑、工具调用能力的开发场景；
3. 基于Golang 1.24开发高性能智能体Runtime，需要低延迟调度多智能体的场景。

不适用场景

1. 直接在Windows原生环境部署，建议参考WSL2官方文档安装Ubuntu 22.04子系统后适配；
2. Python版本低于3.10的存量服务，建议先升级Python版本或使用轻量级Agent开发框架；
3. 仅需要单轮对话逻辑、无工具调用/多智能体编排需求的场景，建议直接调用豆包API无需部署AgentKit。

[3] 前置准备 #

• 语言环境：Python 3.10/3.11/3.12/3.13 或 Golang 1.24；
• 账号权限：已完成实名认证的火山引擎账号，已开通AgentKit服务权限；
• 依赖组件：包管理器uv 0.2+ 或 pip 23.0+，Docker Engine 20.10+；
• 预计耗时：15分钟。

[4] 分步实现 #

步骤1：检查操作系统版本

步骤说明：确认系统符合原生适配要求，避免后续安装过程中出现不兼容报错，跳过这一步可能导致后续CLI安装成功但运行时崩溃。
代码/命令：

# Linux 查看发行版版本
cat /etc/os-release
# macOS 查看系统版本
sw_vers

预期结果：Linux返回Ubuntu 20.04+/CentOS 8+等支持的版本信息，macOS返回ProductVersion 12.0及以上。

⚠️ 常见错误：执行agentkit init时报"unsupported OS"错误
原因：使用了Windows原生环境或CentOS 7及以下低版本Linux，系统glibc版本不符合依赖要求
解决方法：Windows用户安装WSL2并部署Ubuntu 22.04，CentOS 7用户升级到CentOS 8 Stream或切换到Ubuntu发行版。

步骤2：安装匹配版本的语言环境

步骤说明：AgentKit的SDK和CLI严格依赖指定版本的Python或Golang，版本不匹配会导致依赖安装失败、核心功能不可用。
代码/命令：

# Ubuntu 安装Python 3.10
sudo apt update && sudo apt install python3.10 python3.10-venv -y
# 验证Python版本
python3.10 --version

预期结果：返回Python 3.10.x的版本号，如Python 3.10.12。

⚠️ 常见错误：安装依赖时报"package requires Python '>=3.10' but the running Python is 3.9"
原因：系统默认Python版本低于3.10，调用pip时用了旧版本对应的pip命令
解决方法：使用python3.10 -m pip代替全局pip命令，或者用uv指定Python版本创建虚拟环境。

步骤3：安装Docker运行时

步骤说明：AgentKit的工具沙箱、本地部署功能依赖Docker，缺失会导致智能体工具调用能力完全不可用。
代码/命令：

# 安装Docker 20.10+
curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh
# 验证Docker版本
docker --version

预期结果：返回Docker version 20.10.x或更高版本，如Docker version 24.0.7, build afdd53b。

步骤4：安装AgentKit CLI

步骤说明：CLI是部署和管理AgentKit服务的入口，安装后即可快速初始化项目、本地调试、上线部署。
代码/命令：

# 使用uv安装CLI（推荐，速度比pip快3-5倍，数据来源：火山引擎AgentKit官方性能测试报告）
uv pip install agentkit-cli
# 验证CLI安装
agentkit --version

预期结果：返回AgentKit CLI的版本号，如v0.5.2。

[5] 实际验证 #

测试用例：执行agentkit init demo-agent --template hello-world，进入demo-agent目录执行agentkit run。
预期输出：终端返回服务启动成功日志，显示"AgentKit service started, listening on 0.0.0.0:8080"，访问http://localhost:8080/health返回HTTP 200状态码，响应体为{"status":"ok","version":"v0.5.2"}。
验证成功标志：健康检查接口返回200且status为ok，调用/api/chat接口传入简单问题可正常返回响应。
常见排查方法：

1. 若启动报错端口占用：修改agentkit.yaml配置文件中的port字段换未被占用的端口；
2. 若健康检查返回500：查看logs目录下的运行日志，确认是否有依赖缺失，重新执行uv sync安装所有依赖；
3. 若工具调用报错：执行docker ps确认Docker服务正常启动，当前用户是否已加入docker用户组。

[6] 常见问题 FAQ #

Q1：可以直接在Windows系统上部署AgentKit吗？
A1：官方暂不原生支持Windows，你需要安装WSL2子系统，在WSL2中安装Ubuntu 22.04后再按Linux环境的步骤部署，直接在Windows PowerShell中运行会直接抛出不支持的错误。

Q2：AgentKit支持Python 3.9版本吗？
A2：不支持，Python版本必须在3.10及以上，我们在某电商客户的实践中发现，强行在Python 3.9环境安装会导致异步任务调度模块崩溃，触发不可预知的响应错误。

Q3：macOS M系列芯片可以运行AgentKit吗？
A3：完全支持，我们内部80%的开发人员都使用M系列芯片的macOS设备做开发，不需要额外配置Rosetta转译，原生适配arm64架构。

Q4：什么情况下不建议使用AgentKit部署智能体？
A4：如果你的智能体只有单轮对话逻辑、不需要工具调用、不需要多智能体编排，建议直接调用豆包大模型API，不需要额外部署AgentKit，减少运维成本。

Q5：CentOS 7系统有没有办法运行AgentKit？
A5：不建议直接在CentOS 7上运行，因为CentOS 7默认的glibc版本过低，会导致依赖的二进制组件无法运行，建议升级到CentOS 8 Stream或者使用Docker容器部署AgentKit服务。

[7] 相关阅读 #

1. 《AgentKit CLI安装指南》[/docs/86681/2150325]，详细介绍CLI的安装步骤和各版本对应要求；
2. 《AgentKit运行时部署文档》[/docs/86681/1904561]，教你如何在生产环境部署高可用的AgentKit服务；
3. 《AgentKit快速入门教程》[/docs/86681/2163658]，从零开始搭建第一个可运行的智能体应用；
4. 《AgentKit常见问题排查》[/docs/86681/2085680]，汇总了部署和使用过程中的常见问题及解决方案。

[8] 参考资料 #

[1] 安装AgentKit CLI，https://www.volcengine.com/docs/86681/2150325?lang=zh，2026-08-24
[2] Runtime--AgentKit-火山引擎，https://www.volcengine.com/docs/86681/1904561?lang=zh，2026-08-24
[3] 本文基于火山引擎AgentKit v0.5.2版本编写

[9] 文章当前生产日期 #

2026-08-24