本文介绍如何在 [TRAE](https://www.trae.cn/?utm_source=trae_homepage&utm_medium=international_site) 中安装 AgentKit 官方 Skill，并通过自然语言配合 [AgentKit CLI](https://www.volcengine.com/docs/86681/2085680?LibVersion=v26.07.24) 完成 Agent 的创建、调试、部署、调用、观测、评测、更新、回滚和清理。

说明

TRAE 是字节自研 AI 原生编程 IDE，融合多品类大模型，与 AI 深度集成，提供智能问答、代码自动补全以及基于 Agent 的 AI 自动编程能力。使用 TRAE 开发项目时，你可以与 AI 灵活协作，适配全阶段开发者提效使用。

AgentKit CLI 是 AgentKit 产品面向开发者的命令行工具，用于简化 Agent 应用的全生命周期管理，覆盖初始化、配置、构建与部署等关键环节。

## Agent 生命周期与 CLI 命令下表用于说明 Agent 常见生命周期阶段、对应 CLI 命令和预期产物，便于用户在执行本实践前确认操作边界。 |**阶段** |**主要命令** |**产物** | |---|---|---| |初始化 |`agentkit init` |Agent 项目和基础配置。 | |配置 |`agentkit config` |Agent 项目根目录中的 `agentkit.yaml` 文件。 | |构建与部署 |`agentkit deploy` |镜像、运行时 ID、运行时版本和 Endpoint。 | |调用 |`agentkit invoke` |Agent 响应和调用结果。 | |观测 |`agentkit runtime show`、`agentkit runtime logs`、`agentkit runtime attach` |运行时状态、日志和运行时终端。 | |评测 |`agentkit eval` |评测集、评估器、实验和评分。 | |更新 |`agentkit deploy`、`agentkit runtime update` |新的运行时版本。 | |发布与回滚 |`agentkit runtime release` |当前运行时生效版本。 | |清理 |`agentkit destroy`、`agentkit runtime delete` |已删除的运行时和关联资源。 | ## 前提条件 |条件 |要求 | |---|---| |注册账号 |已完成 [账号注册](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 服务使用已选择的产品。

本实践中，需保证 AgentKit 服务具有运行时、评测集和评估器的管理权限，以便体验完整的实践流程。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6a181e6e0aff566d7aeafd836dde4ebf.jpeg) | ## 步骤一：前置环境准备 ### 1、安装 AgentKit CLI 工具 1. 在待迁移 Agent 环境的终端，执行如下命令完成安装。使用 curl 安装（推荐）使用系统自带 curl 工具下载并执行安装脚本： ```Bash curl https://agentkit-cli.tos-cn-beijing.volces.com/install.sh | sh ``` 使用 wget 安装使用 wget 工具下载并执行安装脚本： ```Bash wget -qO- https://agentkit-cli.tos-cn-beijing.volces.com/install.sh | sh ``` 2. 执行以下命令，检查 CLI 工具的版本，版本号为 0.51.x。 ```Bash agentkit -v # 若返回版本号 0.51.x，则表示安装成功 agentkit upgrade --check # 若检测到新版本，可以执行 agentkit upgrade 命令完成升级 ```

说明

您的环境中可能同时存在两套 AgentKit CLI：

TypeScript AgentKit CLI：注册 agentkit 命令和 ak 命令，版本号为 0.51.x。

Python AgentKit CLI：随 agentkit\-python\-sdk 安装，注册 agentkit 命令，版本号为 0.8.x。

当前 agentkit migrate 仅由 TypeScript AgentKit CLI 提供。由于 TypeScript CLI 和 Python SDK 都会注册 agentkit 命令，如果您的 python 安装过agentkit\-python\-sdk 包、或者启用 Python 虚拟环境后，agentkit 有可能优先解析到 Python SDK 提供的 CLI，从而无法使用 migrate 子命令。

建议您在遇到 agentkit migrate 命令无法执行的报错时，输入agentkit -v，检查一下当前 agentkit 命令注册的是什么版本。如果输出显示当前使用的是 Python AgentKit SDK CLI，建议改用 TypeScript CLI 提供的等价命令 ak（即ak migrate），ak 与 TypeScript CLI 的 agentkit 命令等价，可避免与 Python SDK 注册的同名 agentkit 命令发生路径解析冲突。

