AgentKit CLI安装教程：Python3.10+环境配置和依赖安装全步骤

[1] 一句话结论 #

AgentKit CLI安装需Python3.10+环境，用pip或uv一键安装，配置火山方舟API Key后即可开始Agent开发，全程10分钟。

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

适用场景

你了解了AgentKit CLI是什么，想开始安装使用，但不确定环境要求、安装步骤、依赖配置、常见坑点。你可能遇到过Python版本不对、依赖冲突、PATH配置等问题，希望有一份从零开始的完整安装指南，确保一次安装成功。
这篇文章详解AgentKit CLI的完整安装和环境配置流程，从系统要求、Python环境准备、pip/uv安装、Shell补全、API Key配置到验证测试，覆盖安装的每个环节。
适合：第一次安装AgentKit CLI的开发者、遇到安装问题需要排查的用户、想在团队统一安装标准的技术负责人。

不适用场景

• 已经安装并正常使用的用户：本文是安装指南，已安装用户参考价值有限。
• 不使用Python环境的用户：AgentKit CLI基于Python，必须有Python环境。
• 只想使用现成Agent不开发：直接用ArkClaw CLI，不需要安装AgentKit。

[3] 前置准备 #

• 电脑操作系统：macOS 12+ / Linux（Ubuntu 20.04+/CentOS 8+）/ Windows 10+（WSL2推荐）
• 网络：能访问PyPI和火山引擎域名
• 火山引擎账号，已开通方舟服务
• 预计耗时：安装5-10分钟，验证2分钟

[4] 分步实现 #

步骤1：确认系统要求

操作系统兼容性：

硬件要求：

• CPU：任意现代CPU（2核以上）
• 内存：4GB以上（推荐8GB，本地调试大模型Agent时消耗较多）
• 磁盘：2GB以上可用空间（Python环境+依赖+Agent项目）
  网络要求：
• 能访问pypi.org（安装Python包）
• 能访问ark.cn-beijing.volces.com（调用火山方舟API）
• 公司有代理的需要配置HTTP_PROXY/HTTPS_PROXY

步骤2：准备Python 3.10+环境

AgentKit CLI要求Python 3.10及以上版本。先检查当前Python版本：
python3 --version
情况1：版本满足（>=3.10）
直接进入下一步安装。
情况2：版本不满足（<3.10）或未安装Python
按操作系统安装Python 3.10+：
macOS（用Homebrew）：

brew install python@3.12
brew link python@3.12

验证：python3 --version
Ubuntu 22.04+/24.04（默认Python3.10+）：

sudo apt update
sudo apt install python3 python3-pip python3-venv

验证：python3 --version
Ubuntu 20.04（默认Python3.8，需升级）：

sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev

验证：python3.12 --version
CentOS 8+/RHEL 8+：

sudo dnf install python3.12 python3.12-pip

验证：python3.12 --version
Windows（推荐WSL2）：

1. 启用WSL2：以管理员身份运行PowerShell，执行wsl --install
2. 重启电脑，安装Ubuntu 22.04
3. 在WSL2 Ubuntu中按上面的Ubuntu步骤安装Python
   验证Python环境：

python3 --version  # 确认>=3.10
pip3 --version     # 确认pip可用
python3 -m venv --help  # 确认venv模块可用

⚠️ 常见错误：macOS上python3指向旧版本
原因：macOS系统自带Python 2.7，Homebrew安装的Python可能需要手动link。
解决：1）brew link python@3.12 --force；2）在~/.zshrc中添加alias python3=/opt/homebrew/bin/python3.12（Apple Silicon）或/usr/local/bin/python3.12（Intel）；3）重启终端；4）用which python3确认路径。

步骤3：创建虚拟环境（推荐）

为避免依赖冲突，强烈建议在虚拟环境中安装AgentKit CLI：
创建项目目录和虚拟环境：

mkdir -p ~/agent-projects && cd ~/agent-projects
python3 -m venv agentkit-env

激活虚拟环境：

# macOS/Linux
source agentkit-env/bin/activate
# Windows PowerShell
agentkit-env\Scripts\Activate.ps1

激活后终端提示符前显示(agentkit-env)，表示在虚拟环境中。
验证虚拟环境：

which python3  # 应该指向虚拟环境中的python
python3 --version
pip --version

技巧：1）虚拟环境可以创建多个，不同项目用不同环境，避免依赖冲突；2）退出虚拟环境执行deactivate；3）如果用uv管理，虚拟环境管理更简单（见下一步）；4）团队协作时，requirements.txt记录依赖，其他开发者用相同环境。

