文档中心

AgentKit

A2A 中心

快速接入 A2A 中心

本实践以 AgentKit CLI 和 A2A 空间结合为例，面向第一次接触 AgentKit A2A 中心的新手用户，带您从 0 开始体验“创建 A2A 空间 -> 创建并部署 A2A 协议 Agent -> 注册 Agent 至 A2A 空间 -> 验证 Agent 发现与调用”的完整操作流程，方便您了解 A2A 中心的基本使用方式和操作路径。

调用机制

本实践采用“统一入口 + A2A 空间分发 + 业务 Agent 执行”的协作方式。您将业务 Agent 注册到 A2A 空间后，调用方发起的请求会由 A2A 空间完成业务 Agent 的匹配与分发，并由对应的业务 Agent 返回处理结果，从而实现多 Agent 协作。

创建 A2A 空间

该空间用于管理已注册的业务 Agent，并在调用过程中根据 Agent Card 信息完成目标 Agent 的发现、匹配和请求转发，是调用链路中的核心分发模块。

创建并部署 A2A Agent

使用 AgentKit CLI 预置模板创建用于测试的 Agent，并分别将其部署为智能体运行时。其中：

a2a-dispatcher：是整个调用链路的统一入口，不负责具体业务处理，主要用于接收调用方请求、发起 A2A 调用，以及承接最终返回结果。

it-support-agent：业务 Agent，负责处理 VPN 配置、账号权限、软件安装等 IT 支持类问题。

policy-support-agent：业务 Agent，负责处理差旅、请假、考勤、报销等公司政策类问题。

注册业务 Agent

将 it-support-agent 和 policy-support-agent 对应的智能体运行时注册到 A2A 空间中，使其能够被 A2A 空间发现和调用。

发起调用并验证结果

调用方向 a2a-dispatcher 发送问题，例如 IT 支持类问题或公司政策类问题。

a2a-dispatcher 接收请求后，将请求作为 A2A 调用任务发送到 A2A 空间。

A2A 空间根据其中注册 Agent 的 Agent Card 信息，识别与请求最匹配的业务 Agent，并确定目标调用对象。

匹配成功后，请求被转发到目标业务 Agent，例如 IT 支持类问题由 it-support-agent 处理，公司政策类问题由 policy-support-agent 处理。

业务 Agent 完成处理后，将结果返回给 a2a-dispatcher，再由 a2a-dispatcher 返回给调用方。

前提条件

条件	要求
注册账号	已完成账号注册和实名认证。
开通服务	已开通 AgentKit 服务。若未开通，请登录 AgentKit 控制台，根据系统引导开通产品。说明首次登录 AgentKit 服务控制台，平台将默认勾选使用 AgentKit 基础功能的必备依赖产品（包含函数服务、API 网关、镜像仓库等），您也可以根据实际业务需求，勾选所需的其他产品，然后单击“批量开通并授权”按钮确认“AgentKit 依赖服务开通及跨服务授权”，允许 AgentKit 服务使用已选择的产品。
		已开通镜像仓库服务。
		已开通方舟模型服务。
本地环境	已安装、配置 AgentKit CLI。了解更多

操作步骤

步骤一：创建 A2A 空间

在左侧导航树中选择“基础组件 > A2A 中心”。

在顶部导航栏选择目标地域和项目，本实践以华北2（北京）地域与 Default 项目为例。

在下拉框中单击“新建空间”按钮。

配置 A2A 空间参数。

说明

本实践仅配置必要参数，未提及的参数保持默认。全量参数介绍请参见创建智能体空间。

参数	说明	图示
空间名称	自定义 A2A 空间的名称，创建后不支持修改。
智能体语义检索	开启后，调用方可基于自然语言调用意图，在当前空间内检索匹配度较高的 Agent，并返回 Agent Card。本实践开启该功能。

单击“确定”按钮，完成创建。

创建完成后，将自动切换至该 A2A 空间，请在浏览器地址栏中获取其空间 ID。

步骤二：创建 A2A 智能体运行时

