文档中心

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 放宽超时。

命令参数介绍

通用参数

参数	必填等级	功能说明	使用示例
--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 工程、配套测试用例与迁移说明文档。

Any

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

查看迁移进度

低代码框架迁移为异步迁移，您可以通过以下步骤确认迁移进展。本文以迁移 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 原生调用，适用于所有迁移框架。

步骤四（可选）、观测与评测 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

这个页面对您有帮助吗？

有用

无用