文档中心

AgentKit

进阶入门：存量 Agent 迁移

存量 Agent 迁移操作指南（低代码框架）

能力边界与注意事项

迁移覆盖入口、协议、部署和会话，但不承诺替代所有平台能力。因此，迁移前需明确以下边界：

A2A 能力迭代约束：当前 A2A 通信能力基于 ADK 实验性版本实现，协议可正常使用，但需持续关注上游版本迭代与兼容性变更。

AgentCore 平台能力：迁移不会替代完整 Bedrock AgentCore Runtime 平台能力。IAM 权限、workload identity、Memory 记忆、Gateway 网关、MCP 工具、登录态等平台底层能力，仍由原项目及原有部署环境全权负责。

低代码迁移验收标准：Dify、any 低代码迁移方案，以核心业务逻辑、输入输出语义、工具能力、部署特性完整对齐为验收基准；验收核心是业务能力等价替换，而非仅实现基础对话功能。

迁移与评测解耦原则：migrate 工具仅负责生成运行入口、业务配置、部署物料，不会自动触发 eval 评测；低代码迁移产物会自动配套生成测评集，是否执行评测，由用户迁移完成后自主选择、手动触发。

前提条件

条件	要求
注册账号	已完成账号注册和实名认证。
开通服务	已开通 AgentKit 服务。若未开通，请登录 AgentKit 控制台，根据系统引导开通产品。说明首次登录 AgentKit 服务控制台，平台将默认勾选使用 AgentKit 基础功能的必备依赖产品（包含函数服务、API 网关、镜像仓库等），您也可以根据实际业务需求，勾选所需的其他产品，然后单击“批量开通并授权”按钮确认“AgentKit 依赖服务开通及跨服务授权”，允许 AgentKit 服务使用已选择的产品。
demo 体验	火山引擎平台为您提供了 demo 示例供您快速体验框架迁移的完成过程，您可以访问 agentkit-samples 下载 ZIP 包到本地后（如下图所示），在本地进入agentkit-samples/tree/main/python/03-integrations/migration文件夹，按需选择不同框架的 Agent 完成体验。

迁移完成流程

流程示意图

从准备到调用共五步。高代码在「执行迁移」环节与本地一次行完成迁移和适配，低代码则在该步拆成 create 和 status 两个阶段远端交互。

最小流程示例

以 Dify 为例，执行以下一条命令完成迁移。

说明

项目模型调用较慢时，设置 AGENTKIT_MIGRATE_VERIFY_TIMEOUT_SECONDS=240 放宽超时。

# 进入迁移目录​
cd <迁移目录> ​
​
# create 会把  dify_input/ 提交到远端 Codex Sandbox 执行迁移。--output ../dify_output 以 dify_input/ 为基准解析，最终产物会写入 dify/dify_output/。​
agentkit migrate dify_input --framework dify create --name dify-migrate --output ../dify_output \​
  --codex-model <codex模型名> \​
  --codex-api-key-env CODEX_MIGRATE_MODEL_API_KEY \​
  --model-id <VeADK模型名> \​
  --model-base-url <VeADK依赖的模型base_url> \​
  --model-api-key-env MODEL_AGENT_API_KEY​
​
# 查询迁移任务状态并下载终态 dify_output 产物​
agentkit migrate dify_input --framework dify status --job-id <job_id>​
 ​
# 部署构建生成 VeADK 项目到火山引擎 AgentKit​
agentkit deploy​
​
# 调用已部署到火山引擎 AgentKit 的 Agent​
agentkit invoke <agent id/name> -m "你好，请用一句话介绍自己"​

命令参数介绍

通用参数

