本文介绍如何通过 AgentKit CLI，基于 CLI 预置模板或本地已有代码开发 Agent，并将其部署为 AgentKit 云端智能体运行时。 ## 背景介绍 [AgentKit CLI](https://www.volcengine.com/docs/86681/2085680?LibVersion=v26.07.24) 是面向开发者的命令行工具，用于简化 Agent 应用的全生命周期管理，覆盖初始化、配置、构建与部署等关键环节。它通过统一的命令入口与标准化流程，解决 Agent 交付过程中常见的工程化问题，例如：项目启动方式不一致、配置分散难以复用、环境切换成本高、构建部署步骤繁琐且容易出错等，让开发者可以将更多精力投入到 Agent 能力与效果本身。 AgentKit CLI 的核心优势在于： * 采用声明式配置理念，将核心配置集中在 `agentkit.yaml` 文件中管理，配置更清晰、可移植且便于版本控制。 * 支持本地开发、混合部署与纯云端部署等多种模式，适配不同阶段的研发与交付诉求。 * 预置 Agent 模板（例如 Basic Agent App、Basic Stream Agent App），帮助开发者快速生成可运行工程。 * 提供 `agentkit config`、`agentkit launch` 等高阶命令，降低 Agent 配置、发布门槛，提升交付稳定性。 ## 前提条件 |条件 |要求 | |---|---| |注册账号 |已完成 [账号注册](https://www.volcengine.com/docs/6261/64925) 和 [实名认证](https://www.volcengine.com/docs/6261/64935)。 | |开通服务 |已开通 AgentKit 服务。若未开通，请登录 [AgentKit 控制台](https://console.volcengine.com/AgentKit)，根据系统引导开通产品。

说明

首次登录 AgentKit 服务控制台，平台将默认勾选使用 AgentKit 基础功能的必备依赖产品（包含函数服务、API 网关、镜像仓库等），您也可以根据实际业务需求，勾选所需的其他产品，然后单击“批量开通并授权”按钮确认“AgentKit 依赖服务开通及跨服务授权”，允许 AgentKit 服务使用已选择的产品。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6a181e6e0aff566d7aeafd836dde4ebf.jpeg) | ||已 [开通镜像仓库服务](https://console.volcengine.com/cr)。 | ||已 [开通方舟模型服务](https://console.volcengine.com/ark/openManagement)。 | ## 步骤一：配置环境推荐您使用`uv`工具管理 Python 环境，将 AgentKit 相关依赖放进独立虚拟环境，避免影响您终端内运行的其他 Python 项目。其他安装方法，请参见 [安装 AgentKit CLI](https://www.volcengine.com/docs/86681/2150325?LibVersion=v26.07.24)。 1. 登录您需要安装 AgentKit CLI 的终端。 2. 执行如下命令，确认其 Python 版本**不低于 3.10**。 ```Bash python --version ``` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2cfd053631e425aefef3e85acf5e9c05.png) 3. 执行如下命令，下载并安装 `uv` 工具。使用 curl 工具 ```Bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` 使用 wget 工具 ```Bash wget -qO- https://astral.sh/uv/install.sh | sh ``` 4. 执行如下命令，初始化 `uv` 环境。 ```Bash cd <存放项目文件目录> uv init --no-workspace ``` 5. 执行如下命令，创建并激活 `uv` 环境。本文以创建并激活一个基于 `Python 3.12` 版本且名称为 `.AgentKit` 的虚拟环境为例。 ```Bash uv venv --python 3.12 .AgentKit source .AgentKit/bin/activate ``` 环境激活后，您可以看到您的命令行开头会有括号标注的虚拟环境名称。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_320981a65edc10de51ee013d0d304eb4.png) 6. 执行如下命令，在已激活的虚拟环境中安装 VeADK 与 AgentKit SDK。 ```Bash uv pip install -U agentkit-sdk-python uv pip install -U veadk-python ``` 7. 执行如下命令，检测是否安装成功。 ```Bash agentkit --version veadk --version ``` 若回显类似如下信息，则表示安装成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2863abf5f391cc1db1089b8739e375ea.png) 8. 创建并获取用于调用火山引擎云资源的 API 访问密钥（Access Key ID 与 Secret Access Key）。[了解更多](https://www.volcengine.com/docs/6291/65568) 10. 在虚拟环境中配置全局变量。 1. 执行如下命令，初始化全局配置。 ```Bash agentkit config --global --init ``` 2. 执行如下命令，配置用于**调用火山引擎云资源**的 API 访问密钥（Access Key ID 和 Secret Access Key）。 ```Bash agentkit config --global --set volcengine.access_key= agentkit config --global --set volcengine.secret_key= ``` 3. 执行如下命令，配置运行时部署地域。

说明

全局配置信息中，地域默认为华北2（北京）地域。若该地域不符合您的使用预期，请将beijing替换为目标地域ID。了解更多

```Bash agentkit config --global --set volcengine.region=cn-beijing ``` 4. 执行如下命令，在回显信息中确认配置是否正确。 ```Bash agentkit config --global --show ``` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a8f59d4e9d49dfd0c3cd32a3f5db1bbe.png) ## 步骤二：创建 Agent 1. 获取大模型信息。本文以火山引擎方舟大模型 Doubao\-Seed\-2.1\-pro 为例，第三方平台模型请自行获取模型名称、模型 API Key 和模型接入点 URL。 1. 登录 [火山方舟模型服务控制台](https://console.volcengine.com/ark/openManagement)。 2. 搜索 `Doubao-Seed-2.1-pro` 并完成开通后，点击模型名称进入详情页。 3. 查看模型使用说明，记录模型的接入点 URL 和模型名称。

