使用代理到代理通信

A2A 字段

下表描述了 agent.yaml文件的 a2a: 部分中的字段：

使用 A2A 作为 LLM 工具

app.a2a_tools() 方法返回两个 LangChain StructuredTool 对象：discover_available_agents 和 invoke_a2a_agent。这些对象允许 LLM 自主发现并调用其他代理。将它们与现有工具绑定，以便模型可以自行路由到其他代理。

当 a2a.enabled 是 agent.yaml文件中的 false 时，app.a2a_tools() 方法会返回一个空列表，因此可以安全地包含在所有代理中。

以下示例将 2A 工具与现有工具绑定：

from agent_engine_sdk_langgraph import App
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph
from langgraph.prebuilt import ToolNode
app = App(app_name="router-agent")
@app.entrypoint
def build_agent():
    llm = app.llm(ChatOpenAI(model="gpt-5.4"))
    a2a = app.a2a_tools()
    llm_with_tools = llm.bind_tools(
        app.get_tool_schemas() + a2a
    )
    tool_node = ToolNode(app.get_tools() + a2a)
    graph = StateGraph(...)
    return graph.compile(checkpointer=app.checkpointer())

绑定到 LLM 时，该模型会按名称调用这两个工具。这些工具公开以下函数签名：

• discover_available_agents() 返回对调用代理可见的代理的JSON列表。每个条目包括 agent_id、name、description、skills 和 capabilities。调用代理会从其自身的结果中筛选出来。

• invoke_a2a_agent(agent_id, message, custom_headers="") 调用目标代理并以JSON形式返回结果。如果提供 custom_headers，请将其作为JSON字符串传递，示例'{"x-tenant": "acme"}'。

直接调用 A2A 客户端

当您想使用确定性路由时，可以直接通过 runtime.a2a（公开客户端的属性）访问权限AgentToAgent客户端。

以下示例按技能发现客服人员并调用第一个匹配项：

agents = app._runtime.a2a.discover_agents(
    skills=["policy-lookup"],
    limit=10,
)
if agents:
    resp = app._runtime.a2a.invoke_agent(
        agent_id=agents[0].agent_id,
        message="Look up policy POL-123",
        skill="policy-lookup",
        timeout=120,
    )
    if resp.status == "completed":
        print(resp.result)

当 A2A 不可用时，runtime.a2a 属性会返回 None。要学习；了解何时会发生这种情况，请参阅注意事项。在调用客户端方法之前，请务必检查是否存在这种情况，如以下示例所示：

a2a = app._runtime.a2a
if a2a is None:
    ...

AgentToAgent 类

AgentToAgent 是与 OE /a2a/discover 和 /a2a/invoke 端点通信的 HTTP客户端。在代理代码中，使用 runtime.a2a 中预先经过身份验证的实例，而不是直接构造此类。

以下示例显示了构造函数及其参数：

AgentToAgent(oe_url: str, auth_token: str = "")

下表描述了 AgentToAgent 构造函数参数：

find_agents() 方法

discover_agents() 方法返回允许调用者查看的代理。当您在单个过滤参数中传递多个值时，如果代理满足其中任何一个值，则匹配。示例，skills=["a", "b"] 会返回宣传任一技能的座席。当您传递多个过滤参数时，代理必须满足所有这些参数。未启用 2A 并通过 allowed_callers 排除调用者的座席永远不会返回。

以下示例展示了此方法及其参数：

discover_agents(
    project_id: str = "",
    skills: list[str] | None = None,
    capabilities: list[str] | None = None,
    input_modes: list[str] | None = None,
    limit: int = 50,
) -> list[DiscoveredAgent]

下表描述了 discover_agents() 方法的参数：

invoke_agent() 方法

invoke_agent() 方法调用目标代理并等待结果。操作环境会验证令牌、检查访问权限控制、创建子执行并进行轮询，直到代理完成、暂停以供人工查看或超时。

以下示例展示了此方法及其参数：

invoke_agent(
    agent_id: str,
    message: str,
    skill: str = "",
    timeout: float | None = None,
    custom_headers: dict[str, str] | None = None,
) -> AgentResponse

下表描述了 invoke_agent() 方法的参数：

响应数据类

下表列出了响应类型，它们都是不可变数据类：

resp = app._runtime.a2a.invoke_agent(
    agent_id="ws-billing-001",
    message="Process the payment",
)
if resp.status == "completed":
    handle(resp.result)
elif resp.status == "input-required":
    notify_user(
        "The billing agent needs human approval before continuing."
    )
else:
    log.error("A2A call failed: %s", resp.error)

将标头传递给被调用的代理

要将标头附加到被调用的代理，请使用 invoke_agent() 的 custom_headers 参数传递 dict。使用 invoke_a2a_agent LLM 工具时，请将标头作为JSON字符串传递。

以下示例使用直接客户端传递自定义标头：

app._runtime.a2a.invoke_agent(
    agent_id="ws-billing-001",
    message="Charge the customer",
    custom_headers={
        "x-tenant": "acme",
        "oauth-token": "<delegated-token>",
    },
)

以下示例使用 LLM 工具传递自定义标头：

invoke_a2a_agent(
    agent_id="ws-billing-001",
    message="Charge the customer",
    custom_headers='{"x-tenant": "acme"}',
)

标头键不得使用保留的 a2a- 不区分大小写的前缀。如果有任何密钥以 a2a- 开头，则 OE 将拒绝具有 400 Bad Request 响应的请求。 a2a- 前缀保留用于平台路由和身份标头，例如 a2a-token 和 a2a-caller-workspace。

从调用者处读取标头

要读取调用代理转发的自定义标头，请使用 agent_engine_runner_shared.context 类中的 get_current_custom_headers() 方法。以下示例调用此方法：

from agent_engine_runner_shared.context import get_current_custom_headers
headers = get_current_custom_headers()
tenant = headers.get("x-tenant")

get_current_custom_headers() 返回 dict[str, str]。该方法在返回之前会剥离所有 a2a- 平台标头，因此您的代理代码永远不会看到 A2A 令牌或路由元元数据。如果调用者没有发送自定义标头，该方法将返回一个空字典。

当 runtime.a2a 返回 None 时

runtime.a2a 仅当满足以下所有条件时才返回客户端：

1. 代理代码在代理沙箱中运行。 A2A 无法从工具沙箱中运行的代码中获得。

2. 执行上下文中存在 OE URL 。

3. 传入标头中存在 a2a-token。配置 A2A 后，OE 会在每次调度时自动注入此令牌。

不满足任何条件时，runtime.a2a 会返回 None。使用 app.a2a_tools() 时，这些工具会返回结构化错误JSON，而不是引发异常。

令牌生命周期

默认下，A2A 令牌会在 5 分钟后过期。对于典型的请求与响应流，这就足够了。运行时间超过令牌生命周期的代理可能会收到针对 2A 调用的 401 响应。自动令牌刷新尚未实现。将长时间运行的调用的 401 响应视为暂时性故障。

自发现筛选器

discover_available_agents LLM 工具会从结果中筛选出调用代理自己的工作区，以便模型不会调用自身。如果您使用原始 discover_agents()客户端方法，则 OE 可能会在结果中包含您自己的代理。如果需要，请自行过滤掉。

项目内范围

在当前发布中，2发现和调用仅限于同一项目中的代理。跨项目路由尚未实现。

可观察性

平台会自动记录并关联每个 2A 调用。您无需添加仪器。目标作为通过 parent_execution_id 链接到调用者的子执行运行。共享的 root_session_id 将完整的跨代理调用树分组在原始用户会话下。