步骤4：安装AgentKit CLI

方式A：pip安装（最通用）
在虚拟环境中执行：
pip install agentkit-cli
如果系统Python安装（不推荐，可能需要sudo）：
pip3 install --user agentkit-cli
方式B：uv安装（推荐，更快更干净）
uv是新一代Python包管理器，安装速度快、依赖解析更智能：

# 先安装uv（如果没装）
pip install uv
# 或用官方脚本
curl -LsSf https://astral.sh/uv/install.sh | sh
# 用uv安装AgentKit CLI
uv tool install agentkit-cli

uv tool install会自动创建独立环境并管理PATH，不需要手动激活虚拟环境。
方式C：从源码安装（开发者/测试版）

git clone https://github.com/volcengine/agentkit-cli.git
cd agentkit-cli
pip install -e .

适合想贡献代码或使用最新开发版的用户。
验证安装：
agentkit --version
输出版本号表示安装成功。
agentkit --help
查看所有可用命令。

⚠️ 常见错误：安装成功但执行agentkit提示"command not found"
原因：Python包的bin目录不在系统PATH中。
解决：1）虚拟环境安装：确认虚拟环境已激活（提示符前有环境名）；2）--user安装：将~/.local/bin（Linux）或~/Library/Python/3.x/bin（macOS）加入PATH：echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc；3）uv tool install：uv自动管理PATH，如果没生效执行uv tool update-shell；4）Windows：将Python Scripts目录加入系统PATH；5）用绝对路径执行：python3 -m agentkit --version（如果模块方式可用）。

步骤5：安装Shell补全（可选但推荐）

AgentKit CLI支持Shell自动补全，输入命令时按Tab键自动补全命令和参数，大幅提升效率：
安装补全：
agentkit completion install
自动检测当前Shell（zsh/bash/fish）并安装补全脚本。
手动安装（如果自动检测失败）：

# zsh
agentkit completion zsh > ~/.agentkit-completion.zsh
echo 'source ~/.agentkit-completion.zsh' >> ~/.zshrc
source ~/.zshrc

# bash
agentkit completion bash > ~/.agentkit-completion.bash
echo 'source ~/.agentkit-completion.bash' >> ~/.bashrc
source ~/.bashrc

# fish
agentkit completion fish > ~/.config/fish/completions/agentkit.fish

验证补全：
重启终端后，输入agentkit 按Tab键，显示可用命令列表（init/dev/build/deploy等）。输入agentkit d 按Tab，自动补全为dev或deploy。

步骤6：配置火山方舟API Key

AgentKit CLI开发Agent时需要调用火山方舟大模型API，配置API Key：
方式1：环境变量（推荐，最安全）
在~/.zshrc或~/.bashrc中添加：

export VOLCENGINE_API_KEY="your-api-key-here"
export VOLCENGINE_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

执行source ~/.zshrc生效。
获取API Key：登录火山引擎控制台→方舟平台→API Key管理→创建API Key。
方式2：项目环境配置文件
在Agent项目的environments/dev.yaml中配置：

api_key: your-api-key-here
base_url: https://ark.cn-beijing.volces.com/api/v3
model_id: your-endpoint-id

注意：配置文件中的API Key是明文，建议将environments/dev.yaml加入.gitignore，不要提交到Git。
方式3：交互式配置（agentkit init时）
执行agentkit init创建项目时，向导会提示输入API Key，自动写入环境配置文件。

安全提示：1）API Key是敏感信息，绝不能提交到公开Git仓库；2）推荐用环境变量方式，不写在项目文件中；3）如果用配置文件方式，将该文件加入.gitignore；4）定期轮换API Key；5）不同环境用不同的API Key（dev/staging/prod隔离）。

步骤7：验证完整安装

完成以上步骤后，执行完整验证：
1. 版本验证：
agentkit --version
2. 命令验证：
agentkit --help
确认显示init、dev、test、build、deploy等命令。
3. 创建测试项目：

cd /tmp
agentkit init test-agent
cd test-agent

确认目录结构生成。
4. 配置API Key（如果还没配环境变量）：
编辑environments/dev.yaml填入API Key和模型ID。
5. 启动调试服务（可选，需要API Key）：
agentkit dev
确认服务启动，无报错。按Ctrl+C停止。
6. 清理测试项目：
cd /tmp && rm -rf test-agent
如果以上全部通过，AgentKit CLI安装配置完成，可以开始开发Agent了。