3. 执行以下命令，查看 CLI 工具的命令。 ```Bash agentkit --help ``` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6d67efb5e87fa2d1e4d3200eccdbfdf6.png) ### 2、准备 Python 环境用于在本地调试 Agent，请参考本步骤准备 Python 环境。 1. 执行如下命令，确认待迁移 Agent 环境的 Python 版本**不低于 3.10**。 ```Bash python --version ``` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2cfd053631e425aefef3e85acf5e9c05.png) 2. 使用`uv`管理 python 虚拟环境和依赖。推荐您使用`uv`工具管理 Python 环境，将 AgentKit 相关依赖放进独立虚拟环境，避免影响您终端内运行的其他 Python 项目。 ```Bash # install uv curl -LsSf https://astral.sh/uv/install.sh | sh # Initialize uv environment uv init --no-workspace # Specify Python version for the environment uv venv --python 3.12 # Activate the virtual environment source .venv/bin/activate ``` ### 3、准备大模型信息本文以火山引擎方舟大模型 Doubao\-Seed\-2.1\-pro 为例，第三方平台模型请自行获取模型 API Key 和模型接入点 ID。 1. [开通火山方舟模型服务](https://console.volcengine.com/ark/openManagement)。 2. 搜索 Doubao\-Seed\-2.1\-pro 并完成开通后，点击模型名称进入详情页。 3. 单击页面右上角“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) 4. 进入[方舟在线推理模型列表页](https://console.volcengine.com/ark/region:cn-beijing/endpoint)，查询模型接入点 ID。本文已查询预置推理接入点为例，搜索 Doubao\-Seed\-2.1\-pro，记录模型接入点 ID。如需自定义创建模型推理点，请参考[模型接入点使用流程](https://docs.volcengine.com/docs/82379/2121998?lang=zh&open_in_browser=true&redirect=1#c71acab7)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_bc9654d9c2277ea6c0cbf5ccb842d0b1.png) ### 4、准备火山引擎 AK/SK [获取火山引擎 AK/SK](https://www.volcengine.com/docs/6291/65568)，进入[API访问密钥](https://console.volcengine.com/iam/keymanage/)页面，可以创建并获取 **AK ** 和 **SK ** 。[了解更多](https://www.volcengine.com/docs/6291/65568)

注意

请确认已创建的 AK/SK 具备函数服务、API 网关、镜像仓库、AgentKit 运行时、AgentKit 评测集和评估器的管理权限，以便体验完整的实践流程。

### 5、准备本地环境 1. 执行以下命令，配置管理员凭据。 ```Bash export VOLCENGINE_ACCESS_KEY= export VOLCENGINE_SECRET_KEY= ``` 2. 执行以下命令，验证AK/SK是否有效，并确认凭据归属账号。 ```Bash agentkit auth admin doctor \ --account <火山账号ID> \ --region cn-beijing ``` 回显如下，表示验证通过。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d86a1f26b9ce90a5b4cb4310a687cdc7.png) ### 6、安装 TRAE 并打开本地项目 2. 打开 [TRAE 官网下载中心](https://www.trae.cn/download) ，选择与您本地环境匹配的版本下载。 3. 完成注册和登录。 4. 在本地环境中创建新的 Agent 项目目录并选择，或打开已有可部署的 Agent 项目。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_3058eebad8b0626dfd71e84fa5a32f1c.png) ## 步骤二：安装 AgentKit 官方 Skill 本步骤用于将 AgentKit 官方 Skill 安装到当前项目或本机环境中，使 TRAE 可以调用 AgentKit CLI 能力。 1. 在本地终端进入 Agent 项目目录。 ```Bash cd ``` 2. 执行以下命令，将 AgentKit 官方 Skill 安装到当前项目的 TRAE 配置中。

说明

project表示为项目级安装，适合团队协作，相关配置可以随项目一起管理。若需要在本机所有项目中使用，可将 project 替换为 global。

```Bash agentkit onboard --agent trae --scope project ``` 3. 回显如下，结果中显示 TRAE 和已安装的 Skill 路径，表示安装成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1a641b501b26e3e039eaa54927cb4099.png) 4. 使用 TRAE 打开当前项目。后续自然语言指令均在该项目中执行。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c3aa566d2c3684adb112cf60c017962f.png) ## 步骤三：通过自然语言创建 Agent 本步骤用于通过 TRAE 生成 Agent 项目，并在真正执行前先确认计划、修改范围和命令清单。

注意

在以下所有操作中，不要在自然语言指令中输入 Access Key、Secret Key、模型 API Key、飞书应用密钥或其他敏感信息。需要凭据时，应在终端或组织认可的凭据管理系统中配置。

1. 在 TRAE 中提交以下指令。 ```Plain Text 请在当前目录创建一个 Python AgentKit 项目，实现企业 IT 服务 Agent。 Agent 需要处理 VPN、密码重置和软件安装问题，并通过一个带类型标注和 Docstring 的 Python 工具返回固定策略。使用 VeADK 和 AgentKit 的当前项目模板，不要写入任何密钥。先输出实施计划、将要修改的文件和将要执行的命令，不要创建云端资源。等待我确认后再执行。 ``` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f81a2114fb6247a09cc4cc746f2b2e01.png) 2. TRAE 会先梳理实施计划（如下图所示，每次执行返回内容可能不同，请以实际返回为准），并等待用户的确认。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_3bac56ec25cc571ae0bf7a9b1866c848.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2a07dfb5ef35075d667f3d564b8f0c2a.png) 确认实施计划前，建议重点检查以下内容： * 使用 `agentkit init` 创建项目，而不是手工复制过期模板。 * 代码入口、工具函数和 `agentkit.yaml` 的职责边界清楚。 * 代码和配置中没有写入凭据。 * 计划包含本地验证，而不是直接进入部署。 * 修改范围仅限当前项目。 3. 输入“确认”或点击 TRAE 提示的指令，TRAE 会按计划执行，并返回执行产物结果。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b6280ed31609f2860180bf8faf2fef7e.png) 4. 执行`ls -al`命令，查看新创建的项目目录。执行`cd`命令进入新创建的项目目录。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c5a744fc6896518cc897e05a20abd74e.png) 5. 执行`ls -al`命令，检查项目包含以下由 `agentkit init` 生成的文件，表示 Agent 创建成功。 * **.dockerignore**：用于记录构建 Docker 时需要忽略的文件或目录路径。Docker 构建时， `COPY . . `命令会忽略记录在本文件中的文件及目录，减小镜像体积并避免敏感信息泄露。 * **agentkit.yaml** ：AgentKit 项目的配置文件，定义了项目元信息、运行时环境变量、云部署参数等。 * **requirements.txt**：用于声明 Agent 所需的 Python 包依赖。Docker 构建时，将通过 `RUN uv pip install -r requirements.txt` 将其安装到容器镜像中。 * **<项目名称\>.py** ：Agent 应用入口文件，即为 `agentkit.yaml` 文件中的 `common.entry_point`，定义了 Agent 的行为包括接收用户请求、与模型对话、返回流式响应等。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c3d1cae4daae39035a9ede50e176f046.png) ## 步骤四：本地检查和调试 Agent 本步骤用于确认当前 Agent 项目可以在本地启动，并在部署前完成基础自检。 1. 在 TRAE 中提交以下指令。 ```Plain Text 检查当前 Agent 项目是否可以在本地运行。先检查依赖、环境变量示例、8000 端口和 Agent 工具定义；再给出需要执行的命令。不要读取或输出任何凭据。发现问题时只修改与本次检查直接相关的文件。 ``` 回显如下， TRAE 会返回执行结果和建议执行的命令（每次执行返回内容可能不同，请以实际返回为准）。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e8983e78c5cfbd319893cbaf3eddd204.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0e30dacd21e2f630496f787d41ebb860.png) 2. 根据 TRAE 给出的建议命令，在终端依次执行以下命令。

注意

每次执行的建议命令不同，具体命令请以上一步骤中 TRAE 建议为准，此处仅作参考。

