文档中心

AgentKit

快速入门

自然语言驱动：使用 TRAE 开发并部署 Agent

本文介绍如何在 TRAE 中安装 AgentKit 官方 Skill，并通过自然语言配合 AgentKit CLI 完成 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	已删除的运行时和关联资源。

前提条件

条件	要求
注册账号	已完成账号注册和实名认证。
开通服务	已开通 AgentKit 服务。若未开通，请登录 AgentKit 控制台，根据系统引导开通产品。注意首次登录 AgentKit 服务控制台，平台将默认勾选使用 AgentKit 基础功能的必备依赖产品（包含函数服务、API 网关、镜像仓库等），您也可以根据实际业务需求，勾选所需的其他产品，然后单击“批量开通并授权”按钮确认“AgentKit 依赖服务开通及跨服务授权”，允许 AgentKit 服务使用已选择的产品。本实践中，需保证 AgentKit 服务具有运行时、评测集和评估器的管理权限，以便体验完整的实践流程。

步骤一：前置环境准备

1、安装 AgentKit CLI 工具

在待迁移 Agent 环境的终端，执行如下命令完成安装。

使用 curl 安装（推荐）
使用 wget 安装

使用系统自带 curl 工具下载并执行安装脚本：

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

执行以下命令，检查 CLI 工具的版本，版本号为 0.51.x。

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 命令发生路径解析冲突。

执行以下命令，查看 CLI 工具的命令。

agentkit --help

2、准备 Python 环境

用于在本地调试 Agent，请参考本步骤准备 Python 环境。

执行如下命令，确认待迁移 Agent 环境的 Python 版本不低于 3.10。

python --version

使用uv管理 python 虚拟环境和依赖。推荐您使用uv工具管理 Python 环境，将 AgentKit 相关依赖放进独立虚拟环境，避免影响您终端内运行的其他 Python 项目。

# 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。

开通火山方舟模型服务。

搜索 Doubao-Seed-2.1-pro 并完成开通后，点击模型名称进入详情页。

单击页面右上角“API接入”按钮，创建API Key并记录。

进入方舟在线推理模型列表页，查询模型接入点 ID。本文已查询预置推理接入点为例，搜索 Doubao-Seed-2.1-pro，记录模型接入点 ID。如需自定义创建模型推理点，请参考模型接入点使用流程。

4、准备火山引擎 AK/SK

获取火山引擎 AK/SK，进入API访问密钥页面，可以创建并获取 AK 和 SK 。了解更多

注意

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

5、准备本地环境

执行以下命令，配置管理员凭据。

export VOLCENGINE_ACCESS_KEY=<AK>
export VOLCENGINE_SECRET_KEY=<SK>

执行以下命令，验证AK/SK是否有效，并确认凭据归属账号。

agentkit auth admin doctor \
--account <火山账号ID> \
--region cn-beijing

回显如下，表示验证通过。

6、安装 TRAE 并打开本地项目

打开 TRAE 官网下载中心，选择与您本地环境匹配的版本下载。

完成注册和登录。

在本地环境中创建新的 Agent 项目目录并选择，或打开已有可部署的 Agent 项目。

步骤二：安装 AgentKit 官方 Skill

本步骤用于将 AgentKit 官方 Skill 安装到当前项目或本机环境中，使 TRAE 可以调用 AgentKit CLI 能力。

执行以下命令，将 AgentKit 官方 Skill 安装到当前项目的 TRAE 配置中。

说明

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

agentkit onboard --agent trae --scope project

回显如下，结果中显示 TRAE 和已安装的 Skill 路径，表示安装成功。

使用 TRAE 打开当前项目。后续自然语言指令均在该项目中执行。

步骤三：通过自然语言创建 Agent

本步骤用于通过 TRAE 生成 Agent 项目，并在真正执行前先确认计划、修改范围和命令清单。

注意

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

在 TRAE 中提交以下指令。

请在当前目录创建一个 Python AgentKit 项目，实现企业 IT 服务 Agent。
Agent 需要处理 VPN、密码重置和软件安装问题，并通过一个带类型标注和 Docstring 的 Python 工具返回固定策略。
使用 VeADK 和 AgentKit 的当前项目模板，不要写入任何密钥。
先输出实施计划、将要修改的文件和将要执行的命令，不要创建云端资源。等待我确认后再执行。

TRAE 会先梳理实施计划（如下图所示，每次执行返回内容可能不同，请以实际返回为准），并等待用户的确认。

确认实施计划前，建议重点检查以下内容：

使用 agentkit init 创建项目，而不是手工复制过期模板。

代码入口、工具函数和 agentkit.yaml 的职责边界清楚。

代码和配置中没有写入凭据。

计划包含本地验证，而不是直接进入部署。

修改范围仅限当前项目。

输入“确认”或点击 TRAE 提示的指令，TRAE 会按计划执行，并返回执行产物结果。

执行ls -al命令，查看新创建的项目目录。执行cd命令进入新创建的项目目录。

执行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 的行为包括接收用户请求、与模型对话、返回流式响应等。

步骤四：本地检查和调试 Agent

本步骤用于确认当前 Agent 项目可以在本地启动，并在部署前完成基础自检。

在 TRAE 中提交以下指令。

检查当前 Agent 项目是否可以在本地运行。
先检查依赖、环境变量示例、8000 端口和 Agent 工具定义；再给出需要执行的命令。
不要读取或输出任何凭据。发现问题时只修改与本次检查直接相关的文件。

回显如下， TRAE 会返回执行结果和建议执行的命令（每次执行返回内容可能不同，请以实际返回为准）。

根据 TRAE 给出的建议命令，在终端依次执行以下命令。

注意

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

安装依赖。

python3 -m pip install -r requirements.txt --break-system-packages

准备本地环境变量文件。

cp .env.example .env

执行vim编辑 .env，填入 MODEL_AGENT_API_KEY 和火山引擎 AK/SK 并保存。

启动和验证命令。

source .venv/bin/activate
python <Agent 应用入口文件>

回显如下。不要关闭本窗口，直接执行下一步骤后，本窗口会返回 200 状态码。

打开一个新的终端，执行以下命令。

curl http://127.0.0.1:8000/ping

若请求成功，且返回结果如下，则表示本地服务启动成功。

说明

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

git status --short​
git diff --check​
git diff​

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

步骤五：部署 Agent

在 TRAE 中提交以下指令，由 TRAE 汇总配置、资源和将执行的命令（如下图所示，每次执行返回内容可能不同，请以实际返回为准）。

检查当前项目的 AgentKit 部署配置，并准备部署到 cn-beijing 的 default 项目。
部署前列出运行时名称、地域、资源规格、环境变量引用和将执行的 CLI 命令。
部署时使用 .env 文件中的 AK/SK 识别 AgentKit 登录信息。
不要显示或写入密钥。等待我确认后再执行部署。

输入“确认”或点击 TRAE 提示的指令，TRAE 使用如下命令部署。

agentkit deploy

部署完成后， TRAE 会返回 Runtime 的名称、ID、状态、规格、版本等信息。

在本地终端执行以下命令。

agentkit runtime list
agentkit runtime show <Runtime 名称或 ID> --json

若运行时状态为 Ready，且结果中包含 Runtime ID、名称、版本和 Endpoint，则表示部署成功。

登录火山引擎 AgentKit 控制台，可以查看已部署的 Agent。

步骤六：调用和冒烟测试

本步骤用于通过自然语言和 CLI 组合验证运行时是否可用，以及关键能力是否满足预期。

使用 TRAE 测试

使用 CLI 测试

在 TRAE 中提交以下指令。

使用 AgentKit CLI 对当前运行时执行冒烟测试。​
使用 .env 文件中的 AK/SK 识别 AgentKit 登录信息。​
分别测试一个正常问题、一个工具调用问题和一个超出能力范围的问题。​
每次调用使用独立的 session ID，并汇总命令、结果和失败原因。​

回显如下，表示测试通过。

冒烟测试应验证以下内容：

Runtime 可以正常接收请求。

Agent 返回与问题相关的结果。

需要工具时能够触发正确工具。

超出能力范围的问题不会生成虚假业务信息。

失败结果保留 Request ID 或其他可检索标识。

后续操作

查看 Agent 运行状态和日志

本步骤用于在结果异常时读取状态和日志，并按证据进行归因。

使用 TRAE

使用 CLI

在 TRAE 中提交以下指令。

检查当前 Agent 的运行状态，并读取最近 100 行日志。​
按认证、运行时、模型、工具和业务逻辑五类归纳异常。​
只给出有日志证据支持的结论，不修改代码。​

回显如下，表示执行成功（每次执行返回内容可能不同，请以实际返回为准）。

对 Agent 进行评测

本步骤用于为当前 Agent 设计一套最小发布评测，并在提交实验前先检查样本和实验参数。

使用 TRAE

使用 CLI

创建并运行评测

在 TRAE 中提交以下指令。

为当前 Agent 设计一个最小发布评测。
先给出 5 条覆盖正常请求、工具调用、边界问题和拒答的样本，再给出评测集、评估器和实验的 CLI 命令。
先使用 dry-run 检查实验参数，等待我确认后再提交实验。

回显如下，表示执行成功（每次执行返回内容可能不同，请以实际返回为准）。

根据 TRAE 提示信息，输入“确认”或点击 TRAE 提示的指令，等待评测任务创建并运行完成。实验完成后，回显如下（每次执行返回内容可能不同，请以实际返回为准），应要求 TRAE 只根据逐条结果归纳失败类型，而不是仅根据总分直接修改代码。

分析结果并调优

本步骤会基于评测失败样本和运行日志定位问题，并执行最小必要修改。

在 TRAE 中提交以下指令。

分析指定评测实验的失败样本和对应运行日志。
区分提示词问题、工具定义问题、业务数据问题和运行环境问题。
给出最小修改方案、受影响文件和回归测试，不要修改无关代码。等待我确认后再执行。

输入“确认”或点击 TRAE 提示的指令， TRAE 会依次完成以下操作。

修改代码或配置。

运行本地测试。

查看代码差异。

重新部署。

说明

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

agentkit deploy​
agentkit runtime versions <Runtime 名称或 ID>​

使用相同评测集创建新的实验并对比新旧实验结果。只有回归测试和发布评测均通过后，才会进入发布步骤。

更新 Agent 配置

创建新版本并发布

代码更新通常使用 agentkit deploy。如果只需要修改运行时规格、关联资源或观测开关，可使用 agentkit runtime update。

进入本地终端。

执行以下命令，将运行时更新为 1 vCPU、2 GiB 内存，并在更新后自动发布新版本。若不使用 --auto-release，更新只会创建新版本，需要单独发布。

agentkit runtime update <Runtime 名称或 ID> \
--cpu-milli 1000 \
--memory-mb 2048 \
--apmplus \
--auto-release

说明

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

agentkit runtime versions <Runtime 名称或 ID>​
agentkit runtime release <Runtime 名称或 ID> --rev <版本号>​

回显如下，表示新版本发布成功。

执行如下命令，查看已切换为新版本。

agentkit runtime show <Runtime 名称或 ID> --json

回显如下，确认配置变更已经生效。

回滚版本

本步骤用于在当前版本出现异常时，先比较版本信息，再由用户确认后执行回滚。

在 TRAE 中提交以下指令。

当前版本出现异常。请先列出运行时版本，并比较当前版本与上一个稳定版本。
只输出回滚命令和回滚后的验证步骤，不要执行。等待我确认后再回滚。

输入“确认”或点击 TRAE 提示的指令，TRAE 依次执行以下命令（如下图所示，每次执行返回内容可能不同，请以实际返回为准）。

回显如下，表示回滚成功。

在本地终端执行以下命令查看当前版本并完成一次调用。

agentkit runtime show <Runtime 名称或 ID> --json
agentkit invoke "你好，请介绍你自己" -r <Runtime 名称或 ID>

回显如下，可以看到当前版本已切换为目标版本（本例为 v1），且调用正常，表示回滚成功。

清理资源

注意

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

在 TRAE 中提交以下指令。

准备清理当前 Agent 的云端资源。
先列出将删除的 Runtime ID、名称、地域、评测集和自建评估器，不要执行删除。
等待我逐项确认后，再执行不带 --yes 参数的删除命令。

输入“确认删除”或点击 TRAE 提示的指令后，TRAE 执行如下命令。

agentkit runtime delete <Runtime 名称或 ID>
agentkit eval dataset delete <评测集名称或 ID>
agentkit eval evaluator delete <评估器名称或 ID>

TRAE 清理完成后，在本地终端执行如下命令。

agentkit runtime list
agentkit eval dataset list
agentkit eval evaluator list

若列表中不再包含目标资源，则表示 CLI 侧清理完成。

附录

常用自然语言指令

任务	指令要求
创建 Agent	先输出计划、文件和命令，不创建云端资源。
部署 Agent	先检查配置和凭据引用，确认后执行部署。
排查问题	先读取状态和日志，只基于证据归因。
运行评测	先展示样本、评估器和 dry-run 结果。
调优 Agent	从失败样本出发，只做最小必要修改。
更新配置	说明是否会创建和发布新版本。
回滚	先确认稳定版本，再执行 release。
删除资源	先列出资源，不使用 --yes 跳过确认。

基础使用要求

对创建、更新、发布和删除操作，先展示实际 CLI 命令。

凭据只通过安全环境注入，不进入指令、代码和版本库。

每次修改后检查 git diff，避免无关重构。

部署后必须执行冒烟测试，发布前必须执行固定评测。

调优使用同一评测集对比，避免通过修改样本掩盖退化。

删除操作保留交互确认，并在执行后重新查询资源列表。

最近更新时间：2026.08.28 17:46:26

这个页面对您有帮助吗？

有用

无用