文档中心

AgentKit

进阶入门：存量 Agent 迁移

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

能力边界与注意事项

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

旧调用接口兼容约束： LangChain 等框架迁移后，原有旧 HTTP 调用端无法实现零改造兼容，仅通过主动开启 --compat（langserve / fastapi-mount）参数，才可适配原有调用链路。

HITL 交互与数据持久化约束： LangGraph compiled graph 不会自动生成完整的 HITL resume 人工恢复协议，复杂的会话持久化、状态恢复逻辑，需由用户自行配置实现。

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

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

迁移与评测解耦原则：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 两个阶段远端交互。

最小流程示例

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

说明

首次迁移需填加 --verify，用于导入生成物并本地请求 /run_sse。

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

# 进入待迁移 Agent 的本地目录​
cd <待迁移 Agent 的本地目录> ​
​
# 迁移存量 Agent​
agentkit migrate . \​
  --framework langchain \​
  --entry agent.py:agent \​
  --name my-agent \​
  --model-id <模型名称> \​
  --model-base-url <模型接入点> \​
  --model-api-key-env <模型 API Key> \​
  --verify​
​
# 部署存量 Agent 到火山引擎 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

步骤一：前置环境准备

1、安装 AgentKit CLI 工具

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

使用 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 虚拟环境和依赖。推荐您使用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、安装项目依赖

准备项目依赖。

原项目所有业务依赖需规范声明在requirements.txt，并且保证可正常批量安装。迁移工具会自动追加 AgentKit SDK 及对应框架适配依赖，保留原有项目依赖，无删除、无覆盖，保障业务能力不变。

requirements.txt 中需要提供以下两部分的 python 依赖：

待迁移 Agent 的原始 python 依赖：用户已有的 Agent 项目的 python 依赖，用于保证原始 Agent 运行。

AgentKit Agent 适配层依赖：AgentKit Runtime适配层的 python 依赖。需固定为：

a2a-sdk>=0.3.7,<0.4
agentkit-sdk-python>=0.7.12
google-adk>=1.32

以一个简单的 Strands 迁移为例，requirements.txt中需要如下两部分：

# Part 1: native Strands agent dependencies
strands-agents[openai]
python-dotenv>=1.0.0

# Part 2: AgentKit migration runtime dependencies
a2a-sdk>=0.3.7,<0.4
agentkit-sdk-python>=0.7.12
google-adk>=1.32

执行以下命令安装依赖。

通过 uv 安装（推荐）
通过 pip 安装

进入待迁移的 Agent 目录后执行：

uv pip install -r requirements.txt

4、准备大模型信息

本文以火山引擎方舟大模型 Doubao-Seed-2.1-pro 为例，第三方平台模型请自行获取模型名称、模型 API Key 和模型接入点 URL。

开通火山方舟模型服务。

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

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

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

5、准备火山引擎 AK/SK

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

6、准备迁移环境

执行cp命令复制环境变量（例如 .env）文件，并执行vim编辑新文件。

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

说明

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

火山引擎 AK/SK 用于后续部署到 AgentKit 平台时需要，您可以选择在此时配置，也可以后续部署存量 Agent 前再次执行本步骤。

# 模型配置
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)

7、本地调试（可选）

执行以下命令，可以在本地环境中调试和验证待迁移的 Agent。

python agent.py # 请将 agent.py 更换为您待迁移的本地 Agent 文件名称​

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

不同框架的迁移命令不同，各参数介绍请参见命令参数介绍。高代码框架的差异集中在 --framework 和 --entry，其余参数结构一致。

框架示例

LangChain

兼容 Runnable、LCEL 编排、Agent 执行器全能力；原有 LangServe 接口无需改造，启动时加 --compat langserve 即可兼容旧调用端。

agentkit migrate . \​
  --framework langchain \​
  --entry langchain_agent_migrate/agent.py:agent \​
  --name langchain-agent \​
  --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 \​
  --verify​

LangGraph compiled graph

适合已经写好 Graph 流程图的项目。默认直接兼容标准对话消息结构（messages state）；自定义 state 字段用 --input-key，指定流式节点用 --stream-node。

agentkit migrate . \​
  --framework langgraph \​
  --entry graph.py:graph \​
  --name langgraph-agent \​
  --stream-node chatbot \​
  --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 \​
  --verify​

LangGraph Server

官方 LangGraph 线上服务项目，启动需追加 --server-mode langgraph。迁移后服务同时支持原生 LangGraph 接口（/threads、/runs/stream）、AgentKit 标准双协议，原有业务调用不受影响。

agentkit migrate . \​
  --framework langgraph \​
  --server-mode langgraph \​
  --entry langgraph.json:agent \​
  --name langgraph-server-agent \​
  --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 \​
  --verify​

ADK

原生 ADK 智能体无缝迁移，无需中间转换层。完整保留原有工具（ADK tools）、回调函数（callbacks）、子智能体调度逻辑（sub-agent），最终部署为标准 AgentKit 线上服务。

agentkit migrate . \​
  --framework adk \​
  --entry agent.py:root_agent \​
  --name adk-agent \​
  --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 \​
  --verify​

Strands

推荐使用零参数 factory 工厂函数作为程序入口 entry。迁移后每个对话会话 session 独立创建智能体实例 Strands agent，避免多用户对话之间状态错乱、数据互相干扰。

agentkit migrate . \​
  --framework strands \​
  --entry agent.py:build_agent \​
  --name strands-agent \​
  --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 \​
  --verify​

Bedrock AgentCore

项目已使用 Bedrock 官方服务框架（BedrockAgentCoreApp）时选用。迁移后同时提供 AgentKit 标准接口，保留原健康检测（/ping）、调用（/invocations）接口，不会替换原有 Bedrock AgentCore Runtime 完整平台能力。它不是完整 Bedrock AgentCore Runtime 平台替代；IAM、workload identity、Memory、Gateway、MCP、登录态等外部能力仍由原项目和部署环境负责。

agentkit migrate . \​
  --framework agentcore \​
  --entry deploy/agentcore/app.py:app \​
  --name agentcore-agent \​
  --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 \​
  --verify​

迁移生成的文件

文件	作用
agentkit_app.py	AgentKit 统一启动入口文件。自动加载项目原有入口并生成承载应用：常规框架默认使用 AgentkitAgentServerApp，LangGraph Server 模式自动适配 AgentkitLangGraphServerApp。服务启动优先读取当前运行虚拟环境的依赖包（site-packages），避免平台注入路径遮蔽项目本地依赖，保证依赖加载稳定可控。
.agentkit/agentkit.yaml	核心部署配置文件，包含应用运行时 runtime 名称、云端部署规则、环境变量映射等能力。默认开启 APM 可观测能力（apmplus: true）；若原项目已有关闭配置（apmplus: false），则保留用户原有配置不强制覆盖。
.agentkit/Dockerfile	云端镜像构建文件。标准工程通过 requirements 或 PyPI 安装全量依赖；uv 工程会在虚拟环境内重装 AgentKit SDK 并执行导入校验，提前拦截依赖缺失、版本冲突等解析异常，提升部署成功率。
.agentkit/migration-plan.json	迁移全量记录文件，留存完整迁移方案、风险警告、本地校验结果、兼容路由配置、可观测能力状态与框架能力边界信息，用于问题追溯、版本对齐与验收归档。
requirements.txt	在保留项目原有全部依赖的基础上，自动追加 AgentKit SDK 及对应框架适配依赖。生产环境默认从 PyPI 拉取正式发布版本，保证线上版本稳定。

步骤三、部署与调用示例

迁移产物生成完成后，部署时会自动读取 .agentkit/agentkit.yaml 中的环境变量映射并完成云上部署；业务调用统一通过 AgentKit 原生 invoke 协议执行。所有迁移框架默认支持标准流式接口 /run_sse。

说明

部署流程默认从环境变量读取云端 AK/SK 凭证完成鉴权，请确认您已在环境变量文件中配置 AK/SK 并完成加载。

部署存量 Agent

执行以下命令，将存量 Agent 部署到火山引擎 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

这个页面对您有帮助吗？

有用

无用