说明

模型接入点 URL 保留到版本后即可，例如 https://ark.cn\-beijing.volces.com/api/v3。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_06ad47f879198a039384876e7a199aac.png) 4. 单击页面右上角“API接入”按钮，创建 [API Key](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D) 并记录。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_26874d4982211ca036fb107c89cbea73.png) 2. 初始化 Agent。使用 AgentKit CLI 预置模板适用于希望从零开始快速在本地开发 Agent 场景。 1. 执行如下命令，创建并进入 Agent 项目目录，本文以项目名称 `simple-agent` 为例。 ```Bash mkdir simple-agent && cd simple-agent ``` 2. 执行如下命令，开启初始化 Agent 流程。 ```Bash agentkit init ``` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_90bf9c4f54bdd6c78f59474920c73497.png) 3. 输入您希望使用的 Agent 模板序号，本文以选择`1`（Basic Agent APP）号模板为例，按`Enter`键确认。 |序号 |**模板名称** |**类型** |**语言** |**说明** | |---|---|---|---|---| |1 |Basic Agent App |基础应用 |Python |最简单的聊天机器人，零基础入门首选。 | |2 |Basic Stream Agent App |流式应用 |Python |适用于需要流式输出的交互场景，可以作为具有打字机效果的聊天机器人。 | |3 |A2A Agent App |A2A 协议应用 |Python |适用于多 Agent 协作场景，支持多 Agent 编排，例如互相协作的 AI 员工。 | |4 |Eino A2A Agent App |A2A 协议应用 |Golang |Go 语言版高性能 AI 员工，适用于生产级部署场景。 | 使用已有 Agent 代码适用于将本地开发完成的 Agent 快速包装为符合 AgentKit 要求的项目，并发布至云端场景。 1. 执行如下命令，进入存放本地 Agent 项目的目录，本文以项目目录为 `local-agent` 为例。 ```Bash cd local-agent ``` 2. 执行如下命令，开启初始化 Agent 流程。 ```Bash agentkit init --from-agent ~/my_projects/my_agent.py ```

说明

请将~/my_projects/my_agent.py 替换为您已有 Agent 的入口文件路径。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1268b4ca6ea3ae22af5381b1bbc11e99.png) 初始化完成后，CLI 将自动生成如下文件。 * **.dockerignore**：用于记录构建 Docker 时需要忽略的文件或目录路径。Docker 构建时， `COPY . . `命令会忽略记录在本文件中的文件及目录，减小镜像体积并避免敏感信息泄露。 * **agentkit.yaml** ：AgentKit 项目的配置文件，定义了项目元信息、运行时环境变量、云部署参数等。 * **requirements.txt**：用于声明 Agent 所需的 Python 包依赖。Docker 构建时，将通过 `RUN uv pip install -r requirements.txt` 将其安装到容器镜像中。 * **simple_agent.py** ：Agent 应用入口文件，定义了 Agent 的行为包括接收用户请求、与模型对话、返回流式响应等。

注意

使用本地已有 Agent 时，AgentKit CLI 将在您原有的 Agent 应用入口文件名称前添加 agentkit- 前缀，例如：本地 Agent 原入口文件名为 local_agent.py，初始化后将更名为 agentkit-local_agent.py。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_4c7c2fd451bec9a823d13a619d7edc01.png) 2. **（可选）** 执行如下命令，使用交互式配置向导设置部署参数。 ```Bash agentkit config ``` 配置向导会引导您完成以下设置，按`Enter`键表示使用默认配置： |参数 ||说明 | |---|---|---| |通用配置 |应用名称 |Agent 应用名称。 | ||入口文件 |Agent 应用入口文件。 | ||应用描述 |应用的描述信息。 | ||应用语言 |Agent 应用的开发语言，默认为 `Python`。支持：

* 1：Python

* 2：Golang | ||语言版本 |Agent 应用开发语言版本。

* Python 版本默认为 `3.12`。

* Golang 版本默认为 `1.24`。 | ||依赖文件 |记录 Agent 应用相关依赖信息的文件，默认为`requirements.txt`。 | ||环境变量 |配置智能体运行时可读取的环境变量，请以 `Key=Value` 格式进行配置。支持：

* `MODEL_AGENT_NAME=`模型名称：可选，配置为 Agent 提供推理服务的模型名称，默认为火山方舟的`doubao-seed-2-1-pro-260628`模型。

* `MODEL_ENDPOINT=`模型接入点 URL：可选，配置调用模型服务的 URL，默认为火山方舟 Endpoint `https://ark.cn-beijing.volces.com/api/v3` 。

* `MODEL_AGENT_API_KEY=`模型 API Key：必填，配置调用模型服务的 API Key。

* `DEBUG=`调试模式开关：是否开启调试模式开关，支持：

* `true`：开启。开启后 Agent 会输出更详细的调试信息，便于开发和问题排查。

* `false`：不开启。

* `LOG_LEVEL=`日志级别：控制 Agent 运行时输出的日志详细程度。支持：

* `debug`：输出所有调试信息，包括模型调用细节、工具执行过程、中间状态等，适用于开发调试、问题排查。

* `info`：默认值，输出正常运行日志，如请求开始/结束、关键状态变更，适用于日常使用、一般监控。

* `warning`：只输出警告和错误信息，适用于关注潜在风险场景。

* `error`：只输出错误日志，适用于只关注失败场景。 | ||部署模式 |Agent 应用的部署与运行模式，本文选择 `cloud` 部署模式。支持：

* `local`：默认值，在您的本地机器上完成 Agent 构建和部署，非常适合快速开发和调试场景。

* `cloud`：将代码的构建和部署完全托管在 AgentKit 上，无需本地 Docker 环境，内置可观测性，环境一致性高，安全可靠，适用于将 Agent 发布至生产环境场景。

* `hybrid`：在本地构建镜像，然后将其推送到云端 AgentKit 进行部署，兼顾本地构建的灵活性和云端运行环境的稳定性，适合需要自定义构建流程的场景。 | |云端部署配置 |Region |指定本地代码（Agent）上传至CR镜像仓库的地域，默认为`cn-beijing`。 | ||CR 镜像仓库 |CR 实例名称、命名空间和仓库名，默认自动生成。 | 配置完成后，会将以上内容写入 `agentkit.yaml` ** ** 配置文件。您也可以执行`cat agentkit.yaml`命令进入配置文件，查看 Agent 源数据信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_48b9d71da5829fd41850277e141063b8.png) ## 步骤三：部署 Agent 1. 执行以下命令，将应用构建并部署到 AgentKit 智能体运行时。 ```Bash agentkit launch ```

说明

首次部署大约需要 2～3 分钟，请耐心等待。

若构建过程中提示您确认是否启用观测服务时，建议您输入 y 并按 Enter 键确认，该操作会将应用构建并部署至 AgentKit 智能体运行时，同时启用观测服务。