参数	必填等级	功能说明	使用示例
--framework	必填	指定原智能体开发框架，决定迁移适配逻辑，可选：langchain、langgraph、adk、strands、agentcore、dify、any。	--framework langgraph
--entry	必填	项目代码入口标识。默认形态传 file.py:object；LangGraph Server 形态传 langgraph.json[:graph_id]。	常规：--entry agent.py:root_agent LangGraph Server：--entry langgraph.json:graph1
-n、--name	推荐	自定义 AgentKit 应用名称，不传则默认使用项目文件夹名。	-n my-agent
-o、--output	按需	迁移产物输出目录；高代码默认项目根目录，Dify/any 低代码必须输出到源码外层目录。	-o ../agentkit-output
--input-key	按需	适配 LangGraph 自定义会话字段，源 Agent 非标准 messages 入参时指定，如 LangGraph state 用 question 而不是 messages。	--input-key question
--stream-node	LangGraph 编译图专属	指定流式输出节点，可重复传入，标准对话图谱无需配置。	--stream-node answer_node
--compat	按需（兼容旧调用方）	生成旧接口兼容路由，支持 langserve、fastapi-mount 两种模式，默认关闭。	--compat langserve
--compat-prefix	开启 compat 后按需	指定兼容路由挂载前缀；不传则使用 profile 默认值。	--compat-prefix /old-api
--legacy-app	仅 fastapi-mount 模式	指定原有 FastAPI 入口，完整挂载旧服务接口。	--compat fastapi-mount --legacy-app api.py:app
--model-id	按需（ARK 模型替换）	启用 ARK target-model replacement，仅修改运行环境配置，不会修改业务源码。	--model-id ep-xxxxxxxx
--model-base-url	搭配 model-id 推荐	ARK 模型服务地址，兼容 OpenAI 接口格式。	https://ark.cn-beijing.volces.com/api/v3
--model-api-key-env	搭配 model-id 推荐	存储模型密钥 API key 的环境变量，部署时只读，密钥不会写入代码文件。	--model-api-key-env ARK_API_KEY
--server-mode langgraph	LangGraph Server 专属	双协议并存，保留 LangGraph Server 原生 threads/runs/stream 协议，同时挂载 AgentKit 协议。	--server-mode langgraph
--allow-blocking	LangGraph Server 专属	关闭阻塞代码检测，生产环境不建议长期使用，优先优化同步阻塞逻辑。	--allow-blocking
--verify	推荐	迁移后本地自检，校验路由、流式接口/run_sse可用性，需提前准备完整 Python 依赖环境。	--verify
--dry-run	预览调试	仅输出迁移方案，不生成任何文件，用于提前校验参数是否正确。	--dry-run
-f、--force	重复迁移专用	强制覆盖已存在的 AgentKit 迁移产物，不会删除原有业务源码。	-f
--json	自动化流水线专用	输出结构化 JSON 迁移报告，适配 CI 脚本自动读取校验。	--json

低代码远端任务参数

低代码通过远端 sandbox 任务执行，除通用参数外，额外使用以下动作和参数：

参数 / 动作	何时使用	详细说明
create	启动迁移流程	将源码上传至 CodeEnv 沙箱环境，自动安装迁移能力，调用 Codex 完成工程转换
list	查看迁移任务	展示当前项目全部已创建的远端迁移任务列表
status --job-id	查询进度 + 下载产物	查询指定任务运行状态；任务成功后自动下载工程产物 artifact、配置清单 manifest、迁移报告 report、运行日志 logs；添加 --overwrite 可强制刷新本地缓存文件
--force-new	强制新建迁移任务	系统默认复用参数完全一致的运行中任务，需重新完整执行迁移时添加该参数
--codex-model	指定迁移专用大模型	仅控制 Codex 代码转换阶段使用的模型，不会改变最终 Agent 应用运行时绑定的推理模型
--codex-api-key-env	配置迁移模型密钥	填写存储 Codex 鉴权密钥的环境变量名称，示例：ARK_API_KEY，密钥不会硬编码写入文件

步骤一：前置环境准备

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

1、安装 AgentKit CLI 工具

执行如下命令完成安装。

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

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

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

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

agentkit -v

说明

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

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

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

2、准备 Python 环境（可选）

如果您需要在本地调试待迁移的 Agent，请参考本步骤准备 Python 环境。

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

python --version

使用uv管理 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 和模型接入点 URL。

注意

低代码框架迁移时，“存量 Agent 提交到远端 Codex 沙箱重建”和“构建生成 VeADK 项目”两个步骤均需要使用大模型能力，并且迁移的质量和成功率与大模型有关，建议您根据实际情况选择适合的大模型。

开通火山方舟模型服务。

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

查看模型使用说明，记录模型的接入点 URL 和模型名称。如下图所示，分别为模型接入点 URL 和模型名称。

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

4、准备火山引擎 AK/SK

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

注意

低代码框架迁移时，需要在火山引擎 AgentKit 中创建工具 Sandbox，因此，请确认您的 AK/SK 具备创建 Sandbox （即CreateSandbox）权限。

5、准备迁移环境

说明

迁移前，需要先区分两个目录：

迁移工作目录：你在本地 Terminal 中执行迁移命令的目录，例如 dify/ 或 any/。

迁移输入目录：位于迁移工作目录下的子目录，例如 dify_input/ 或 any_input/。该目录会被整体上传至 Codex Sandbox，作为迁移任务的输入。

您需首先在本地创建全新的迁移输入目录 dify_input/ 或 any_input/，将所有必要且会影响迁移判断、运行行为的项目文件，例如待迁移项目所需的源码、配置模板、依赖声明和启动说明，复制到该目录。不要复制本地运行环境、缓存、构建产物或敏感配置。不同迁移类型需要准备的内容如下：

dify_input/：Dify 应用导出目录。必须包含 workflow.yml；可按需补充 node_config.yml，用于描述模型、知识库、Memory、外部服务等节点的运行配置。不要包含迁移产物、缓存文件或明文密钥。

any_input/：存放待迁移 Python Agent 项目的源代码。应包含程序入口、项目源码、依赖声明、配置模板和启动说明，不要包含 .venv/、uv 缓存、pycache/、日志、测试缓存、构建产物。

创建环境变量文件。

进入迁移工作目录，例如 dify/ 或 any/。

创建环境变量新文件（例如 .env），并执行vim编辑新文件。

在新文件中，填写模型配置和 AgentKit 命令所需的火山引擎 AK/SK。

说明

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

# 远端 Codex 沙箱使用的模型 key
CODEX_MODEL_AGENT_NAME=<模型名称>
CODEX_MIGRATE_MODEL_API_KEY=<模型 API Key>

# 构建生成 VeADK 项目的模型配置
MODEL_AGENT_NAME=<模型名称>
MODEL_AGENT_API_BASE=<模型接入点 URL> # 本例为：https://ark.cn-beijing.volces.com/api/v3
MODEL_AGENT_API_KEY=<模型 API Key>

# 火山引擎 AK/SK
VOLCENGINE_ACCESS_KEY=<your ak>
VOLCENGINE_SECRET_KEY=<your sk>

执行以下命令，加载环境变量。

export $(grep -v '^#' .env | xargs)

步骤二：执行迁移（低代码框架）

框架示例

不同框架的迁移命令不同，各参数介绍请参见命令参数介绍。低代码（Dify / any）分 create 与 status 两步，产物输出到源码目录外侧。

Dify

无需大量改代码，上传 Dify 工作流（workflow） / 对话流（chatflow）配置文件，工具自动解析提示词（prompt）、模型、工具配置，一键生成完整 VeADK 工程、配套测试用例与迁移说明文档。

agentkit migrate dify_input --framework dify create \​
  --name dify-agent \​
  --output ../agentkit-dify-output \​
  --codex-model doubao-seed-2-1-pro-260628 \​
  --codex-api-key-env ARK_API_KEY \​
  --model-id doubao-seed-2-1-pro-260628 \​
  --model-base-url https://ark.cn-beijing.volces.com/api/v3 \​
  --model-api-key-env ARK_API_KEY​

Any

通用兜底迁移方案，适合任意有源码的 Agent 项目。Codex 自动分析现有项目代码，按照 VeADK 最佳实践重建整套工程，同步自动生成批量测评用例，降低人工改造工作量。以核心业务逻辑、输入输出语义、工具能力、部署特性完整对齐为验收基准；验收核心是业务能力等价替换，而非仅实现基础对话功能。

agentkit migrate any_input --framework any create \​
  --name any-agent \​
  --output ../agentkit-output \​
  --codex-model doubao-seed-2-1-pro-260628 \​
  --codex-api-key-env ARK_API_KEY \​
  --model-id doubao-seed-2-1-pro-260628 \​
  --model-base-url https://ark.cn-beijing.volces.com/api/v3 \​
  --model-api-key-env ARK_API_KEY​

查看迁移进度

低代码框架迁移为异步迁移，您可以通过以下步骤确认迁移进展。本文以迁移 dify 为例。

迁移命令执行成功后，请记录返回的 jobID，如下图所示。

执行以下命令，查看任务状态并下载终态 dify_output 产物。

agentkit migrate dify_input --framework dify status --job-id <job_id> # 本文以迁移 dify 为例，如迁移 any，请将命令中的 dify_input 替换为 any_input

