快速开始

本教程介绍如何安装 AgentKit CLI、配置云端凭证、创建项目并部署一个可调用的智能体。运行时是云端承载智能体应用的服务，部署后可在终端发送消息并查看回答本文按 AgentKit CLI 0.54.0 的公开命令维护，终端示例使用 Bash 或 zsh

前置条件

可访问 AgentKit 的火山引擎或 BytePlus 账号，并拥有目标区域中创建运行时及相关构建资源的权限
对应平台可调用的模型名称、模型 API 地址和 API Key
使用浏览器登录时，能够访问对应云控制台或组织提供的 SSO 地址

云端管理凭证用于创建和管理资源，模型 API Key 用于智能体调用模型，两者用途不同

安装并检查版本

安装脚本下载独立二进制，无需 Node.js。选择本机已有的下载工具：

curl
wget

curl -fsSL https://agentkit-cli.tos-cn-beijing.volces.com/install.sh | sh

wget -qO- https://agentkit-cli.tos-cn-beijing.volces.com/install.sh | sh

安装脚本会更新 shell 启动配置，使 agentkit 和别名 ak 可用。按脚本输出重新加载配置或打开新终端，再检查版本和帮助：

agentkit --version
agentkit --help

确认终端输出版本号和命令列表后继续；安装目录和已有 Python 命令的处理见本页「安装选项」

配置云端凭证

选择一种与目标云平台匹配的方式。环境变量示例必须在后续执行部署的同一终端中运行，并替换占位符：

火山引擎 AK/SK
BytePlus AK/SK
控制台登录
组织 SSO

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"
export VOLCENGINE_REGION="cn-beijing"

export BYTEPLUS_ACCESS_KEY="your-access-key"
export BYTEPLUS_SECRET_KEY="your-secret-key"

在创建项目后，按下方 BytePlus 配置步骤显式设置云厂商与区域

火山引擎账号执行：

agentkit --provider volcengine login --console
agentkit --provider volcengine whoami

BytePlus 账号执行：

agentkit --provider byteplus login --console
agentkit --provider byteplus whoami

浏览器授权完成后，whoami 应显示所选云平台的登录身份。远程服务器使用 login --remote，按提示在另一台设备完成授权

使用组织提供的 SSO 地址登录：

agentkit login <sso-address>
agentkit whoami

此路径需要换取可管理云资源的短期 STS 凭证。不要为本教程添加 --identity-only，该选项仅保存用户身份会话，不能用于后续资源部署

环境中的有效 AK/SK 优先于登录缓存，登录不会覆盖已有环境凭证。SSO 凭证过期后重新登录；云厂商选择与凭证优先级见鉴权与登录

创建并配置项目

创建项目目录

在准备存放项目的父目录执行。--directory 指定文件写入位置，项目名称本身不会创建同名子目录：

agentkit init my-agent --template basic --directory my-agent
cd my-agent

当前目录应包含 my-agent.py、requirements.txt、agentkit.yaml 和 .dockerignore。后续配置、部署和调用命令均在此目录执行

设置云平台与模型

选择与凭证匹配的平台，并将模型名称与 API Key 替换为账号可用的值：

火山引擎
BytePlus

agentkit config --launch_type cloud --cloud_provider volcengine --region cn-beijing
export MODEL_AGENT_NAME="your-ark-model-name"
export MODEL_AGENT_API_BASE="https://ark.cn-beijing.volces.com/api/v3/"
export MODEL_AGENT_API_KEY="your-ark-api-key"

agentkit config --launch_type cloud --cloud_provider byteplus --region ap-southeast-1
export MODEL_AGENT_NAME="your-modelark-model-name"
export MODEL_AGENT_API_BASE="https://ark.ap-southeast.bytepluses.com/api/v3"
export MODEL_AGENT_API_KEY="your-modelark-api-key"

agentkit config 更新项目根目录的 agentkit.yaml。本教程使用云端构建和部署模式；更多配置见配置命令

将模型配置传入运行时

下方命令会把当前环境变量的值写入 agentkit.yaml，其中包含真实模型 API Key。执行前，在 .gitignore 和 .dockerignore 中各添加 agentkit.yaml 与 .env，避免提交凭证或将其复制进镜像；不存在的忽略文件需自行创建

agentkit config \
  --runtime_envs "MODEL_AGENT_NAME=$MODEL_AGENT_NAME" \
  --runtime_envs "MODEL_AGENT_API_BASE=$MODEL_AGENT_API_BASE" \
  --runtime_envs "MODEL_AGENT_API_KEY=$MODEL_AGENT_API_KEY" \
  --runtime_envs "MODEL_AGENT_PROVIDER=openai"

双引号让终端在执行命令前展开变量。仅在本地导出模型凭证不会自动把它传给云端运行时；本例通过运行时环境变量配置完成传递

部署并调用

agentkit launch 会在选定云平台与区域中构建镜像、创建或更新运行时及所需资源，可能产生费用。先确认账号权限、区域、模型配置和构建资源设置；调用智能体还会产生模型用量

在项目目录构建并部署：

agentkit launch

部署成功后，检查运行时状态，再发送一条测试消息：

agentkit status
agentkit invoke run "hello"

status 用于确认当前项目的运行时状态；收到智能体回答表示部署后的调用链路可用。如果构建或部署失败，先处理命令报告的问题，再继续调用，不应将本地文件生成成功视为云端部署成功

安装选项

二进制安装在 AGENTKIT_HOME（默认 ~/.agentkit），并在 AGENTKIT_BIN_DIR（默认 ~/.local/bin）下创建 agentkit、ak 两个兼容链接。自定义这两个目录时必须使用绝对路径，且两者不能指向同一目录。安装目录还包含 templates/、lifecycle-templates/、harness/、skills/、im-proxies/ 与 vendor/ 等运行所需资源；手动移动或解压独立发行包时，请保留这些目录与 ak 在同一安装目录。需要安装指定版本时，设置环境变量 AGENTKIT_VERSION（默认 latest）。若当前终端仍提示命令不存在，请重新打开终端或按安装脚本输出加载 shell 配置。

安装脚本会在 zsh、bash 或 fish 的启动配置中写入受管理的 agentkit 与 ak 调度入口，使独立 CLI 在 shell 重新加载后优先于 pip、pipx、venv 或 Conda 中同名的 Python 命令。若当前环境中已有同名 Python 入口，安装脚本会先保留原入口并写入可恢复的 shim，卸载脚本会在仍由安装脚本管理时恢复原入口。设置 AGENTKIT_NO_MODIFY_PATH=1 可跳过自动修改 shell 配置，脚本会打印需要手动加入的配置块。

安装脚本默认获取最新独立发行包，也可用 agentkit upgrade 更新已有安装。本文按 0.54.0 发布内容维护

开始使用

AI-Friendly

命令参考

前置条件

安装并检查版本

配置云端凭证

创建并配置项目

部署并调用

安装选项

​前置条件

​安装并检查版本

​配置云端凭证

​创建并配置项目

​部署并调用

​安装选项

前置条件

安装并检查版本

配置云端凭证

创建并配置项目

部署并调用

安装选项