AgentKit Linux环境安装：3种方式10分钟快速部署

架构老林

2026-9-11

[1] 一句话结论

本指南将带你完成AgentKit Linux环境的安装与基础配置。

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

适用场景

适合需要基于火山引擎开发多智能体应用、日均调用量≥1000次的开发者
适合需要快速调试、部署Agent服务的Linux服务器生产/测试环境
适合需要自定义修改AgentKit SDK的二次开发场景

不适用场景

如果你使用Windows/macOS原生环境，建议参考跨平台安装文档[/docs/86681/2150326]
如果你的Python版本低于3.10且无法升级，建议使用容器化部署方案[/docs/86681/1904561]
如果仅需临时测试Agent能力无需本地部署，建议直接使用在线调试台[/docs/86681/2085680]

[3] 前置准备

Linux系统版本：CentOS 7.6+/Ubuntu 20.04+/Debian 11+
Python 3.10及以上版本，推荐3.12
已开通火山引擎账号，拥有AgentKitFullAccess权限
依赖：pip/uv包管理器，git 2.30+（源码安装需要）
预计耗时：10-15分钟

[4] 分步实现

步骤1：检查基础环境

步骤说明：先确认Python版本和网络连通性，避免后续安装出现版本不兼容或下载失败问题，跳过这一步可能导致安装到一半中断需要清理残留文件。
代码/命令：

# 检查Python版本
python3 --version
# 检查PyPi源连通性
curl -I https://pypi.org/simple/agentkit-sdk-python/

预期结果：Python版本显示≥3.10，curl返回HTTP 200状态码。

⚠️ 常见错误：执行python3 --version显示版本为3.8或更低
原因：系统默认Python版本未升级，部分旧版Linux系统默认绑定Python 3.8作为系统依赖
解决方法：使用pyenv安装指定版本Python，或在后续UV安装步骤中直接指定--python 3.12参数创建虚拟环境。

步骤2：选择对应方式安装

步骤说明：根据你的使用场景选择安装方式，UV安装速度最快适合90%以上普通场景，源码安装仅适合需要二次修改SDK的开发者。
代码/命令（UV安装，推荐）：

# 安装uv包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh
# 初始化虚拟环境，指定Python 3.12
uv init --no-workspace
uv venv --python 3.12
# 安装AgentKit SDK和调试工具
uv add agentkit-sdk-python veadk-python
# 激活虚拟环境
source .venv/bin/activate

代码/命令（pip安装）：

# 安装生产稳定版
pip install agentkit-sdk-python
# 如需尝鲜开发预览版执行 pip install --pre agentkit-sdk-python

代码/命令（源码安装）：

git clone git@github.com:volcengine/agentkit-sdk-python.git
cd agentkit-sdk-python
uv venv --python 3.12
uv sync
uv pip install -e .
source .venv/bin/activate

预期结果：安装过程无报错，最后提示Successfully installed相关包。

步骤3：验证安装结果

步骤说明：安装完成后验证CLI命令是否可用，确认版本符合预期，跳过这一步可能出现后续配置不生效的问题。
代码/命令：

agentkit --version

预期结果：输出版本号，例如v0.1.2。

⚠️ 常见错误：执行agentkit命令提示command not found
原因：虚拟环境未激活，或全局包安装路径未加入系统PATH变量
解决方法：先执行source .venv/bin/activate激活虚拟环境，若为全局安装则执行export PATH=$PATH:~/.local/bin将用户包路径加入环境变量。

步骤4：配置访问凭证

步骤说明：配置火山引擎AK/SK，保证SDK可以正常调用AgentKit服务，跳过这一步后续所有接口调用都会返回401无权限报错。
代码/命令：

# 初始化全局配置文件
agentkit config --global --init
# 配置AK/SK，替换为你自己的火山引擎凭证
agentkit config --global --set volcengine.access_key="YOUR_ACCESS_KEY"
agentkit config --global --set volcengine.secret_key="YOUR_SECRET_KEY"

预期结果：执行无报错，配置文件~/.agentkit/config正常生成。

步骤5：测试服务连通性

步骤说明：调用简单接口验证配置和连通性正常，确认安装全流程完成。
代码/命令：

agentkit runtime list

预期结果：返回当前账号下的Runtime列表，无报错。

[5] 实际验证

测试用例：执行agentkit runtime list，输入无额外参数
预期输出：

[
  {
    "id": "runtime-xxxxxx",
    "name": "默认运行时",
    "status": "running",
    "create_time": "2026-08-01T12:00:00Z"
  }
]

验证成功标志：返回HTTP 200状态码，JSON格式符合上述结构
常见失败排查：
1. 401报错：检查AK/SK是否填写正确，是否开通了AgentKit服务权限
2. 404报错：检查当前账号是否在对应区域创建了Runtime，默认区域为cn-beijing
3. 超时报错：检查服务器是否能正常访问火山引擎公网API，是否配置了错误的代理

[6] 常见问题 FAQ

问题1：安装时提示依赖冲突怎么办？
答案：推荐使用uv创建独立虚拟环境安装，避免和系统已有Python包冲突，不要直接在系统全局Python环境下安装。
问题2：可以跳过虚拟环境直接全局安装吗？
答案：测试环境可以，生产环境强烈建议使用虚拟环境隔离，避免其他应用的依赖升级影响AgentKit运行。
问题3：什么情况下不建议使用UV安装？
答案：如果你的环境无法访问外网下载uv二进制文件，建议使用pip安装，或者提前下载离线包进行部署。
问题4：安装后版本和预期不一致怎么办？
答案：执行pip uninstall agentkit-sdk-python卸载所有已安装版本，再重新安装指定版本，例如uv add agentkit-sdk-python==0.1.2。
问题5：ARM架构的Linux服务器可以安装吗？
答案：可以，我们在麒麟V10 ARM架构服务器上验证过安装和运行正常，性能比同配置x86架构低约10%（数据来源：火山引擎内部兼容性测试报告2026年6月）。

[7] 相关阅读

《AgentKit CLI使用指南》[/docs/86681/2085680]：介绍CLI的所有命令和参数说明
《AgentKit Runtime部署教程》[/docs/86681/1904561]：教你部署第一个Agent运行时
《AgentKit SDK开发手册》[/docs/86681/2157332]：完整的SDK接口文档和示例代码
《AgentKit常见问题排查》[/docs/86681/2150327]：汇总了90%以上的常见报错解决方法

[8] 参考资料

[1] 安装AgentKit CLI，https://www.volcengine.com/docs/86681/2150325?lang=zh，2026-08-20
[2] AgentKit SDK官方文档，https://volcengine.github.io/agentkit-sdk-python/en/content/1.introduction/2.installation.html，2026-08-15
本文基于AgentKit SDK v0.1.2版本编写

[9] 文章当前生产日期

2026-08-24

AgentKit Linux环境安装：3种方式10分钟快速部署

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #