feat: add langchain migration sample

python/03-integrations/migration/langchain/README.md

@@ -0,0 +1,138 @@
+# LangChain 项目适配 AgentKit Runtime 示例
+
+本示例将演示如何将 LangChain 项目适配到 AgentKit Runtime 上。
+
+示例项目模拟一个用户已有的 LangChain 旅行规划项目。该项目的业务入口是 `agent.py:agent`，类型是 `TravelPlanningRunnable`。它接收用户的旅行问题，解析城市、天数、预算、同行人和兴趣偏好，然后调用工具生成每天的景点、美食和交通建议。
+
+示例中的工具用于模拟真实 LangChain 项目中的 tool use：
+
+- `search_travel_web`：模拟依赖外部知识检索的工具，内部调用 `veadk.tools.builtin_tools.web_search`
+- `estimate_trip_budget`：模拟本地业务计算工具，根据城市、天数和预算生成预算判断
+
+`agent.py` 是一个基于 LangChain 构建的 Agent。它使用 `Runnable` 定义可调用入口，用 `@tool` 声明工具函数，并在 `search_travel_web` 中调用 `veadk.tools.builtin_tools.web_search` 获取外部知识。相关依赖如下：
+
+```python
+from langchain_core.runnables import Runnable
+from langchain_core.tools import tool
+from veadk.tools.builtin_tools.web_search import web_search as builtin_web_search
+```
+
+- `TravelPlanningRunnable(Runnable)`：实现原生 LangChain Agent，并作为 `agent.py:agent` 暴露给迁移命令
+- `@tool`：把 `search_travel_web` 和 `estimate_trip_budget` 声明为 LangChain tools
+- `builtin_web_search`：由 `search_travel_web` 调用，用于模拟真实项目中需要外部知识检索的工具
+
+适配到 AgentKit Runtime 时，不需要改写 `agent.py` 的业务逻辑。`agentkit migrate` 会生成 `agentkit_app.py` 和 `.agentkit/` 配置；生成的 Runtime 应用通过 `LangChainAgentkitBridge(input_key="question")` 调用原始 `agent.py:agent`。
+
+## 适配后的调用链路
+
+适配前，用户可以直接调用 `agent.py:agent`。适配后，AgentKit Runtime 会通过生成的 `agentkit_app.py` 调用同一个入口：
+
+```text
+用户问题
+    ↓
+AgentKit Runtime
+    ↓
+agentkit_app.py
+    ↓
+LangChainAgentkitBridge(input_key="question")
+    ↓
+agent.py:agent  # TravelPlanningRunnable
+    ├── search_travel_web
+    │   └── veadk.tools.builtin_tools.web_search
+    └── estimate_trip_budget
+```
+
+## 目录结构
+
+```bash
+langchain/
+├── README.md
+├── agent.py               # 原生 LangChain Runnable 和 tools
+├── requirements.txt       # Python 依赖
+└── tests                  # 本地行为测试和迁移链路回归测试
+```
+
+## 本地运行
+
+安装依赖：
+
+```bash
+pip install -r requirements.txt
+```
+
+直接运行原生 Agent：
+
+```bash
+python agent.py
+```
+
+运行测试：
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+测试会直接调用 `search_travel_web`，不使用 mock 或 fixture。
+
+## 搜索配置
+
+`search_travel_web` 直接使用 `veadk.tools.builtin_tools.web_search`。本地或云端运行时，请参考其它 samples 的通用方式，先在 [AgentKit 控制台授权页面](https://console.volcengine.com/agentkit/region:agentkit+cn-beijing/auth?projectName=default) 完成依赖服务授权，并配置火山引擎 AK/SK：
+
+```bash
+VOLCENGINE_ACCESS_KEY=<Your Access Key>
+VOLCENGINE_SECRET_KEY=<Your Secret Key>
+```
+
+如果环境没有搜索权限，工具会返回搜索失败说明，Agent 仍会按示例逻辑生成可读结果。
+
+## 执行迁移
+
+在当前目录执行：
+
+```bash
+agentkit migrate . \
+  --framework langchain \
+  --entry agent.py:agent \
+  --name migration-langchain-travel \
+  --input-key question \
+  --compat langserve \
+  --verify
+```
+
+参数含义：
+
+- `--framework langchain`：按 LangChain Runnable 方式迁移
+- `--entry agent.py:agent`：指定原生 Agent 入口
+- `--input-key question`：把 Runtime 输入写入 `question` 字段
+- `--compat langserve`：生成 LangServe 兼容路由
+- `--verify`：生成后执行基础校验
+
+迁移会生成：
+
+```bash
+langchain/
+├── agentkit_app.py
+├── .agentkit/
+│   ├── agentkit.yaml
+│   ├── Dockerfile
+│   └── migration-plan.json
+└── requirements.txt
+```
+
+迁移命令不会改写 `agent.py`。生成的 Runtime 应用会通过 `LangChainAgentkitBridge(input_key="question")` 调用原始 `agent.py:agent`。
+
+## 部署到 AgentKit Runtime
+
+确认 `.agentkit/agentkit.yaml` 后执行：
+
+```bash
+agentkit deploy
+```
+
+部署后，Runtime 入口是 `agentkit_app.py`，业务逻辑仍由 `agent.py:agent` 和原有 LangChain tools 执行。
+
+## 示例问题
+
+```text
+我想带父母去北京玩3天，总预算3000元，喜欢历史文化、胡同和老北京美食，行程轻松一点。请帮我规划每天的景点、美食和交通建议。
+```

python/03-integrations/migration/langchain/README_EN.md

@@ -0,0 +1,139 @@
+# LangChain Project Adaptation to AgentKit Runtime Sample
+
+This sample shows how to adapt a LangChain project to AgentKit Runtime.
+
+The sample project represents an existing LangChain travel-planning project that a user already has. Its business entry point is `agent.py:agent`, implemented as `TravelPlanningRunnable`. It takes a user's travel request, parses the city, number of days, budget, travelers, and interests, then calls tools to generate daily attraction, food, and transportation suggestions.
+
+The tools in this sample simulate tool use in a real LangChain project:
+
+- `search_travel_web`: simulates a tool that depends on external knowledge retrieval, and internally calls `veadk.tools.builtin_tools.web_search`
+- `estimate_trip_budget`: simulates a local business calculation tool that evaluates the budget based on city, number of days, and total budget
+
+`agent.py` is a LangChain-based agent. It uses `Runnable` to define the callable entry point, `@tool` to declare tool functions, and calls `veadk.tools.builtin_tools.web_search` inside `search_travel_web` to retrieve external knowledge. The related dependencies are:
+
+```python
+from langchain_core.runnables import Runnable
+from langchain_core.tools import tool
+from veadk.tools.builtin_tools.web_search import web_search as builtin_web_search
+```
+
+- `TravelPlanningRunnable(Runnable)`: implements the native LangChain agent and exposes it as `agent.py:agent` for migration
+- `@tool`: declares `search_travel_web` and `estimate_trip_budget` as LangChain tools
+- `builtin_web_search`: called by `search_travel_web` to simulate a real project tool that needs external knowledge retrieval
+
+When adapting the project to AgentKit Runtime, you do not need to rewrite the business logic in `agent.py`. `agentkit migrate` generates `agentkit_app.py` and `.agentkit/` configuration. The generated Runtime app calls the original `agent.py:agent` through `LangChainAgentkitBridge(input_key="question")`.
+
+## Adapted Call Flow
+
+Before adaptation, users can call `agent.py:agent` directly. After adaptation, AgentKit Runtime calls the same entry point through the generated `agentkit_app.py`:
+
+```text
+User question
+    |
+AgentKit Runtime
+    |
+agentkit_app.py
+    |
+LangChainAgentkitBridge(input_key="question")
+    |
+agent.py:agent  # TravelPlanningRunnable
+    |-- search_travel_web
+    |   `-- veadk.tools.builtin_tools.web_search
+    `-- estimate_trip_budget
+```
+
+## Directory Layout
+
+```bash
+langchain/
+├── README.md
+├── README_EN.md
+├── agent.py               # Native LangChain Runnable and tools
+├── requirements.txt       # Python dependencies
+└── tests                  # Local behavior tests and migration-chain regression tests
+```
+
+## Local Run
+
+Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Run the native agent directly:
+
+```bash
+python agent.py
+```
+
+Run tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+The tests call `search_travel_web` directly. They do not use mocks or fixtures.
+
+## Search Configuration
+
+`search_travel_web` directly uses `veadk.tools.builtin_tools.web_search`. For local or cloud execution, follow the common setup used by other samples: authorize dependent services in the [AgentKit Console authorization page](https://console.volcengine.com/agentkit/region:agentkit+cn-beijing/auth?projectName=default), then configure Volcengine AK/SK:
+
+```bash
+VOLCENGINE_ACCESS_KEY=<Your Access Key>
+VOLCENGINE_SECRET_KEY=<Your Secret Key>
+```
+
+If the environment has no search permission, the tool returns a search failure message. The agent still returns a readable sample response.
+
+## Run Migration
+
+Run this command in the current directory:
+
+```bash
+agentkit migrate . \
+  --framework langchain \
+  --entry agent.py:agent \
+  --name migration-langchain-travel \
+  --input-key question \
+  --compat langserve \
+  --verify
+```
+
+Arguments:
+
+- `--framework langchain`: migrate as a LangChain Runnable
+- `--entry agent.py:agent`: specify the native agent entry
+- `--input-key question`: write Runtime input into the `question` field
+- `--compat langserve`: generate LangServe-compatible routes
+- `--verify`: run basic checks after generation
+
+Migration generates:
+
+```bash
+langchain/
+├── agentkit_app.py
+├── .agentkit/
+│   ├── agentkit.yaml
+│   ├── Dockerfile
+│   └── migration-plan.json
+└── requirements.txt
+```
+
+The migration command does not rewrite `agent.py`. The generated Runtime app calls the original `agent.py:agent` through `LangChainAgentkitBridge(input_key="question")`.
+
+## Deploy To AgentKit Runtime
+
+After reviewing `.agentkit/agentkit.yaml`, run:
+
+```bash
+agentkit deploy
+```
+
+After deployment, the Runtime entry point is `agentkit_app.py`. The business logic is still handled by `agent.py:agent` and the original LangChain tools.
+
+## Example Prompt
+
+```text
+I want to take my parents to Beijing for 3 days with a total budget of 3000 RMB. We like history and culture, hutongs, and old Beijing food. Please keep the itinerary relaxed and plan attractions, food, and transportation for each day.
+```