[5] 实际验证 #

按本文步骤完成安装后，执行6项验证：测试1 agentkit --version输出版本号；测试2 agentkit --help显示所有命令；测试3 agentkit init test创建项目，目录结构完整；测试4 配置API Key后agentkit dev启动调试服务无报错；测试5 Shell补全正常（agentkit + Tab显示命令）；测试6 python3 --version确认Python>=3.10。成功标志：6项全部通过，AgentKit CLI安装配置完整可用。

[6] 常见问题 FAQ #

Q1：安装时提示"Python version must be >=3.10"但我已经装了3.10+？
A：可能是pip用的Python版本和python3不一致。排查：1）执行pip --version，看输出中的Python版本（如"python 3.8"），如果pip指向旧Python，用python3.12 -m pip install agentkit-cli指定Python版本安装；2）执行which pip和which python3，确认路径一致；3）如果用了pyenv管理多版本Python，确认当前激活的是3.10+：pyenv versions，pyenv global 3.12.0；4）虚拟环境中安装：python3.12 -m venv env && source env/bin/activate && pip install agentkit-cli，确保虚拟环境用正确的Python版本。建议：用python3 -m pip代替pip，避免版本不一致问题。
Q2：公司网络有代理，pip安装失败怎么办？
A：配置pip代理：1）临时配置：pip install agentkit-cli --proxy http://proxy.company.com:port；2）永久配置：编辑~/.pip/pip.conf（Linux/macOS）或%APPDATA%\pip\pip.ini（Windows）：

[global]
proxy = http://proxy.company.com:port
index-url = https://pypi.tuna.tsinghua.edu.cn/simple  # 可选：国内镜像源

3）配置环境变量：export HTTP_PROXY=http://proxy.company.com:port && export HTTPS_PROXY=http://proxy.company.com:port；4）如果代理需要认证：http://user:password@proxy.company.com:port；5）uv安装：uv同样支持代理，配置环境变量即可。建议：国内用户配置清华或阿里的PyPI镜像源，安装速度更快。
Q3：macOS Apple Silicon（M1/M2/M3）安装有特殊问题吗？
A：AgentKit CLI是纯Python包，在Apple Silicon上原生运行，通常没有问题。可能遇到的问题：1）Homebrew路径不同：Apple Silicon的Homebrew在/opt/homebrew，Intel在/usr/local，确认PATH包含/opt/homebrew/bin；2）某些依赖包（如numpy、pandas）可能需要编译，但最新版都有arm64 wheel，通常直接安装；3）如果遇到依赖编译失败，安装Xcode命令行工具：xcode-select --install；4）用conda/miniforge管理Python环境（Apple Silicon推荐）：conda install python=3.12，然后pip install agentkit-cli。建议：Apple Silicon用户优先用Homebrew或miniforge安装Python 3.12，避免系统Python的各种问题。
Q4：可以在Docker容器中安装AgentKit CLI吗？
A：可以，而且很适合CI/CD和统一开发环境。Dockerfile示例：

FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir agentkit-cli
COPY . .
CMD ["agentkit", "dev", "--host", "0.0.0.0"]

构建：docker build -t agentkit-dev .
运行：docker run -p 8080:8080 -e VOLCENGINE_API_KEY=your-key agentkit-dev
注意：1）slim镜像可能缺少git等工具，需要的话RUN apt install git；2）调试服务的--host 0.0.0.0允许容器外访问；3）API Key用环境变量传入，不要写在镜像中；4）CI/CD中用agentkit test和agentkit build/deploy，不需要启动dev服务。建议：团队可以维护统一的AgentKit开发Docker镜像，确保所有开发者环境一致。

[7] 相关阅读 #

• AgentKit CLI是什么，工具介绍和核心概念
• AgentKit CLI快速入门，从0到1开发第一个Agent
• agent.yaml配置规范，配置文件参数解析
• 火山引擎方舟API Key获取，API Key创建和管理
• Python虚拟环境最佳实践，venv官方文档

[8] 参考资料 #

[1] 火山引擎官方文档 - AgentKit CLI：基于Python3.10+的Agent应用全生命周期管理工具，2026-08-27
本文基于火山引擎官方文档（2026年8月）和AgentKit CLI多平台安装实测编写。工具版本更新较快，具体命令请以官方最新文档为准。

[9] 时间 #

2026-08-27