使用 AgentKit CLI 预置的 A2A 模板创建三个支持 A2A 协议的 Agent，并将它们分别部署到 AgentKit 智能体运行时。

注意

本实践仅说明主要流程及相关参数详情，安装、配置 AgentKit CLI 详细操作步骤可参考使用 AgentKit CLI 开发并部署 Agent。

配置环境变量。

创建并获取用于调用火山引擎云资源的 API 访问密钥（Access Key ID 与 Secret Access Key）。了解更多

在您本地终端中执行如下命令，设置环境变量。

注意

由于 AK/SK 属于高敏感凭据，直接写入.env等静态配置文件存在泄露风险，在本地开发环境中配置火山引擎 AK/SK 时，推荐通过终端会话级环境变量导出的方式管理。

export VOLCENGINE_ACCESS_KEY=<your_access_key>
export VOLCENGINE_SECRET_KEY=<your_secret_key>

创建 Agent 并部署为智能体运行时。

注意

为便于验证 Agent 是否被正确调用，本实践中的业务 Agent 使用固定示例数据。正式使用前，请将示例实现替换为实际的企业知识库、工单系统或内部 API。

本实践创建的所有 Agent 项目均存放在同一个父目录下，各 Agent 项目之间相互独立、处于同一目录层级，便于统一管理和分别执行部署操作。

a2a-dispatcher

it-support-agent

policy-support-agent

该 Agent 作为统一调用入口，调用方仅需与其进行对话，该 Agent 即可根据调用方请求自动识别任务类型并通过 A2A 空间 ID 访问指定空间，检索匹配的 Agent Card，并将任务委派给对应的业务 Agent。

执行如下命令，使用 AgentKit CLI 预置模板创建基于 A2A 协议的 Agent 项目。

agentkit init a2a-dispatcher \
--template a2a \
--directory a2a-dispatcher

参数说明

参数	说明
[project_name]	Agent 项目名称，本实践以 a2a-dispatcher 为例。
--template	指定用于初始化 Agent 的 CLI 预置模板 ID、Key 或名称。本实践以 a2a 模板为例。
--directory	指定用于存放 Agent 项目的目录路径，若不存在 AgentKit CLI 会自动创建该目录。本实践以 a2a-dispatcher 目录为例。

说明

请将 a2a-dispatcher 替换为实际 Agent 项目根目录路径。

cd a2a-dispatcher

执行如下命令，配置部署地域及 A2A 空间信息。

agentkit config \
--region <your_registry_region> \
--project_name default \
-e REGISTRY_SPACE_ID=<your_registry_space_id> \
-e REGISTRY_ENDPOINT=https://agentkit.<your_registry_region>.volcengineapi.com/

参数说明

参数	说明
--region	部署的智能体运行时所属地域，请将 <your_registry_region> 替换为您创建的 A2A 空间所在地域 ID，本实践以 cn-beijing 地域为例。支持：华北 2（北京）：cn-beijing 华东 2（上海）：cn-shanghai 注意请确保智能体运行时所属地域及项目，与目标 A2A 空间保持一致。
--project_name	部署的智能体运行时所属项目，本实践以 default 项目为例。注意请确保智能体运行时所属项目与目标 A2A 空间保持一致。项目是一组资源的集合，您可以将本次创建的智能体运行时添加至项目中并按项目维度统一管理，有利于保持资源独立，维护数据安全。了解更多
-e	部署的智能体运行时环境变量。 REGISTRY_SPACE_ID：目标 A2A 空间 ID，请将 <your_registry_space_id> 替换为您创建后获取的 A2A 空间 ID。 REGISTRY_ENDPOINT：请求服务地址，请将 <your_registry_region> 替换为您创建的 A2A 空间所在地域 ID，本实践以 cn-beijing 地域为例。

执行如下命令，修改 Agent 依赖文件配置。

printf 'veadk-python[extensions]==1.1.8\n' > requirements.txt

按需修改 Agent 应用入口文件，调整 Agent 的行为。

在项目根目录中，执行如下命令，打开 Agent 代码文件。

vim a2a-dispatcher.py