状态字段 status 由 Running 转为 Succeeded 表示迁移成功。

注意

迁移成功率与您选择的大模型质量有关，如失败，可以查看 conver_report.md 文件定位失败原因、或直接按照以下操作重试：

先执行 rm -rf dify_output 命令删除 output 文件夹。

参见准备迁移环境。更新环境变量 .env 文件中的大模型。

重新执行迁移。

执行以下命令，可以查看本地迁移任务的历史记录。

agentkit migrate dify_input --framework dify list # 本文以迁移 dify 为例，如迁移 any，请将命令中的 dify_input 替换为 any_input

迁移生成的文件

迁移完成后，会新生成 dify_output/ 或 any _output/ 文件夹，文件夹中包含可部署到 AgentKit Runtime 的 VeADK 工程。

文件	作用
.agentkit/agentkit.yaml	核心部署配置文件，包含应用运行时 runtime 名称、云端部署规则、环境变量映射等能力。默认开启 APM 可观测能力（apmplus: true）；若原项目已有关闭配置（apmplus: false），则保留用户原有配置不强制覆盖。
convert_report.md	迁移报告，汇总了全量迁移落地记录、功能兼容验证结果、可观测运行状态、框架能力边界梳理，用于问题回溯、版本对齐与正式验收归档。
migration-plan.md	迁移计划，留存了整体迁移实施方案、潜在风险预警、前置校验要求、部署路由适配规则，用于迁移执行落地与风险前置管控。
eval/	评测用例，包括基准对话测试样本、边界异常用例，用于新旧版本效果对标、迭代回归验收。
requirements.txt	在保留项目原有全部依赖的基础上，自动追加 AgentKit SDK 及对应框架适配依赖。生产环境默认从 PyPI 拉取正式发布版本，保证线上版本稳定。

步骤三、部署与调用示例

部署存量 Agent

执行以下命令，将环境变量 .env 文件复制到 dify_output/ 或 any_output/ 文件夹。

cp .env dify_output/.env # 本文以迁移 dify 为例，如迁移 any，请将命令中的 dify_input 替换为 any_input

执行以下命令，进入 dify_output/ 或 any_output/ 文件夹。

cd dify_output/ # 本文以迁移 dify 为例，如迁移 any，请将命令中的 dify_input 替换为 any_input

执行以下命令，将构建生成 VeADK 项目部署到火山引擎 AgentKit。

agentkit release

回显如下，返回 AgentKit 智能体运行时（Runtime）名称和 ID ，表示部署成功。

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

调试已部署的 Agent

部署成功后，您可以在本地或火山引擎 AgentKit 控制台在线测试 Agent。

本地调试

在线调试

执行invoke命令，使用 AgentKit 原生调用，适用于所有迁移框架。

agentkit invoke <agent id/name> -m "你好，请用一句话介绍自己"

步骤四（可选）、观测与评测 Agent

Agent 发布并完成在线测试后，建议您继续通过 AgentKit 提供的观测和评测能力验证其运行状态与实际效果，逐步完成“是否稳定可用”到“足够好、值得上线”的优化。

观测 Agent

观测用于查看 Agent 在真实调用过程中的运行表现，帮助您发现链路异常、模型调用异常、日志报错或性能瓶颈。开启数据观测后，AgentKit 与 VeADK SDK 会基于 OpenTelemetry 自动采集各环节（例如模型调用、工具执行、记忆库检索等）的 Trace（调用链）与 Metrics（指标）的 Trace（调用链）与 Metrics（指标），并将数据投递至观测平台。

您可以在“数据观测”页面查看 Agent 的运行时监控、会话分析、Trace 分析、模型监控、日志分析。了解更多

评测 Agent

评测用于通过标准化实验衡量 Agent 在效果、性能和成本三个维度的表现，帮助您判断当前版本是否满足预期，并为后续优化迭代及上线提供依据。

评测机制通常由三部分组成：评测集、评估器和实验。其中，评测集用于提供标准化输入与参考答案；评估器可以基于 LLM 或 Code 按既定规则打分；实验则负责组合执行、聚合结果指标，并支持多实验之间的对比分析。了解更多

后续操作

Agent 上线后，您还可以在控制台中随时更新其实例规格、自定义镜像、模型、环境变量等配置。了解更多

注意

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

最近更新时间：2026.08.11 10:51:34

这个页面对您有帮助吗？

有用

无用