optimize a2a simple

Author: codingmokey2025

02-use-cases/beginner/a2a_simple/README.md

@@ -1,121 +1,112 @@
 # A2A Simple - Agent-to-Agent 通信协议
 
-基于火山引擎 VeADK 和 A2A (Agent-to-Agent) 协议构建的分布式智能体示例，展示如何实现智能体之间的通信和协作。
+基于火山引擎 VeADK 和 A2A (Agent-to-Agent) 协议构建的智能体示例，展示如何实现标准化的智能体服务。
 
 ## 概述
 
-本示例演示 A2A 协议的基础应用，展示如何构建可互操作的分布式智能体系统。
+本示例演示 A2A 协议的基础应用，展示如何构建符合 A2A 协议标准的智能体服务。
 
 ## 核心功能
 
 - A2A 协议：标准化的智能体间通信协议
-- 远程服务：提供工具能力的远程 Agent
-- 本地客户端：调用远程 Agent 的客户端
+- Agent 服务：提供工具能力的 A2A Agent
+- 客户端调用：通过 A2A 协议调用 Agent 服务
 - 工具能力：投掷骰子和检查质数
 - 状态管理：跨工具调用的状态持久化
 
 ## Agent 能力
 
 ```text
-方式一：直接客户端调用
+客户端调用流程
 本地客户端 (local_client.py)
     ↓
 A2A 协议 (HTTP/JSONRPC)
     ↓
-远程 Agent 服务 (remote/agent.py:8001)
+Agent 服务 (agent.py:8000)
     ├── roll_die 工具 (投掷骰子)
     │   └── 状态管理：rolls 历史
     │
     └── check_prime 工具 (检查质数)
-
-方式二：Agent 级联调用
-本地 Agent (agent.py:8000)
-    ├── add 工具 (加法)
-    └── RemoteVeAgent → 远程 Agent 服务 (remote/agent.py:8001)
-        ├── roll_die 工具 (投掷骰子)
-        └── check_prime 工具 (检查质数)
 ```
 
 ## 目录结构说明
 
 ```bash
 a2a_simple/
-├── agent.py                 # 本地 Agent 服务（端口 8000，可调用远程 Agent）
+├── agent.py                 # Agent 服务（端口 8000）
 ├── local_client.py          # A2A 客户端实现
-├── remote/                  # 远程 Agent 服务
-│   ├── agent.py            # Agent 定义和 A2A App（端口 8001）
-│   ├── agentkit.yaml       # AgentKit 部署配置
-│   ├── requirements.txt    # Python 依赖
-│   ├── Dockerfile          # Docker 镜像构建
-│   └── tools/              # 工具实现
-│       ├── roll_die.py     # 投掷骰子工具
-│       └── check_prime.py  # 质数检查工具
-├── requirements.txt         # 客户端依赖
+├── tools/                   # 工具实现
+│   ├── roll_die.py         # 投掷骰子工具
+│   └── check_prime.py      # 质数检查工具
+├── agentkit.yaml           # AgentKit 部署配置
+├── requirements.txt        # Python 依赖
 ├── pyproject.toml          # 项目配置
+├── Dockerfile              # Docker 镜像构建
 └── README.md               # 项目说明文档
 ```
 
 ### 核心组件
 
 | 组件 | 描述 |
 | - | - |