按 i 键进入编辑模式，使用如下内容替换模板默认的 Agent 信息。

import logging

from veadk import Agent, Runner
from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
from agentkit.apps import AgentkitA2aApp
from veadk.tools.builtin_tools.a2a_registry import build_a2a_registry_tools

logger = logging.getLogger(__name__)
a2a_app = AgentkitA2aApp()

system_instruction = (
"You are the company's front-desk routing agent. You do NOT answer domain "
"questions yourself. For every user request, follow these steps exactly:\n"
"1. Call a2a_registry_search_agent_cards with a SHORT English task summary "
"(keywords, not the full message).\n"
"2. Inspect the returned agents' name, description and skills, and choose the "
"single best-matching agent.\n"
"3. Call a2a_registry_task_create with the chosen agent_name and the user's "
"FULL original request.\n"
"4. If it returns a task.id without a final response, call "
"a2a_registry_task_poll with the same agent_name and task_id until the task is "
"completed.\n"
"5. Return the remote specialist's answer verbatim, in the user's language.\n"
"If no returned agent can handle the request, tell the user no specialist "
"agent is available instead of guessing."
)

root_agent = Agent(
name="a2a_dispatcher",
description=(
"Front-desk routing agent that discovers and delegates user requests to "
"the best specialist A2A agent in the shared A2A space."
),
instruction=system_instruction,
tools=build_a2a_registry_tools(),
)
runner = Runner(agent=root_agent)

@a2a_app.agent_executor(runner=runner)
class DispatcherExecutor(A2aAgentExecutor):
pass

@a2a_app.ping
def ping() -> str:
return "pong!"

if __name__ == "__main__":
from a2a.types import AgentCard, AgentProvider, AgentSkill, AgentCapabilities

agent_card = AgentCard(
capabilities=AgentCapabilities(streaming=True),
description=root_agent.description,
name=root_agent.name,
default_input_modes=["text"],
default_output_modes=["text"],
provider=AgentProvider(organization="veadk", url=""),
skills=[
AgentSkill(
id="0",
name="route_to_specialist",
description=(
"Accept any company question and route it to the matching "
"specialist agent (IT support or company HR policy)."
),
tags=["router", "dispatcher", "a2a"],
)
],
url="http://0.0.0.0:8000",
version="1.0.0",
)

a2a_app.run(agent_card=agent_card, host="0.0.0.0", port=8000)

按 esc 键退出编辑模式，输入 :wq 按回车键，保存并退出文件。

在项目根目录中执行如下命令，将应用构建并部署到 AgentKit 智能体运行时。

agentkit launch

说明

首次部署耗时较长，请耐心等待。

当回显智能体运行时状态为 Ready 时，则表示创建成功，您可以在此获取智能体运行时名称、ID 及本次部署使用的相关云资源信息。

该 Agent 作为处理 VPN 配置、密码重置和软件安装等 IT 支持问题的业务 Agent，无需对外暴露调用入口。

执行如下命令，使用 AgentKit CLI 预置模板创建基于 A2A 协议的 Agent 项目。

agentkit init it-support-agent \
--template a2a \
--directory it-support-agent

参数说明

参数	说明
[project_name]	Agent 项目名称，本实践以 it-support-agent 为例。
--template	指定用于初始化 Agent 的 CLI 预置模板 ID、Key 或名称。本实践以 a2a 模板为例。
--directory	指定用于存放 Agent 项目的目录路径，若不存在 AgentKit CLI 会自动创建该目录。本实践以 it-support-agent 目录为例。

说明

请将 it-support-agent 替换为实际 Agent 项目根目录路径。

cd it-support-agent

执行如下命令，配置 Agent 部署地域。

agentkit config \
--project_name default \
--region <your_registry_region>

参数说明

参数	说明
--project_name	部署的智能体运行时所属项目，本实践以 default 项目为例。注意请确保智能体运行时所属项目与目标 A2A 空间保持一致。项目是一组资源的集合，您可以将本次创建的智能体运行时添加至项目中并按项目维度统一管理，有利于保持资源独立，维护数据安全。了解更多
--region	部署的智能体运行时所属地域，请将 <your_registry_region> 替换为您创建的 A2A 空间所在地域 ID，本实践 cn-beijing 地域为例。支持：华北 2（北京）：cn-beijing 华东 2（上海）：cn-shanghai 注意请确保智能体运行时所属地域与目标 A2A 空间保持一致。