当回显智能体运行时状态为 **Ready ** 时，则表示创建成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9a2dd3ce534b0b49385cc29ff41ec37f.png) 2. 登录 [AgentKit 控制台](https://console.volcengine.com/agentkit)，可以查看已部署的智能体运行时实例及其详细信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_4fc077d440e5ae8c2709c50145f2ef16.png) ## 步骤四：测试 Agent 创建成功后，您可以通过控制台“在线测试”或通过`invoke`命令验证 Agent 能否正常工作。在线调试 1. 登录 [AgentKit 控制台](https://console.volcengine.com/agentkit)。 2. 在左侧导航树中，选择“基础组件 \> 智能体运行时”。 3. 单击目标 Agent 右侧“操作”列的“在线测试”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0d0305ce8b68e448bc891305338060c8.png) 4. 在 **Body** **类型 ** 模块中，选择 **raw ** 并输入测试参数（本文调整 Prompt 为“介绍下自己，看看你有哪些 MCP 工具可用”），单击“调试”按钮发起 POST 请求。更多调试参数详情，请参见 [调用 Agent](https://www.volcengine.com/docs/86681/2122004)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_01190fbe74fc7a5f6c48c5edd30c4186.png) 5. 在 **调试结果 ** 模块，确认状态码为 **200**，并验证返回内容符合预期。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a1a500fed1918b8ac785e01d2365a1a0.png) 使用 CLI 命令调试 1. 在本地虚拟环境中执行如下命令，发送 Prompt。 ```Bash agentkit invoke "你是谁" ``` 2. 根据回显信息，确认 Agent 可以正常回复。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1aae9e211ee9c90f7c95232c4f4b0de0.png) ## 步骤五：观测与评测 Agent Agent 发布并完成在线测试后，建议您继续通过 AgentKit 提供的观测和评测能力验证其运行状态与实际效果，逐步完成“是否稳定可用”到“足够好、值得上线”的优化。 ### 观测 Agent 观测用于查看 Agent 在真实调用过程中的运行表现，帮助您发现链路异常、模型调用异常、日志报错或性能瓶颈。开启数据观测后，AgentKit 与 VeADK SDK 会基于 OpenTelemetry 自动采集各环节（例如模型调用、工具执行、记忆库检索等）的 Trace（调用链）与 Metrics（指标）的 Trace（调用链）与 Metrics（指标），并将数据投递至观测平台。您可以在“数据观测”页面查看 Agent 的运行时监控、会话分析、Trace 分析、模型监控、日志分析。[了解更多](https://www.volcengine.com/docs/86681/1873528) ### 评测 Agent 评测用于通过标准化实验衡量 Agent 在效果、性能和成本三个维度的表现，帮助您判断当前版本是否满足预期，并为后续优化迭代及上线提供依据。评测机制通常由三部分组成：评测集、评估器和实验。其中，评测集用于提供标准化输入与参考答案；评估器可以基于 LLM 或 Code 按既定规则打分；实验则负责组合执行、聚合结果指标，并支持多实验之间的对比分析。[了解更多](https://www.volcengine.com/docs/86681/1873446) ## 后续操作 Agent 上线后，您还可以在控制台中随时更新其实例规格、自定义镜像、模型、环境变量等配置。[了解更多](https://www.volcengine.com/docs/86681/2204794)

注意

更新智能体运行时配置后，需重新发布使新配置生效。了解更多

## 相关操作 AgentKit CLI 还为您提供了多种命令，方便您管理 Agent 及智能体运行时。本节仅为您展示部分核心命令用法，完整 AgentKit CLI 命令可查看 [命令详解](https://www.volcengine.com/docs/86681/2119713)。 ### 查看智能体运行时运行状态 1. 执行如下命令，进入目标 Agent 根目录。 ```Bash cd ``` 2. 执行如下命令，查看当前 Agent 对应的智能体运行时 ID、名称、状态及 `Endpoint` 等信息。 ```Bash agentkit status ``` 回显如下，表示正常运行： ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_deb9d4c10dd08adae863ac5d93207edd.png) ### 清理资源若您不再使用 Agent 发布至 AgentKit 中的智能体运行时，可通过命令清理智能体运行时实例及相关资源。

注意

删除操作仅针对本地 Agent 发布至 AgentKit 中的对应智能体运行时及相关资源，不会清理您本地的 Agent 文件。

智能体运行时实例及相关资源删除后无法恢复，请谨慎操作。

1. 执行如下命令，进入目标 Agent 根目录。 ```Bash cd ``` 2. 执行如下命令，清理智能体运行时及相关资源。 ```Bash agentkit destroy ``` 3. 输入`y`并按回车键确认删除操作。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2477f9f21c88341b38c8cdfbb273d182.png) 回显如下，表示删除成功： ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9fe7ee7c03c72a88b2ec7abef004ae26.png)