-| **远程 Agent** | [remote/agent.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/remote/agent.py#L14-L40) - hello_world_agent，提供工具服务（端口 8001） |
-| **本地 Agent** | [agent.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/agent.py#L16-L21) - a2a_sample_agent，具有 add 工具和 sub_agents（端口 8000） |
-| **本地客户端** | [local_client.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/local_client.py) - A2ASimpleClient，调用远程服务 |
-| **工具：roll_die** | [remote/tools/roll_die.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/remote/tools/roll_die.py) - 投掷骰子 |
-| **工具：check_prime** | [remote/tools/check_prime.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/remote/tools/check_prime.py) - 检查质数 |
+| **Agent 服务** | [agent.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/agent.py) - hello_world_agent，提供工具服务（端口 8000） |
+| **本地客户端** | [local_client.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/local_client.py) - A2ASimpleClient，调用 Agent 服务 |
+| **工具：roll_die** | [tools/roll_die.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/tools/roll_die.py) - 投掷骰子 |
+| **工具：check_prime** | [tools/check_prime.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/tools/check_prime.py) - 检查质数 |
 | **AgentCard** | Agent 元数据和能力描述 |
-| **项目配置** | [remote/agentkit.yaml](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/remote/agentkit.yaml) - AgentKit 部署配置 |
+| **项目配置** | [agentkit.yaml](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/agentkit.yaml) - AgentKit 部署配置 |
 
 ### 代码特点
 
-**本地 Agent 定义**（[agent.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/agent.py#L16-L21)）:
-
-```python
-agent = Agent(
-    name="a2a_sample_agent",
-    instruction="You are a helpful assistant that can add numbers and delegate tasks to a remote agent that can roll dice and check prime numbers.",
-    tools=[add],
-    sub_agents=[remote_agent],
-)
-```
-
-**远程 Agent 定义**（[remote/agent.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/remote/agent.py#L14-L40)）：
+**Agent 定义**（[agent.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/agent.py#L9-L35)）：
 
 ```python
 root_agent = Agent(
-    name='hello_world_agent',
+    name="hello_world_agent",
     description=(
-        'hello world agent that can roll a dice of 8 sides and check prime numbers.'
+        "hello world agent that can roll a dice of 8 sides and check prime numbers."
     ),
     instruction="""
       You roll dice and answer questions about the outcome of the dice rolls.
       You can roll dice of different sizes.
-      You can use multiple tools in parallel by calling functions in parallel.
-      When you are asked to roll a die, you must call the roll_die tool.
-      When checking prime numbers, call the check_prime tool with a list of integers.
+      You can use multiple tools in parallel by calling functions in parallel(in one request and in one round).
+      It is ok to discuss previous dice roles, and comment on the dice rolls.
+      When you are asked to roll a die, you must call the roll_die tool with the number of sides. Be sure to pass in an integer. Do not pass in a string.
+      You should never roll a die on your own.
+      When checking prime numbers, call the check_prime tool with a list of integers. Be sure to pass in a list of integers. You should never pass in a string.
+      You should not check prime numbers before calling the tool.
+      When you are asked to roll a die and check prime numbers, you should always make the following two function calls:
+      1. You should first call the roll_die tool to get a roll. Wait for the function response before calling the check_prime tool.
+      2. After you get the function response from roll_die tool, you should call the check_prime tool with the roll_die result.
+        2.1 If user asks you to check primes based on previous rolls, make sure you include the previous rolls in the list.
+      3. When you respond, you must include the roll_die result from step 1.
+      You should always perform the previous 3 steps when asking for a roll and checking prime numbers.
+      You should not rely on the previous history on prime results.
     """,
-    tools=[roll_die, check_prime],
+    tools=[
+        roll_die,
+        check_prime,
+    ],
 )
 ```
 
-**AgentCard 配置**（[remote/agent.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/remote/agent.py#L48-L58)）：
+**AgentCard 配置**（[agent.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/agent.py#L45-L55)）：
 
 ```python
 agent_card = AgentCard(
-  capabilities=AgentCapabilities(streaming=True),
-  description=root_agent.description,
-  name=root_agent.name,
-  defaultInputModes=["text"],
-  defaultOutputModes=["text"],
-  provider=AgentProvider(organization="agentkit", url=""),
-  skills=[AgentSkill(id="0", name="chat", description="Chat", tags=["chat"])],
-  url="http://localhost:8001",
-  version="1.0.0",
+    capabilities=AgentCapabilities(streaming=True),
+    description=root_agent.description,
+    name=root_agent.name,
+    default_input_modes=["text"],
+    default_output_modes=["text"],
+    provider=AgentProvider(organization="agentkit", url=""),
+    skills=[AgentSkill(id="0", name="chat", description="Chat", tags=["chat"])],
+    url="http://localhost:8000",
+    version="1.0.0",
 )
 ```
 
-**本地客户端调用**（[local_client.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/local_client.py#L32-L97)）：
+**本地客户端调用**（[local_client.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/local_client.py#L28-L88)）：
 
 ```python
 async def create_task(self, agent_url: str, message: str) -> str:
@@ -134,17 +125,17 @@ async def create_task(self, agent_url: str, message: str) -> str:
         responses.append(response)
 ```
 
-**工具状态管理**（[remote/tools/roll_die.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/remote/tools/roll_die.py#L4-L18)）：
+**工具状态管理**（[tools/roll_die.py](https://github.com/volcengine/agentkit-samples/blob/main/02-use-cases/beginner/a2a_simple/tools/roll_die.py#L6-L21)）：
 
 ```python
 def roll_die(sides: int, tool_context: ToolContext) -> int:
     result = random.randint(1, sides)
 
     # 状态持久化
-    if not 'rolls' in tool_context.state:
-        tool_context.state['rolls'] = []
+    if "rolls" not in tool_context.state:
+        tool_context.state["rolls"] = []
 
-    tool_context.state['rolls'] = tool_context.state['rolls'] + [result]
+    tool_context.state["rolls"] = tool_context.state["rolls"] + [result]
     return result
 ```
 
@@ -186,11 +177,11 @@ cd 02-use-cases/beginner/a2a_simple
 # 如果没有 `uv` 虚拟环境，可以使用命令先创建一个虚拟环境
 uv venv --python 3.12
 
-# 使用 `pyproject.toml` 管理依赖
-uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple
-
 # 激活虚拟环境
 source .venv/bin/activate
+
+# 使用 `pyproject.toml` 管理依赖
+uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple
 ```
 
 ### 环境准备
@@ -215,19 +206,19 @@ veadk web
 # 在浏览器访问：http://127.0.0.1:8000
 ```
 
-Web 界面提供图形化对话测试环境，支持实时查看远程调用过程。
+Web 界面提供图形化对话测试环境，支持实时查看调用过程。
 
 #### 方式二：命令行测试（推荐学习）
 
-**步骤 1：启动远程 Agent 服务：**
+**步骤 1：启动 Agent 服务：**
 
 ```bash
 # 在终端窗口 1 中运行
 cd 02-use-cases/beginner/a2a_simple
-uv run uvicorn remote.agent:a2a_app --host localhost --port 8001
+uv run agent.py
 
 # 服务启动后，可访问 Agent Card
-# http://localhost:8001/.well-known/agent-card.json
+# http://localhost:8000/.well-known/agent-card.json
 ```
 
 **步骤 2：运行本地客户端：**
@@ -238,22 +229,6 @@ cd 02-use-cases/beginner/a2a_simple
 python local_client.py
 ```
 
-**步骤 3（可选）：启动本地 Agent 服务：**
-
-```bash
-# 在终端窗口 3 中运行（需要先启动远程 Agent）
-cd 02-use-cases/beginner/a2a_simple
-python agent.py
-
-# 服务启动后，可访问 Agent Card
-# http://localhost:8000/.well-known/agent-card.json
-```
-
-此时您有两个 Agent 服务：
-
-- **远程 Agent**（端口 8001）：提供 roll_die 和 check_prime 工具
-- **本地 Agent**（端口 8000）：提供 add 工具，并可调用远程 Agent
-
 ## AgentKit 部署
 
 ### 前置准备
@@ -272,7 +247,7 @@ python agent.py
 ### Agentkit 云上部署
 
 ```bash
-cd 02-use-cases/beginner/a2a_simple/remote
+cd 02-use-cases/beginner/a2a_simple
 
 # 配置部署参数（重要：agent_type 必须为 a2a）
 agentkit config
@@ -377,10 +352,7 @@ Agent Card 提供以下信息：
 访问方式：
 
 ```bash
-# 远程 Agent Card
-http://localhost:8001/.well-known/agent-card.json
-
-# 本地 Agent Card（如果启动了 agent.py）
+# Agent Card
 http://localhost:8000/.well-known/agent-card.json
 ```
 
@@ -393,55 +365,23 @@ http://localhost:8000/.well-known/agent-card.json
 - 示例：记录投掷历史
 
 ```python
-tool_context.state['rolls'] = tool_context.state['rolls'] + [result]
+tool_context.state["rolls"] = tool_context.state["rolls"] + [result]
 ```
 
-### 远程调用流程
+### 调用流程
 
-**方式一：直接客户端调用（local_client.py）：**
+**客户端调用流程（local_client.py）：**
 
-1. **获取 Agent Card**：了解远程 Agent 的能力
+1. **获取 Agent Card**：了解 Agent 的能力
 2. **创建客户端**：基于 Agent Card 创建 A2A 客户端
 3. **发送消息**：通过 A2A 协议发送请求
-4. **接收响应**：处理远程 Agent 的响应
-
-**方式二：Agent 级联调用（agent.py）：**
-
-1. **定义 RemoteVeAgent**：配置远程 Agent 的 URL
-2. **注册为 sub_agents**：将远程 Agent 注册到本地 Agent
-3. **自动路由**：本地 Agent 自动将任务委派给合适的 Agent
-4. **统一接口**：对外提供统一的 A2A 接口
-
-### Agent 级联（Sub-Agents）
-
-通过 `sub_agents` 参数，可以构建 Agent 级联架构：
-
-```python
-from veadk.a2a.remote_ve_agent import RemoteVeAgent
-
-remote_agent = RemoteVeAgent(
-    name="a2a_agent",
-    url="http://localhost:8001/",
-)
-
-agent = Agent(
-    name="a2a_sample_agent",
-    tools=[add],
-    sub_agents=[remote_agent],  # 级联远程 Agent
-)
-```
-
-**优势：**
-
-- 本地 Agent 可以同时使用本地工具和远程 Agent 的工具
-- 自动处理工具路由和调用
-- 支持多个远程 Agent 级联
-- 对外暴露统一的 A2A 接口
+4. **接收响应**：处理 Agent 的响应
 
 ### AgentKit A2A App
 
 ```python
 from agentkit.apps import AgentkitA2aApp
+from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
 
 a2a_app = AgentkitA2aApp()
 
@@ -459,7 +399,6 @@ a2a_app.run(agent_card=agent_card, host="0.0.0.0", port=8000)
 1. **[Multi Agents](https://github.com/volcengine/agentkit-samples/tree/main/02-use-cases/beginner/multi_agents/README.md)** - 构建多智能体协作系统
 2. **[Restaurant Ordering](https://github.com/volcengine/agentkit-samples/tree/main/02-use-cases/beginner/restaurant_ordering/README.md)** - 高级 Agent 特性
 3. **[Travel Concierge](https://github.com/volcengine/agentkit-samples/tree/main/02-use-cases/beginner/travel_concierge/README.md)** - 使用 Web 搜索工具
-4. **分布式系统**：部署多个 A2A Agent 构建分布式智能体网络
 
 ## 常见问题