按需修改 Agent 应用入口文件，调整 Agent 的行为。

在项目根目录中，执行如下命令，打开 Agent 代码文件。

vim it-support-agent.py

按 i 键进入编辑模式，使用如下内容替换模板默认的 Agent 信息。

import logging

from veadk import Agent, Runner
from veadk.a2a.agent_card import get_agent_card
from veadk.prompts.agent_default_prompt import DEFAULT_DESCRIPTION, DEFAULT_INSTRUCTION
from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
from agentkit.apps import AgentkitA2aApp

logger = logging.getLogger(__name__)

a2a_app = AgentkitA2aApp()

def query_it_policy(topic: str) -> dict[str, str]:
"""Query the internal IT service policy for a topic."""
policies = {
"vpn": "Open the company VPN client, sign in with SSO, and complete MFA verification.",
"password": "Open the account portal and select Reset password. Complete identity verification before setting a new password.",
"software": "Submit a software installation request in the IT service portal and wait for approval.",
}
normalized_topic = topic.lower().strip()

if "vpn" in normalized_topic:
key = "vpn"
elif any(keyword in normalized_topic for keyword in ("password", "passwd", "reset", "account", "credential")):
key = "password"
elif any(keyword in normalized_topic for keyword in ("software", "install", "installation", "app", "application", "program")):
key = "software"
else:
return {
"result": "No matching policy was found. Contact the IT service desk for assistance."
}

return {"result": policies[key]}

agent_name = "it_support_agent"
description = "An enterprise IT service assistant."
system_prompt = (
"You are an enterprise IT service assistant. "
"Use query_it_policy when the user asks about VPN, passwords, or software installation. "
"Do not invent policies that are not returned by the tool."
)

tools = [query_it_policy]

agent = Agent(
name=agent_name,
description=description,
instruction=system_prompt,
tools=tools,
)
runner = Runner(agent=agent)

@a2a_app.agent_executor(runner=runner)
class MyAgentExecutor(A2aAgentExecutor):
pass

@a2a_app.ping
def ping() -> str:
return "pong!"

if __name__ == "__main__":
from a2a.types import AgentCard, AgentProvider, AgentSkill, AgentCapabilities

agent_card = AgentCard(
capabilities=AgentCapabilities(streaming=True),
description=agent.description,
name=agent.name,
default_input_modes=["text"],
default_output_modes=["text"],
provider=AgentProvider(organization="veadk", url=""),
skills=[AgentSkill(id="0", name="chat", description="Chat", tags=["chat"])],
url="http://0.0.0.0:8000",
version="1.0.0",
)

a2a_app.run(
agent_card=agent_card,
host="0.0.0.0",
port=8000,
)

按 esc 键退出编辑模式，输入 :wq 按回车键，保存并退出文件。

在项目根目录中执行如下命令，将应用构建并部署到 AgentKit 智能体运行时。

agentkit launch

说明

首次部署耗时较长，请耐心等待。

当回显智能体运行时状态为 Ready 时，则表示创建成功，您可以在此获取智能体运行时名称、ID 及本次部署使用的相关云资源信息。

该 Agent 作为处理差旅、考勤和请假等公司政策问题的业务 Agent，无需对外暴露调用入口。

执行如下命令，使用 AgentKit CLI 预置模板创建基于 A2A 协议的 Agent 项目。

agentkit init policy-support-agent \
--template a2a \
--directory policy-support-agent

参数说明

参数	说明
[project_name]	Agent 项目名称，本实践以 policy-support-agent 为例。
--template	指定用于初始化 Agent 的 CLI 预置模板 ID、Key 或名称。本实践以 a2a 模板为例。
--directory	指定用于存放 Agent 项目的目录路径，若不存在 AgentKit CLI 会自动创建该目录。本实践以 policy-support-agent 目录为例。

说明

请将 policy-support-agent 替换为实际 Agent 项目根目录路径。

cd policy-support-agent

执行如下命令，配置 Agent 部署地域。

agentkit config \
--project_name default \
--region <your_registry_region>

参数说明

参数	说明
--project_name	部署的智能体运行时所属项目，本实践以 default 项目为例。注意请确保智能体运行时所属项目与目标 A2A 空间保持一致。项目是一组资源的集合，您可以将本次创建的智能体运行时添加至项目中并按项目维度统一管理，有利于保持资源独立，维护数据安全。了解更多
--region	部署的智能体运行时所属地域，请将 <your_registry_region> 替换为您创建的 A2A 空间所在地域 ID，本实践 cn-beijing 地域为例。支持：华北 2（北京）：cn-beijing 华东 2（上海）：cn-shanghai 注意请确保智能体运行时所属地域与目标 A2A 空间保持一致。

按需修改 Agent 应用入口文件，调整 Agent 的行为。

在项目根目录中，执行如下命令，打开 Agent 代码文件。

vim policy-support-agent.py

按 i 键进入编辑模式，使用如下内容替换模板默认的 Agent 信息。

import logging

from veadk import Agent, Runner
from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
from agentkit.apps import AgentkitA2aApp

logger = logging.getLogger(__name__)
a2a_app = AgentkitA2aApp()

def query_company_policy(topic: str) -> dict[str, str]:
"""Look up a company policy by topic.

The topic MUST be expressed in English, even when the user asks in another
language (translate their intent into the matching English topic first).
Only these three policy areas are supported:
- travel: business travel and expense reimbursement, e.g. "travel
reimbursement", "flight booking", "hotel expense", "taxi invoice"
- attendance: attendance and clock-in rules, e.g. "attendance", "clock-in
time", "check-in", "working hours", "late arrival"
- leave: time-off requests, e.g. "annual leave", "vacation", "sick leave",
"a day off", "PTO"
"""
policies = {
"travel": "Travel reimbursement policy: flights and hotels must be booked through the approved company platform. Taxi reimbursement requires a digital invoice.",
"attendance": "Attendance policy: employees must check in before 10:00 AM on workdays. Late arrival over 30 minutes requires manager approval.",
"leave": "Leave policy: annual leave should be submitted in the HR system at least one business day in advance, except for emergencies.",
}

# Lowercase, trim and treat hyphens as spaces so that "check-in" matches
# "check in", "time-off" matches "time off", etc.
normalized_topic = topic.lower().strip().replace("-", " ")

travel_keywords = (
"travel", "reimbursement", "reimburse", "trip", "expense",
"flight", "hotel", "accommodation", "lodging", "taxi", "cab",
"invoice", "allowance", "per diem", "business trip",
)
attendance_keywords = (
"attendance", "clock", "check in", "sign in", "late", "tardy",
"punctual", "work hour", "working hour", "time card", "timesheet",
)
leave_keywords = (
"leave", "vacation", "annual leave", "day off", "days off",
"time off", "pto", "sick leave", "absence", "holiday request",
)

if any(keyword in normalized_topic for keyword in travel_keywords):
key = "travel"
elif any(keyword in normalized_topic for keyword in attendance_keywords):
key = "attendance"
elif any(keyword in normalized_topic for keyword in leave_keywords):
key = "leave"
else:
return {
"result": "No matching policy was found. Contact HR or the policy owner for clarification."
}

return {"result": policies[key]}

agent_name = "policy_support_agent"
description = "A company policy assistant."
system_prompt = (
"You are a company policy assistant. "
"Whenever the user asks about travel/expense reimbursement, attendance/clock-in, "
"or leave/vacation, call query_company_policy. "
"The tool only accepts English topics, so regardless of the user's language, "
"always translate their intent into one of the supported English topics: "
"travel reimbursement, attendance, or leave. "
"Do not invent policies that are not returned by the tool."
)

tools = [query_company_policy]

agent = Agent(
name=agent_name,
description=description,
instruction=system_prompt,
tools=tools,
)
runner = Runner(agent=agent)