1. 安装依赖。 ```Bash python3 -m pip install -r requirements.txt --break-system-packages ``` 2. 准备本地环境变量文件。 ```Bash cp .env.example .env ``` 3. 执行`vim`编辑 `.env`，填入 MODEL_AGENT_API_KEY 和火山引擎 AK/SK 并保存。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e378a1c492bfbd255a309b0346e3bcde.png) 4. 启动和验证命令。 ```Bash source .venv/bin/activate python ``` 回显如下。不要关闭本窗口，直接执行下一步骤后，本窗口会返回 200 状态码。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d63240ccbcebee66c1491d9fabf10892.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_8e72a3a68666362e30bf528eba956eb0.png) 3. 打开一个新的终端，执行以下命令。 ```Bash curl http://127.0.0.1:8000/ping ``` 若请求成功，且返回结果如下，则表示本地服务启动成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_57a11806d82b809e0803409d2365bbed.png)

说明

如果当前项目使用 Git，提交代码前建议查看实际变更。

```Bash git status --short git diff --check git diff ```

确认代码中不存在凭据、无关文件和不必要的重构后，再进入部署阶段。

## 步骤五：部署 Agent 1. 在 TRAE 中提交以下指令，由 TRAE 汇总配置、资源和将执行的命令（如下图所示，每次执行返回内容可能不同，请以实际返回为准）。 ```Plain Text 检查当前项目的 AgentKit 部署配置，并准备部署到 cn-beijing 的 default 项目。部署前列出运行时名称、地域、资源规格、环境变量引用和将执行的 CLI 命令。部署时使用 .env 文件中的 AK/SK 识别 AgentKit 登录信息。不要显示或写入密钥。等待我确认后再执行部署。 ``` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2dd8735fb3279efe9ee9382f91181aa2.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_32ce3a38afebe625a216d37b56435fe6.png) 2. 输入“确认”或点击 TRAE 提示的指令，TRAE 使用如下命令部署。 ```Bash agentkit deploy ``` 3. 部署完成后， TRAE 会返回 Runtime 的名称、ID、状态、规格、版本等信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_fe2057690a7339e83e5e633747e73eb6.png) 4. 在本地终端执行以下命令。 ```Bash agentkit runtime list agentkit runtime show --json ``` 若运行时状态为 Ready，且结果中包含 Runtime ID、名称、版本和 Endpoint，则表示部署成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6a9b43633a8c4b0130f17734ce30c6b5.png) 5. 登录[火山引擎 AgentKit 控制台](https://console.volcengine.com/agentkit)，可以查看已部署的 Agent。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_030eb8b6e7800e786dc91c53ddd9ba13.png) ## 步骤六：调用和冒烟测试本步骤用于通过自然语言和 CLI 组合验证运行时是否可用，以及关键能力是否满足预期。使用 TRAE 测试在 TRAE 中提交以下指令。 ```Plain Text 使用 AgentKit CLI 对当前运行时执行冒烟测试。使用 .env 文件中的 AK/SK 识别 AgentKit 登录信息。分别测试一个正常问题、一个工具调用问题和一个超出能力范围的问题。每次调用使用独立的 session ID，并汇总命令、结果和失败原因。 ``` 回显如下，表示测试通过。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_de60b4d53a0883c9aeb94d2a0444909b.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_29b5f2e0702c23d82e23ccf2633c5263.png) 使用 CLI 测试 CLI 命令示例如下。 ```Bash agentkit invoke -r "你好，请用一句话介绍自己" ``` 回显如下，表示测试通过。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_199a6efc2e1a7855a68155a2ef8b58fa.png) 冒烟测试应验证以下内容： * Runtime 可以正常接收请求。 * Agent 返回与问题相关的结果。 * 需要工具时能够触发正确工具。 * 超出能力范围的问题不会生成虚假业务信息。 * 失败结果保留 Request ID 或其他可检索标识。 ## 后续操作 ### 查看 Agent 运行状态和日志本步骤用于在结果异常时读取状态和日志，并按证据进行归因。使用 TRAE 在 TRAE 中提交以下指令。 ```Bash 检查当前 Agent 的运行状态，并读取最近 100 行日志。按认证、运行时、模型、工具和业务逻辑五类归纳异常。只给出有日志证据支持的结论，不修改代码。 ``` 回显如下，表示执行成功（每次执行返回内容可能不同，请以实际返回为准）。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d7ad37ac9db6bffc7345921df6db953c.png) 使用 CLI CLI 示例命令如下。 ```Bash agentkit runtime logs --limit 100 ``` 回显如下。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_68b3e5376d0ac589d6a01dc891fa92af.png) 如果需要进入 Runtime 实例进一步检查时，可执行以下命令进入 Runtime 终端： ```Bash agentkit runtime attach ``` 回显如下，可按需进一步检查。按 `Ctrl-]` 可以退出运行时终端。

说明

不要在 Runtime 终端中直接修改生产文件。如需修复应回到项目代码，经测试后重新部署。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6b8a9b3c82d104e909aa5ac536d36a92.png) ### 对 Agent 进行评测本步骤用于为当前 Agent 设计一套最小发布评测，并在提交实验前先检查样本和实验参数。使用 TRAE 1. 创建并运行评测 1. 在 TRAE 中提交以下指令。 ```Plain Text 为当前 Agent 设计一个最小发布评测。先给出 5 条覆盖正常请求、工具调用、边界问题和拒答的样本，再给出评测集、评估器和实验的 CLI 命令。先使用 dry-run 检查实验参数，等待我确认后再提交实验。 ``` 回显如下，表示执行成功（每次执行返回内容可能不同，请以实际返回为准）。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6c746f09b3364573ddc4c2fe680e5975.png) 2. 根据 TRAE 提示信息，输入“确认”或点击 TRAE 提示的指令，等待评测任务创建并运行完成。实验完成后，回显如下（每次执行返回内容可能不同，请以实际返回为准），应要求 TRAE 只根据逐条结果归纳失败类型，而不是仅根据总分直接修改代码。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_94feb29f63e79fcf512cc17ff9f71a30.png) 2. 分析结果并调优本步骤会基于评测失败样本和运行日志定位问题，并执行最小必要修改。 1. 在 TRAE 中提交以下指令。 ```Plain Text 分析指定评测实验的失败样本和对应运行日志。区分提示词问题、工具定义问题、业务数据问题和运行环境问题。给出最小修改方案、受影响文件和回归测试，不要修改无关代码。等待我确认后再执行。 ``` 2. 输入“确认”或点击 TRAE 提示的指令， TRAE 会依次完成以下操作。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9495ce60f24f8da0ae2db589e5dfac5c.png) 1. 修改代码或配置。 2. 运行本地测试。 3. 查看代码差异。 4. 重新部署。

说明

重新部署时将使用以下命令。

```Bash agentkit deploy agentkit runtime versions ```

5. 使用相同评测集创建新的实验并对比新旧实验结果。只有回归测试和发布评测均通过后，才会进入发布步骤。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_7f9c303aef6ebd71db385b43ce7ff2ff.png) 使用 CLI 1. 创建评测集并添加样本。 ```Bash agentkit eval dataset create \ --name <评测集名称> \ --schema input,reference_output,output \ --json agentkit eval dataset add <评测集名称> \ --field input="<测试输入>" \ --field reference_output="<参考结果>" \ --json ``` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_8ea8d2f163250f7e815fa46acc93ec2c.png) 2. 查看模板，记录模版 ID。 ```Bash agentkit eval evaluator templates --json ``` 回显如下，返回模版 ID 等信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a40e2bc64344bff53257ec2794e21154.png) 3. 创建评估器。 ```Bash agentkit eval evaluator create \ --name <评估器名称> \ --from-template <模板 ID> \ --model <方舟模型 Endpoint ID> \ --json ``` 回显如下，返回评估器名称和 ID。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d6607816929b8925619f6eb3c2f7e41c.png) 4. 预览并提交评测实验。 ```Bash agentkit eval run \ --dataset <评测集名称> \ --evaluator <评估器名称> \ --target \ --name <实验名称> \ --dry-run agentkit eval run \ --dataset <评测集名称> \ --evaluator <评估器名称> \ --target \ --name <实验名称> \ --json ``` 回显如下，返回实验名称和 ID。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1352c6db48593aace2e4a76ac79acc99.png) 5. 查看评测状态和结果。 ```Bash agentkit eval experiment get <实验 ID> --json agentkit eval experiment results <实验 ID> --json ``` 回显如下，表示执行成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a833b60a8fc97aa45c9004262895a513.png) ### 更新 Agent 配置 #### 创建新版本并发布代码更新通常使用 `agentkit deploy`。如果只需要修改运行时规格、关联资源或观测开关，可使用 `agentkit runtime update`。 1. 进入本地终端。 2. 执行以下命令，将运行时更新为 1 vCPU、2 GiB 内存，并在更新后自动发布新版本。若不使用 `--auto-release`，更新只会创建新版本，需要单独发布。 ```Bash agentkit runtime update \ --cpu-milli 1000 \ --memory-mb 2048 \ --apmplus \ --auto-release ```

