From a32234c940340a6f57e0c1271acea7cec9e38ab5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Czhangning=E2=80=9D?= Date: Wed, 21 Jan 2026 18:15:41 +0800 Subject: [PATCH 1/5] =?UTF-8?q?feat(mcp):=20=E6=B7=BB=E5=8A=A0MCP=E7=AE=80?= =?UTF-8?q?=E5=8D=95=E7=A4=BA=E4=BE=8B=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加MCP协议工具集成示例项目，包括： - 实现基于VeADK和AgentKit的MCP集成Agent - 提供测试客户端和SSE流式调用支持 - 完善项目配置文件和文档 - 更新项目检查脚本以支持MCP工具集类型 --- 02-use-cases/mcp_simple/README.md | 225 +++++++++++++++++++++++ 02-use-cases/mcp_simple/README_en.md | 212 +++++++++++++++++++++ 02-use-cases/mcp_simple/agent.py | 23 +++ 02-use-cases/mcp_simple/client.py | 60 ++++++ 02-use-cases/mcp_simple/project.yaml | 46 +++++ 02-use-cases/mcp_simple/pyproject.toml | 11 ++ 02-use-cases/mcp_simple/requirements.txt | 4 + workflow_utils/check_project_yaml.py | 7 +- 8 files changed, 585 insertions(+), 3 deletions(-) create mode 100644 02-use-cases/mcp_simple/README.md create mode 100644 02-use-cases/mcp_simple/README_en.md create mode 100644 02-use-cases/mcp_simple/agent.py create mode 100644 02-use-cases/mcp_simple/client.py create mode 100644 02-use-cases/mcp_simple/project.yaml create mode 100644 02-use-cases/mcp_simple/pyproject.toml create mode 100644 02-use-cases/mcp_simple/requirements.txt diff --git a/02-use-cases/mcp_simple/README.md b/02-use-cases/mcp_simple/README.md new file mode 100644 index 00000000..17c72e9c --- /dev/null +++ b/02-use-cases/mcp_simple/README.md @@ -0,0 +1,225 @@ +# MCPSimpleAgent - MCP 协议工具集成示例 + +基于火山引擎 VeADK 和 AgentKit 构建的 MCP (Model Context Protocol) 集成示例，展示如何通过 `mcp_router` 调用 MCP 工具集。 + +## 概述 + +本示例展示 Agent 如何通过内置的 `mcp_router` 工具集成和调度 MCP 工具集。Agent 被配置为一个具备深度推理能力的助手，能够根据用户意图自动路由到相应的 MCP 工具完成任务。 + +## 核心功能 + +- 集成火山 MCP Server 作为 Agent 工具 +- 用户自然语言指令，agent 调用 MCP 工具集完成任务。 +- 使用 MCPToolset 管理工具连接和调用 +- 展示生产级工具集成模式 + +## Agent 能力 + +```text +用户自然语言指令 + ↓ +AgentKit 运行时 + ↓ +TOS MCP Agent + ├── VeADK Agent (对话引擎) + ├── MCPToolset (工具管理器) + │ └── mcp_search_tool (搜索工具) + │ └── mcp_use_tool (使用工具) + │ + └── ShortTermMemory (会话记忆) +``` + +### 核心组件 + +| 组件 | 描述 | +| - | - | +| **Agent 服务** | [agent.py](https://github.com/volcengine/agentkit-samples/blob/main/python/01-tutorials/01-agentkit-runtime/mcp_simple/agent.py) - 集成 MCP 工具的 Agent 应用 | +| **测试客户端** | [client.py](https://github.com/volcengine/agentkit-samples/blob/main/python/01-tutorials/01-agentkit-runtime/mcp_simple/client.py) - SSE 流式调用客户端 | +| **项目配置** | [pyproject.toml](https://github.com/volcengine/agentkit-samples/blob/main/python/01-tutorials/01-agentkit-runtime/mcp_simple/pyproject.toml) - 依赖管理（uv 工具） | +| **短期记忆** | 本地后端存储会话上下文 | + +### 代码特点 + +**Agent 配置**（[agent.py](https://github.com/volcengine/agentkit-samples/blob/main/python/01-tutorials/01-agentkit-runtime/mcp_simple/agent.py#L10-L20)）： + +```python +root_agent = Agent( + name="mcp_agent", + instruction="你是一个具备深度推理能力的 AI 助手。当你遇到复杂逻辑、数学、编程或需要多步推理的问题时，请务必使用MCP工具辅助完成用户的问题。", + tools=[mcp_router], # 集成 MCP 路由工具 + model_extra_config={ + "extra_body": { + "thinking": {"type": "disabled"} + } + }, +) +``` + +## 目录结构说明 + +```bash +mcp_simple/ +├── agent.py # Agent 应用入口 +├── client.py # 测试客户端 +├── requirements.txt # Python 依赖列表 +├── pyproject.toml # 项目配置（uv 依赖管理） +└── README.md # 项目说明文档 +``` + +## 本地运行 + +### 前置准备 + +### 1. 开通火山方舟模型服务 + +- 访问 [火山方舟控制台](https://exp.volcengine.com/ark?mode=chat) 并开通服务。 + +### 2. 获取访问凭证 + +- 参考 [用户指南](https://www.volcengine.com/docs/6291/65568?lang=zh) 获取 AK/SK。 + +### 3. 准备 MCP 服务 + +- 参考 [火山MCP工具集](https://www.volcengine.com/docs/86681/1844858?lang=zh) 配置和启动MCP服务创建MCP工具集，并且获取URL和API Key。 + +### 依赖安装 + +#### 1. 安装 uv 包管理器 + +```bash +# macOS / Linux +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +#### 2. 初始化项目依赖 + +```bash +cd python/01-tutorials/01-agentkit-runtime/mcp_simple + +# 创建虚拟环境并安装依赖 +uv venv --python 3.12 +uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple +source .venv/bin/activate +``` + +### 环境配置 + +```bash +# 火山方舟模型名称 +export MODEL_AGENT_NAME=doubao-seed-1-8-251228 + +# 火山引擎访问凭证 +export VOLCENGINE_ACCESS_KEY= +export VOLCENGINE_SECRET_KEY= + +# 火山MCP工具集地址和访问凭证 +export TOOL_MCP_ROUTER_URL=https://*****.apigateway-cn-****.volceapi.com/mcp +export TOOL_MCP_ROUTER_API_KEY= +``` + +### 调试方法 + +#### 1. 启动 Agent 服务 + +```bash +uv run agent.py +``` + +#### 2. 运行测试客户端 + +```bash +# 运行客户端 +uv run client.py +``` + +**运行效果示例**： + +```text +[run agent] Event from server: +[create session] Response from server: {'id': 'agentkit_session', 'appName': 'mcp_agent', 'userId': 'agentkit_user', 'state': {}, 'events': [], 'lastUpdateTime': 1768465256.520708} +data: {"modelVersion":"doubao-seed-1-8-251228"... +... +``` + +#### 3. 使用 VeADK Web 调试 + +```bash +cd python/01-tutorials/01-agentkit-runtime +veadk web +# 访问 http://127.0.0.1:8000 +``` + +## AgentKit 部署 + +### 云上部署流程 + +**1. 授权与准备** +确保已在 [AgentKit 控制台](https://console.volcengine.com/agentkit/region:agentkit+cn-beijing/auth?projectName=default) 完成服务授权。 + +### 2. 部署命令 + +```bash +cd python/01-tutorials/01-agentkit-runtime/mcp_simple + +# 生成/更新配置 +agentkit config +注意: Application-level runtime environment variables 需要配置上 MODEL_AGENT_NAME, TOOL_MCP_ROUTER_URL 和 TOOL_MCP_ROUTER_API_KEY 三个环境变量 +# 启动云端服务 +agentkit launch + +# 命令行测试 +agentkit invoke '一只青蛙一次可以跳 1 级台阶，也可以跳 2 级。它要跳上一个 10 级台阶，总共有多少种跳法？如果是 n 级呢？' +``` + +**3. 使用 Client 连接云端** +修改 `client.py` 中的 `base_url` 和 `api_key` 为 `agentkit.yaml` 中生成的 `runtime_endpoint` 和 `runtime_apikey`，然后运行： + +```bash +uv run client.py +``` + +## 技术要点 + +### `mcp_router` 工具 + +`mcp_router` 是 VeADK 框架提供的通用 MCP 路由工具。它不仅仅是一个单一的工具，而是一个能够感知和分发请求到多个 MCP Server 的网关。 + +- **自动路由**：根据用户指令，自动选择合适的 MCP 工具。 +- **协议封装**：屏蔽了底层的 MCP 协议细节（如 JSON-RPC 消息格式）。 +- **统一接口**：Agent 只需与 `mcp_router` 交互，无需单独管理每个 MCP 连接。 + +### 深度推理配置 + +Agent 在配置时指定了 `instruction` 强调深度推理能力： + +```python +instruction="你是一个具备深度推理能力的 AI 助手...请务必使用MCP工具辅助完成用户的问题。" +``` + +这引导模型在面对复杂问题时，主动思考并利用外部工具（通过 MCP）来解决问题，而不是仅凭训练数据回答。 + +## 示例提示词 + +- 示例 1 +- 示例 2 + +## 效果展示 + +暂无 + +## 常见问题 + +无 + +## 参考资料 + +- [VeADK 官方文档](https://volcengine.github.io/veadk-python/) +- [AgentKit 开发指南](https://volcengine.github.io/agentkit-sdk-python/) +- [火山方舟模型服务](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new&projectName=default) +- [MCP 协议规范](https://modelcontextprotocol.io) +- [火山 MCP Marketplace](https://www.volcengine.com/mcp-marketplace) +- [TOS 对象存储文档](https://www.volcengine.com/docs/tos) + +## 代码许可 + +本工程遵循 Apache 2.0 License diff --git a/02-use-cases/mcp_simple/README_en.md b/02-use-cases/mcp_simple/README_en.md new file mode 100644 index 00000000..8c30e864 --- /dev/null +++ b/02-use-cases/mcp_simple/README_en.md @@ -0,0 +1,212 @@ +# MCPSimpleAgent - MCP Protocol Tool Integration Example + +An MCP (Model Context Protocol) integration example built on Volcengine VeADK and AgentKit, demonstrating how to call the MCP toolset via `mcp_router`. + +## Overview + +This example demonstrates how an Agent integrates and schedules the MCP toolset through the built-in `mcp_router` tool. The Agent is configured as an assistant with deep reasoning capabilities, capable of automatically routing to the corresponding MCP tools to complete tasks based on user intent. + +## Core Features + +- Integrate Volcengine MCP Server as an Agent tool +- User natural language instructions, agent calls MCP toolset to complete tasks. +- Use MCPToolset to manage tool connections and calls +- Demonstrate production-level tool integration patterns + +## Agent Capabilities + +```text +User Natural Language Instructions + ↓ +AgentKit Runtime + ↓ +TOS MCP Agent + ├── VeADK Agent (Dialogue Engine) + ├── MCPToolset (Tool Manager) + │ └── mcp_search_tool (Search Tool) + │ └── mcp_use_tool (Use Tool) + │ + └── ShortTermMemory (Session Memory) +``` + +### Core Components + +| Component | Description | +| - | - | +| **Agent Service** | [agent.py](https://github.com/volcengine/agentkit-samples/blob/main/python/01-tutorials/01-agentkit-runtime/mcp_simple/agent.py) - Agent application integrating MCP tools | +| **Test Client** | [client.py](https://github.com/volcengine/agentkit-samples/blob/main/python/01-tutorials/01-agentkit-runtime/mcp_simple/client.py) - SSE streaming client | +| **Project Configuration** | [pyproject.toml](https://github.com/volcengine/agentkit-samples/blob/main/python/01-tutorials/01-agentkit-runtime/mcp_simple/pyproject.toml) - Dependency management (uv tool) | +| **Short Term Memory** | Local backend storage for session context | + +### Code Features + +**Agent Configuration** ([agent.py](https://github.com/volcengine/agentkit-samples/blob/main/python/01-tutorials/01-agentkit-runtime/mcp_simple/agent.py#L10-L20)): + +```python +root_agent = Agent( + name="mcp_agent", + instruction="You are an AI assistant with deep reasoning capabilities. When you encounter complex logic, mathematics, programming, or problems requiring multi-step reasoning, please make sure to use MCP tools to assist in completing user questions.", + tools=[mcp_router], # Integrate MCP router tool + model_extra_config={ + "extra_body": { + "thinking": {"type": "disabled"} + } + }, +) +``` + +## Directory Structure + +```bash +mcp_simple/ +├── agent.py # Agent application entry point +├── client.py # Test client +├── requirements.txt # Python dependency list +├── pyproject.toml # Project configuration (uv dependency management) +└── README.md # Project documentation +``` + +## Run Locally + +### Prerequisites + +**1. Activate Volcengine Ark Model Service** +- Visit [Volcengine Ark Console](https://exp.volcengine.com/ark?mode=chat) and activate the service. + +**2. Get Access Credentials** +- Refer to [User Guide](https://www.volcengine.com/docs/6291/65568?lang=zh) to get AK/SK. + +**3. Prepare MCP Service** +- Refer to [Volcengine MCP Toolset](https://www.volcengine.com/docs/86681/1844858?lang=zh) to configure and start the MCP service, create the MCP toolset, and obtain the URL and API Key. + +### Install Dependencies + +#### 1. Install uv Package Manager + +```bash +# macOS / Linux +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +#### 2. Initialize Project Dependencies + +```bash +cd python/01-tutorials/01-agentkit-runtime/mcp_simple + +# Create virtual environment and install dependencies +uv venv --python 3.12 +uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple +source .venv/bin/activate +``` + +### Environment Configuration + +```bash +# Volcengine Ark Model Name +export MODEL_AGENT_NAME=doubao-seed-1-8-251228 + +# Volcengine Access Credentials +export VOLCENGINE_ACCESS_KEY= +export VOLCENGINE_SECRET_KEY= + +# Volcengine MCP Toolset Address and Access Credentials +export TOOL_MCP_ROUTER_URL=https://*****.apigateway-cn-****.volceapi.com/mcp +export TOOL_MCP_ROUTER_API_KEY= +``` + +### Debugging Methods + +#### 1. Start Agent Service + +```bash +uv run agent.py +``` + +#### 2. Run Test Client + +```bash +# Run client +uv run client.py +``` + +**Run Result Example**: + +```text +[run agent] Event from server: +[create session] Response from server: {'id': 'agentkit_session', 'appName': 'mcp_agent', 'userId': 'agentkit_user', 'state': {}, 'events': [], 'lastUpdateTime': 1768465256.520708} +data: {"modelVersion":"doubao-seed-1-8-251228"... +... +``` + +#### 3. Use VeADK Web Debugging + +```bash +cd python/01-tutorials/01-agentkit-runtime +veadk web +# Visit http://127.0.0.1:8000 +``` + +## AgentKit Deployment + +### Cloud Deployment Process + +**1. Authorization and Preparation** +Ensure that service authorization is completed in the [AgentKit Console](https://console.volcengine.com/agentkit/region:agentkit+cn-beijing/auth?projectName=default). + +**2. Deployment Commands** + +```bash +cd python/01-tutorials/01-agentkit-runtime/mcp_simple + +# Generate/Update configuration +agentkit config +Note: Application-level runtime environment variables need to configure three environment variables: MODEL_AGENT_NAME, TOOL_MCP_ROUTER_URL, and TOOL_MCP_ROUTER_API_KEY +# Launch cloud service +agentkit launch + +# Command line test +agentkit invoke 'A frog can jump 1 step or 2 steps at a time. To jump up a 10-step staircase, how many ways are there in total? What if it is n steps?' +``` + +**3. Use Client to Connect to Cloud** +Modify `base_url` and `api_key` in `client.py` to `runtime_endpoint` and `runtime_apikey` generated in `agentkit.yaml`, then run: + +```bash +uv run client.py +``` + +## Technical Highlights + +### `mcp_router` Tool + +`mcp_router` is a general MCP routing tool provided by the VeADK framework. It is not just a single tool, but a gateway capable of perceiving and distributing requests to multiple MCP Servers. + +- **Automatic Routing**: Automatically selects appropriate MCP tools based on user instructions. +- **Protocol Encapsulation**: Shields underlying MCP protocol details (such as JSON-RPC message formats). +- **Unified Interface**: The Agent only needs to interact with `mcp_router` without managing each MCP connection individually. + +### Deep Reasoning Configuration + +The Agent specifies `instruction` in the configuration to emphasize deep reasoning capabilities: + +```python +instruction="You are an AI assistant with deep reasoning capabilities... please make sure to use MCP tools to assist in completing user questions." +``` + +This guides the model to actively think and use external tools (via MCP) to solve problems when facing complex issues, rather than answering solely based on training data. + +## FAQ +None + +## References + +- [VeADK Official Documentation](https://volcengine.github.io/veadk-python/) +- [AgentKit Development Guide](https://volcengine.github.io/agentkit-sdk-python/) +- [Volcengine Ark Model Service](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new&projectName=default) +- [MCP Protocol Specification](https://modelcontextprotocol.io) +- [Volcengine MCP Marketplace](https://www.volcengine.com/mcp-marketplace) +- [TOS Object Storage Documentation](https://www.volcengine.com/docs/tos) + +## Code License + +This project follows the Apache 2.0 License diff --git a/02-use-cases/mcp_simple/agent.py b/02-use-cases/mcp_simple/agent.py new file mode 100644 index 00000000..db4a0d05 --- /dev/null +++ b/02-use-cases/mcp_simple/agent.py @@ -0,0 +1,23 @@ +import os +from agentkit.apps import AgentkitAgentServerApp +from veadk import Agent +from veadk.memory.short_term_memory import ShortTermMemory +from veadk.tools.builtin_tools.mcp_router import mcp_router + +short_term_memory = ShortTermMemory(backend="local") + +root_agent = Agent( + name="mcp_agent", + model_name=os.getenv("MODEL_AGENT_NAME", "doubao-seed-1-8-251228"), + instruction="你是一个具备深度推理能力的 AI 助手。当你遇到复杂逻辑、数学、编程或需要多步推理的问题时，请务必使用MCP工具辅助完成用户的问题。", + tools=[mcp_router], + model_extra_config={"extra_body": {"thinking": {"type": "disabled"}}}, +) + +agent_server_app = AgentkitAgentServerApp( + agent=root_agent, + short_term_memory=short_term_memory, +) + +if __name__ == "__main__": + agent_server_app.run(host="0.0.0.0", port=8000) diff --git a/02-use-cases/mcp_simple/client.py b/02-use-cases/mcp_simple/client.py new file mode 100644 index 00000000..9fdcc3b8 --- /dev/null +++ b/02-use-cases/mcp_simple/client.py @@ -0,0 +1,60 @@ +import asyncio + +import httpx +import requests +from google.adk.cli.adk_web_server import CreateSessionRequest, RunAgentRequest +from google.genai.types import Content, Part + +if __name__ == "__main__": + # Step 0: setup running configs + app_name = "mcp_agent" + user_id = "agentkit_user" + session_id = "agentkit_session" + base_url = "http://127.0.0.1:8000" + api_key = "agentkit test key" + + # Step 1: create a session + def create_session(): + create_session_request = CreateSessionRequest( + session_id=session_id, + ) + + response = requests.post( + url=f"{base_url}/apps/{app_name}/users/{user_id}/sessions/{create_session_request.session_id}", + headers={"Authorization": f"Bearer {api_key}"}, + ) + + print(f"[create session] Response from server: {response.json()}") + + return create_session_request.session_id + + # Step 2: run agent with SSE + + print("[run agent] Event from server:") + + # 3. Handle streaming events + async def send_request(message: str): + run_agent_request = RunAgentRequest( + app_name=app_name, + user_id=user_id, + session_id=create_session(), + new_message=Content(parts=[Part(text=message)], role="user"), + stream=True, + ) + + with httpx.stream( + "POST", + f"{base_url}/run_sse", + json=run_agent_request.model_dump(exclude_none=True), + timeout=120, + headers={"Authorization": f"Bearer {api_key}"}, + ) as r: + for line in r.iter_lines(): + print(line) + + async def send_request_parallel(): + await send_request( + "一只青蛙一次可以跳 1 级台阶，也可以跳 2 级。它要跳上一个 10 级台阶，总共有多少种跳法？如果是 n 级呢？" + ) + + asyncio.run(send_request_parallel()) diff --git a/02-use-cases/mcp_simple/project.yaml b/02-use-cases/mcp_simple/project.yaml new file mode 100644 index 00000000..6427042b --- /dev/null +++ b/02-use-cases/mcp_simple/project.yaml @@ -0,0 +1,46 @@ +name: Agent 与火山 MCP Server +name_en: MCP +description: 展示如何通过 mcp_router 调用 MCP 工具集。 +details: 这是一个通过内置的 mcp_router 工具集成和调度 MCP 工具集Agent。 +tags: + # 行业场景标签（金融、汽车、泛互、医疗、零售、广告营销、能源电力、信息技术服务、教育、工业、制造等） + industry: 教育 + from: volcengine + framework: veadk + language: python + tech: + - MCPToolset + - veadk + - mcp +type: tutorial +senarios: # 应用场景（2-6个），type 为 application 时必填 + - name: # 应用场景名称（2-15字） + desc: # 应用场景描述（10-20字） + - name: + desc: +prompts: # Prompt 样例 + - text: 一只青蛙一次可以跳 1 级台阶，也可以跳 2 级。它要跳上一个 10 级台阶，总共有多少种跳法？如果是 n 级呢？ + resource_url: # 必要的多模态数据 URL（公网可访问） +envs: # 所需的环境变量（用于第三方依赖服务） + - name: 火山引擎访问密钥 + key: VOLCENGINE_ACCESS_KEY + url: https://www.volcengine.com/docs/6291/65568?lang=zh + - name: 火山引擎访问密钥 + key: VOLCENGINE_SECRET_KEY + url: https://www.volcengine.com/docs/6291/65568?lang=zh + - name: 火山MCP工具集地址 + key: TOOL_MCP_ROUTER_URL + url: https://www.volcengine.com/docs/86681/1844858?lang=zh + - name: 火山MCP工具集访问凭证 + key: TOOL_MCP_ROUTER_API_KEY + url: https://www.volcengine.com/docs/86681/1844858?lang=zh +components: # Agentkit 依赖服务 + - type: mcp_toolset # 服务类型，可选项为 tool | knowledgebase | memory + # 对应产品（不区分大小写） + # knowledgebase: VikingKnowledge + # memory: VikingMem | Mem0 + product: mcp_toolset +models: # 涉及到的具体模型列表 + - doubao-seed-1-8-251228 + +image: agentkit-platform-2113735418-cn-beijing.cr.volces.com/agentkit/mcp_simple:v1.0.0 \ No newline at end of file diff --git a/02-use-cases/mcp_simple/pyproject.toml b/02-use-cases/mcp_simple/pyproject.toml new file mode 100644 index 00000000..192a1e68 --- /dev/null +++ b/02-use-cases/mcp_simple/pyproject.toml @@ -0,0 +1,11 @@ +[project] +name = "mcp-example" +version = "0.1.0" +description = "Add your description here" +readme = "README.md" +requires-python = ">=3.12" +dependencies = [ + "agentkit-sdk-python==0.1.15", + "google-adk==1.18.0", + "veadk-python==0.2.29", +] diff --git a/02-use-cases/mcp_simple/requirements.txt b/02-use-cases/mcp_simple/requirements.txt new file mode 100644 index 00000000..d08bfacd --- /dev/null +++ b/02-use-cases/mcp_simple/requirements.txt @@ -0,0 +1,4 @@ +veadk-python==0.2.29 +agentkit-sdk-python==0.1.15 +google-adk==1.18.0 +urllib3<2.0.0 \ No newline at end of file diff --git a/workflow_utils/check_project_yaml.py b/workflow_utils/check_project_yaml.py index 4ae6f0ec..940f01f9 100644 --- a/workflow_utils/check_project_yaml.py +++ b/workflow_utils/check_project_yaml.py @@ -13,6 +13,7 @@ "sandbox": ["AIO_Sandbox", "Skills_Sandbox"], "knowledgebase": ["VikingKnowledge"], "memory": ["VikingMem", "Mem0"], + "mcp_toolset": ["mcp_toolset"], } @@ -39,7 +40,7 @@ def check_description(metadata: dict[str, Any]): if not description: raise ValueError("description is required") - if len(description) < 10 or len(description) > 20: + if len(description) < 10 or len(description) > 200: raise ValueError("description should be between 10-20 characters") @@ -48,7 +49,7 @@ def check_details(metadata: dict[str, Any]): if not details: raise ValueError("details is required") - if len(details) < 10 or len(details) > 40: + if len(details) < 10 or len(details) > 400: raise ValueError("details should be between 10-40 characters") @@ -210,7 +211,7 @@ def main(argv: list[str] | None = None) -> int: check_details(data) check_tags(data) check_type(data) - check_senarios(data) + # check_senarios(data) check_prompts(data) check_models(data) check_envs(data) From d238caf1f6e15a797c4e62414b6b4faaf78d792d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Czhangning=E2=80=9D?= Date: Thu, 22 Jan 2026 14:35:13 +0800 Subject: [PATCH 2/5] remove env --- 02-use-cases/mcp_simple/project.yaml | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/02-use-cases/mcp_simple/project.yaml b/02-use-cases/mcp_simple/project.yaml index 6427042b..5ab63aea 100644 --- a/02-use-cases/mcp_simple/project.yaml +++ b/02-use-cases/mcp_simple/project.yaml @@ -21,19 +21,7 @@ senarios: # 应用场景（2-6个），type 为 application 时 prompts: # Prompt 样例 - text: 一只青蛙一次可以跳 1 级台阶，也可以跳 2 级。它要跳上一个 10 级台阶，总共有多少种跳法？如果是 n 级呢？ resource_url: # 必要的多模态数据 URL（公网可访问） -envs: # 所需的环境变量（用于第三方依赖服务） - - name: 火山引擎访问密钥 - key: VOLCENGINE_ACCESS_KEY - url: https://www.volcengine.com/docs/6291/65568?lang=zh - - name: 火山引擎访问密钥 - key: VOLCENGINE_SECRET_KEY - url: https://www.volcengine.com/docs/6291/65568?lang=zh - - name: 火山MCP工具集地址 - key: TOOL_MCP_ROUTER_URL - url: https://www.volcengine.com/docs/86681/1844858?lang=zh - - name: 火山MCP工具集访问凭证 - key: TOOL_MCP_ROUTER_API_KEY - url: https://www.volcengine.com/docs/86681/1844858?lang=zh +# envs: # 所需的环境变量（用于第三方依赖服务） components: # Agentkit 依赖服务 - type: mcp_toolset # 服务类型，可选项为 tool | knowledgebase | memory # 对应产品（不区分大小写） From 6f526dbbfd8d9c47f8def72d496fa887f261d72d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Czhangning=E2=80=9D?= Date: Wed, 28 Jan 2026 12:11:39 +0800 Subject: [PATCH 3/5] fix(workflow_utils): Expand use case check scope and adjust project yaml validation rules In check_usecases.py, add checks for the python directory, not just the 02-use-cases directory. In check_project_yaml.py, add mcp_toolset as a component option and adjust the character length limits for description and details. --- template/project.yaml | 6 +++--- workflow_utils/check_project_yaml.py | 25 +++++++++++++------------ workflow_utils/check_usecases.py | 5 ++++- 3 files changed, 20 insertions(+), 16 deletions(-) diff --git a/template/project.yaml b/template/project.yaml index f3e3e7fc..c2d64435 100644 --- a/template/project.yaml +++ b/template/project.yaml @@ -1,7 +1,7 @@ name: # 中文名称（255字符） name_en: # 英文名称（255字符） -description: # 简介（10-20字） -details: # 详细介绍（10-40字） +description: # 简介（10-60字） +details: # 详细介绍（10-400字） tags: # 行业场景标签（金融、汽车、泛互、医疗、零售、广告营销、能源电力、信息技术服务、教育、工业、制造等） industry: @@ -11,7 +11,7 @@ tags: tech: # 技术标签（可选），最多 5 个 - type: # 类型，可选项为 tutorial | application -senarios: # 应用场景（2-6个），type 为 application 时必填 +scenarios: # 应用场景（2-6个），type 为 application 时必填 - name: # 应用场景名称（2-15字） desc: # 应用场景描述（10-20字） - name: diff --git a/workflow_utils/check_project_yaml.py b/workflow_utils/check_project_yaml.py index 4ae6f0ec..02c2f66f 100644 --- a/workflow_utils/check_project_yaml.py +++ b/workflow_utils/check_project_yaml.py @@ -13,6 +13,7 @@ "sandbox": ["AIO_Sandbox", "Skills_Sandbox"], "knowledgebase": ["VikingKnowledge"], "memory": ["VikingMem", "Mem0"], + "mcp_toolset": ["MCPToolset"], } @@ -39,8 +40,8 @@ def check_description(metadata: dict[str, Any]): if not description: raise ValueError("description is required") - if len(description) < 10 or len(description) > 20: - raise ValueError("description should be between 10-20 characters") + if len(description) < 10 or len(description) > 60: + raise ValueError("description should be between 10-60 characters") def check_details(metadata: dict[str, Any]): @@ -48,8 +49,8 @@ def check_details(metadata: dict[str, Any]): if not details: raise ValueError("details is required") - if len(details) < 10 or len(details) > 40: - raise ValueError("details should be between 10-40 characters") + if len(details) < 10 or len(details) > 400: + raise ValueError("details should be between 10-400 characters") def check_tags(metadata: dict[str, Any]): @@ -76,16 +77,16 @@ def check_type(metadata: dict[str, Any]): raise ValueError(f"type should be one of {SAMPLE_TYPES}") -def check_senarios(metadata: dict[str, Any]): +def check_scenarios(metadata: dict[str, Any]): type = metadata.get("type") - senarios: list = metadata.get("senarios", []) - if not senarios and type == "application": - raise ValueError("senarios is required when type is `application`") + scenarios: list = metadata.get("scenarios", []) + if not scenarios and type == "application": + raise ValueError("scenarios is required when type is `application`") - if len(senarios) < 2 or len(senarios) > 6: - raise ValueError("senarios should have 2-6 items") + if len(scenarios) < 2 or len(scenarios) > 6: + raise ValueError("scenarios should have 2-6 items") - for scenario in senarios: + for scenario in scenarios: name = scenario.get("name") if not name: raise ValueError("scenario name is required") @@ -210,7 +211,7 @@ def main(argv: list[str] | None = None) -> int: check_details(data) check_tags(data) check_type(data) - check_senarios(data) + check_scenarios(data) check_prompts(data) check_models(data) check_envs(data) diff --git a/workflow_utils/check_usecases.py b/workflow_utils/check_usecases.py index fc49ec13..0089f560 100644 --- a/workflow_utils/check_usecases.py +++ b/workflow_utils/check_usecases.py @@ -35,7 +35,10 @@ def main() -> None: parts = Path(rel_path).parts if len(parts) >= 2 and parts[0] == "02-use-cases" and parts[1] != "beginner": candidate_dirs.add(Path(parts[0]) / parts[1]) - + if len(parts) >= 2 and parts[0] == "python" and parts[1] != "02-use-cases": + candidate_dirs.add(Path(parts[0]) / parts[1]) + if len(parts) >= 3 and parts[0] == "python" and parts[1] == "01-use-cases": + candidate_dirs.add(Path(parts[0]) / parts[2] / parts[3]) if not candidate_dirs: print( "No top-level 02-use-cases/* directories detected, skipping main.py checks." From fdd32d52753ed9be443e7c564a06ada8772cd201 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Czhangning=E2=80=9D?= Date: Thu, 29 Jan 2026 16:13:28 +0800 Subject: [PATCH 4/5] r --- 02-use-cases/mcp_simple/project.yaml | 12 ++++++------ workflow_utils/check_project_yaml.py | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/02-use-cases/mcp_simple/project.yaml b/02-use-cases/mcp_simple/project.yaml index 5ab63aea..65e77696 100644 --- a/02-use-cases/mcp_simple/project.yaml +++ b/02-use-cases/mcp_simple/project.yaml @@ -13,11 +13,11 @@ tags: - veadk - mcp type: tutorial -senarios: # 应用场景（2-6个），type 为 application 时必填 - - name: # 应用场景名称（2-15字） - desc: # 应用场景描述（10-20字） - - name: - desc: +scenarios: # 应用场景（2-6个），type 为 application 时必填 + - name: 复杂逻辑推理 + desc: 利用MCP解决数学、编程等多步推理问题 + - name: MCP工具调度 + desc: 根据自然语言指令自动路由调用MCP工具集 prompts: # Prompt 样例 - text: 一只青蛙一次可以跳 1 级台阶，也可以跳 2 级。它要跳上一个 10 级台阶，总共有多少种跳法？如果是 n 级呢？ resource_url: # 必要的多模态数据 URL（公网可访问） @@ -27,7 +27,7 @@ components: # Agentkit 依赖服务 # 对应产品（不区分大小写） # knowledgebase: VikingKnowledge # memory: VikingMem | Mem0 - product: mcp_toolset + product: MCPToolset models: # 涉及到的具体模型列表 - doubao-seed-1-8-251228 diff --git a/workflow_utils/check_project_yaml.py b/workflow_utils/check_project_yaml.py index 02c2f66f..22fb2e6a 100644 --- a/workflow_utils/check_project_yaml.py +++ b/workflow_utils/check_project_yaml.py @@ -145,7 +145,7 @@ def check_components(metadata: dict[str, Any]): assert component.get("product"), "component product is required" component_type = component["type"].lower() - component_product = component["product"].lower() + component_product = component["product"] assert component_type in COMPONENT_OPTIONS, ( f"component type should be one of {COMPONENT_OPTIONS.keys()}" From b9357d6805c52d72f20bd1da1e9973b781fec631 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Czhangning=E2=80=9D?= Date: Thu, 29 Jan 2026 16:14:34 +0800 Subject: [PATCH 5/5] r --- workflow_utils/check_project_yaml.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/workflow_utils/check_project_yaml.py b/workflow_utils/check_project_yaml.py index 22fb2e6a..4a4dc69e 100644 --- a/workflow_utils/check_project_yaml.py +++ b/workflow_utils/check_project_yaml.py @@ -10,10 +10,10 @@ SAMPLE_TYPES = ["tutorial", "application"] COMPONENT_OPTIONS = { - "sandbox": ["AIO_Sandbox", "Skills_Sandbox"], - "knowledgebase": ["VikingKnowledge"], - "memory": ["VikingMem", "Mem0"], - "mcp_toolset": ["MCPToolset"], + "sandbox": ["AIO_Sandbox".lower(), "Skills_Sandbox".lower()], + "knowledgebase": ["VikingKnowledge".lower()], + "memory": ["VikingMem".lower(), "Mem0".lower()], + "mcp_toolset": ["MCPToolset".lower()], } @@ -145,7 +145,7 @@ def check_components(metadata: dict[str, Any]): assert component.get("product"), "component product is required" component_type = component["type"].lower() - component_product = component["product"] + component_product = component["product"].lower() assert component_type in COMPONENT_OPTIONS, ( f"component type should be one of {COMPONENT_OPTIONS.keys()}"