@a2a_app.agent_executor(runner=runner)
class MyAgentExecutor(A2aAgentExecutor):
pass

@a2a_app.ping
def ping() -> str:
return "pong!"

if __name__ == "__main__":
from a2a.types import AgentCard, AgentProvider, AgentSkill, AgentCapabilities

agent_card = AgentCard(
capabilities=AgentCapabilities(streaming=True),
description=agent.description,
name=agent.name,
default_input_modes=["text"],
default_output_modes=["text"],
provider=AgentProvider(organization="veadk", url=""),
skills=[
AgentSkill(
id="0",
name="policy_chat",
description="Company policy Q&A",
tags=["policy", "travel", "attendance", "leave"],
)
],
url="http://0.0.0.0:8000",
version="1.0.0",
)

a2a_app.run(
agent_card=agent_card,
host="0.0.0.0",
port=8000,
)

按 esc 键退出编辑模式，输入 :wq 按回车键，保存并退出文件。

在项目根目录中执行如下命令，将应用构建并部署到 AgentKit 智能体运行时。

agentkit launch

说明

首次部署耗时较长，请耐心等待。

当回显智能体运行时状态为 Ready 时，则表示创建成功，您可以在此获取智能体运行时名称、ID 及本次部署使用的相关云资源信息。

步骤三：注册智能体

在左侧导航树中选择“基础组件 > A2A 中心”。

在下拉框中选择您在步骤一中创建的 A2A 空间，单击“注册智能体”按钮。

选择“智能体运行时”页签，并配置如下注册参数。

说明

本实践仅配置必要参数，未提及的参数保持默认。全量参数介绍请参见注册智能体。

参数	说明	图示
智能体运行时	选择您在步骤二中部署的智能体运行时。注意 a2a-dispatcher 对应的智能体运行时无需注册到 A2A 空间。
服务地址	选择智能体运行时后，自动匹配智能体运行时的服务地址。本实践以公网为例。

单击“立即注册”按钮，完成操作。

说明

本文需注册 it-support-agent、 policy-support-agent 两个业务 Agent，请重复 3 ~ 5 步骤完成操作。

步骤四：验证 Agent 发现与调用

验证 Agent 可以独立工作。

it-support-agent
policy-support-agent
执行如下命令，发送 Prompt。
说明
请将 r-yettxxxx 替换为实际 it-support-agent 对应智能体运行时 ID。

agentkit invoke run \
--runtime-id r-yettxxxx \
"如何配置VPN"

根据回显信息，确认 Agent 可以正常回复。
执行如下命令，发送 Prompt。
说明
请将 r-yettxxxx 替换为实际 policy-support-agent 对应智能体运行时 ID。

agentkit invoke run \
--runtime-id r-yettxxxx \
"如何申请出差"

根据回显信息，确认 Agent 可以正常回复。

验证 a2a-dispatcher 能识别调用方请求，并将 IT 支持问题或公司政策问题委派给 A2A 空间内的对应业务 Agent。

说明

请将 r-yettxxxx 替换为实际 a2a-dispatcher 对应智能体运行时 ID。

执行如下命令，验证是否可以正常调用 it-support-agent。

agentkit invoke run \
--runtime-id r-yettxxxx \
"如何配置VPN"

根据回显信息，确认 a2a-dispatcher 可以将 IT 相关任务正常发送给 it-support-agent 执行，且最终回复包含 VPN 固定数据中的关键信息。

执行如下命令，验证是否可以正常调用 policy-support-agent 。

agentkit invoke run \
--runtime-id r-yettxxxx \
"如何申请出差"

根据回显信息，确认 a2a-dispatcher 可以将差旅、假期相关任务正常发送给 policy-support-agent 执行，且最终回复包含差旅政策固定数据中的关键信息。

至此，您已完成 A2A 空间创建、运行时部署及业务 Agent 注册，并成功验证 A2A 空间的 Agent 发现、调用能力。

最近更新时间：2026.09.14 19:08:49

这个页面对您有帮助吗？

有用

无用