说明

若不使用 --auto-release，创建新版本后需执行以下命令，查看并发布新版本。

```Bash agentkit runtime versions agentkit runtime release --rev <版本号> ```

3. 回显如下，表示新版本发布成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1b1c4ebac22088f5102cdd855b92a023.png) 4. 执行如下命令，查看已切换为新版本。 ```Bash agentkit runtime show --json ``` 回显如下，确认配置变更已经生效。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b2fbc3a152218c60d8ea0dc3aca3057f.png) #### 回滚版本本步骤用于在当前版本出现异常时，先比较版本信息，再由用户确认后执行回滚。 1. 在 TRAE 中提交以下指令。 ```Plain Text 当前版本出现异常。请先列出运行时版本，并比较当前版本与上一个稳定版本。只输出回滚命令和回滚后的验证步骤，不要执行。等待我确认后再回滚。 ``` 2. 输入“确认”或点击 TRAE 提示的指令，TRAE 依次执行以下命令（如下图所示，每次执行返回内容可能不同，请以实际返回为准）。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_854fab020d5ec8b9f1c4964c5c0e2bf5.png) 回显如下，表示回滚成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e2c7c4be69132fe23be4e37a5cbd4537.png) 3. 在本地终端执行以下命令查看当前版本并完成一次调用。 ```Bash agentkit runtime show --json agentkit invoke "你好，请介绍你自己" -r ``` 回显如下，可以看到当前版本已切换为目标版本（本例为 v1），且调用正常，表示回滚成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b003ebd19e9ef0fc1fec854db7d6a0fa.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6d007b47bd7aec37d7e263cb8eea6a27.png) ### 清理资源

注意

删除 Runtime 属于不可恢复操作。不要在自然语言指令中允许自动跳过确认。

1. 在 TRAE 中提交以下指令。 ```Plain Text 准备清理当前 Agent 的云端资源。先列出将删除的 Runtime ID、名称、地域、评测集和自建评估器，不要执行删除。等待我逐项确认后，再执行不带 --yes 参数的删除命令。 ``` 2. 输入“确认删除”或点击 TRAE 提示的指令后，TRAE 执行如下命令。 ```Bash agentkit runtime delete agentkit eval dataset delete <评测集名称或 ID> agentkit eval evaluator delete <评估器名称或 ID> ``` 3. TRAE 清理完成后，在本地终端执行如下命令。 ```Bash agentkit runtime list agentkit eval dataset list agentkit eval evaluator list ``` 若列表中不再包含目标资源，则表示 CLI 侧清理完成。 ## 附录 ### 常用自然语言指令 |**任务** |**指令要求** | |---|---| |创建 Agent |先输出计划、文件和命令，不创建云端资源。 | |部署 Agent |先检查配置和凭据引用，确认后执行部署。 | |排查问题 |先读取状态和日志，只基于证据归因。 | |运行评测 |先展示样本、评估器和 dry\-run 结果。 | |调优 Agent |从失败样本出发，只做最小必要修改。 | |更新配置 |说明是否会创建和发布新版本。 | |回滚 |先确认稳定版本，再执行 release。 | |删除资源 |先列出资源，不使用 \-\-yes 跳过确认。 | ### 基础使用要求 * 对创建、更新、发布和删除操作，先展示实际 CLI 命令。 * 凭据只通过安全环境注入，不进入指令、代码和版本库。 * 每次修改后检查 git diff，避免无关重构。 * 部署后必须执行冒烟测试，发布前必须执行固定评测。 * 调优使用同一评测集对比，避免通过修改样本掩盖退化。 * 删除操作保留交互确认，并在执行后重新查询资源列表。