A2A 代理

这使 A2AAgent 应用程序能够连接到通过 代理到代理 (A2A) 协议公开的远程代理。 它将任何符合 A2A 的终结点包装为标准 AIAgent,因此可以使用熟悉的方法(例如 RunAsync ,并与 RunStreamingAsync 远程代理交互),而不考虑它们使用哪种框架或技术。

Warning

在连接到 A2A 代理之前,请验证是否信任运行远程代理的组织或发布者终结点 URL。 将来自远程代理的响应视为不受信任的应用程序输入。 在代码执行副作用或呈现内容之前对其进行验证。

若要将代理框架代理公开为 A2A 服务器,请参阅 具有 A2A 的主机代理。

入门

将所需的 NuGet 包添加到项目:

dotnet add package Microsoft.Agents.AI.A2A --prerelease

代理发现

在与远程 A2A 代理通信之前,需要发现它并创建实例 AIAgent 。 A2A 协议定义了三种 发现策略,每个策略都受代理框架支持。

已知 URI

A2A 代理可以在标准化路径上发现其代理卡: https://{domain}/.well-known/agent-card.json 使用 A2ACardResolver 提取卡片并在单个调用中创建代理:

using A2A;
using Microsoft.Agents.AI;

// Initialize a resolver pointing at the remote agent's host.
A2ACardResolver resolver = new(new Uri("https://a2a-agent.example.com"));

// Resolve the agent card and create an AIAgent in one step.
AIAgent agent = await resolver.GetAIAgentAsync();

// Use the agent.
Console.WriteLine(await agent.RunAsync("Hello!"));

参考: A2ACardResolverExtensions。

Tip

GetAIAgentAsync还接受用于协议选择的可选A2AClientOptions参数。

基于目录的发现

在企业环境或公共市场中,代理卡通常由中央注册表管理。 如果已 AgentCard 从此类注册表获取,请将其直接转换为 AIAgent:

using A2A;
using Microsoft.Agents.AI;

// Assume agentCard was retrieved from a registry or catalog.
AgentCard agentCard = await GetAgentCardFromRegistryAsync("travel-planner");

AIAgent agent = agentCard.AsAIAgent();

Console.WriteLine(await agent.RunAsync("Plan a trip to Paris."));

直接配置

对于提前知道代理终结点的紧密耦合系统或开发方案,请直接创建一个 A2AClient 并将其转换为 AIAgent:

using A2A;
using Microsoft.Agents.AI;

// Create a client pointing at the known agent endpoint.
A2AClient a2aClient = new(new Uri("https://a2a-agent.example.com"));

AIAgent agent = a2aClient.AsAIAgent();

Console.WriteLine(await agent.RunAsync("What can you help me with?"));

参考: A2AClientExtensions。

AsAIAgent 适用于任何 IA2AClient 实现。 它和 A2AAgent 构造函数接受可选 A2AAgentOptions 设置代理的 Id、 Name和 Description。

替代代理卡标识

默认情况下,基于卡片的创建使用卡片和 NameDescription。 传递给agentOptions或重写Id,Name或A2ACardResolver.GetAIAgentAsyncDescription。AgentCard.AsAIAgent 将不设置的属性回退到卡片的值:

using A2A;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.A2A;

A2ACardResolver resolver = new(new Uri("https://a2a-agent.example.com"));

AIAgent agent = await resolver.GetAIAgentAsync(new A2AAgentOptions
{
    Id = "travel-agent-id",
    Name = "travel-agent",
    Description = "Plans trips and suggests itineraries."
});

参考: A2AAgentOptions、 A2ACardResolverExtensions。

传递agentOptions时,通过clientOptions传递协议设置。 不 agentOptions 带名称的重载同一参数 options。

协议选择

A2A 代理可以公开 HTTP+JSON、JSON-RPC 和 gRPC 绑定。 默认情况下,基于卡片的创建接受 HTTP+JSON 和 JSON-RPC。 SDK 选择匹配A2AClientOptions.PreferredBindings的第一个接口AgentCard.SupportedInterfaces,因此卡片的接口顺序决定了选择。

设置为 PreferredBindings 将所选内容限制为列表的绑定。 这会在创建过程中选择客户端;当请求失败时,它不会启用自动故障转移:

using A2A;
using Microsoft.Agents.AI;

A2ACardResolver agentCardResolver = new(
    new Uri("https://a2a-agent.example.com"));

AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();

// Select HTTP+JSON. Use ProtocolBindingNames.JsonRpc for JSON-RPC.
A2AClientOptions options = new()
{
    PreferredBindings = [ProtocolBindingNames.HttpJson]
};

AIAgent agent = agentCard.AsAIAgent(options: options);

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

注释

远程 A2A 代理必须在支持所选协议绑定的终结点上可用。

如果已知道终结点及其绑定,请跳过卡片并直接创建绑定的客户端。 每个客户端实现 IA2AClient,因此可以使用 AsAIAgent():

Binding Client Package
JSON-RPC A2AClient A2A
HTTP+JSON A2AHttpJsonClient A2A
gRPC A2AGrpcClient A2A.Grpc
using A2A;
using Microsoft.Agents.AI;

A2AHttpJsonClient a2aClient = new(new Uri("https://a2a-agent.example.com"));

AIAgent agent = a2aClient.AsAIAgent();

参考: A2AClientExtensions。

gRPC

该 A2A 包不包括 gRPC 支持。 添加 A2A SDK 的可选 gRPC 包:

dotnet add package A2A.Grpc --prerelease

对于基于卡片的发现,在应用程序启动期间注册 gRPC 绑定一次。 卡必须播发 gRPC 接口:

using A2A;
using A2A.Grpc;
using Microsoft.Agents.AI;

A2AGrpcClientRegistration.Register();

A2ACardResolver resolver = new(new Uri("https://a2a-agent.example.com"));

AIAgent agent = await resolver.GetAIAgentAsync(
    options: new A2AClientOptions
    {
        PreferredBindings = [ProtocolBindingNames.Grpc]
    });

Console.WriteLine(await agent.RunAsync("Hello over gRPC!"));

参考: A2ACardResolverExtensions、 A2A 示例。

发现仍通过 HTTP 提取代理卡,然后连接到卡中列出的 gRPC 终结点。 A2AGrpcClient直接创建不需要注册。

身份验证和 HTTP 配置

对于 HTTP 绑定,传递 HttpClient 通过 httpClient 参数 AgentCard.AsAIAgent 或 A2ACardResolver.GetAIAgentAsync. 使用它来配置身份验证标头或超时。

有关在转发凭据之前对播发的终结点源进行身份验证的发现和验证,请参阅 A2A 身份验证指南。

会话和后续任务

创建会话,并跨轮次重复使用会话以保留远程会话:

using A2A;
using Microsoft.Agents.AI;

A2ACardResolver resolver = new(new Uri("https://a2a-agent.example.com"));

AIAgent agent = await resolver.GetAIAgentAsync();

AgentSession session = await agent.CreateSessionAsync();

Console.WriteLine(await agent.RunAsync("Plan a trip to Paris.", session));
Console.WriteLine(await agent.RunAsync("Make it three days.", session));

参考: A2AAgent、 A2AGentSession。

会话是 A2AAgentSession 跟踪以下协议状态的会话:

Property Purpose
ContextId 标识远程对话。
TaskId 标识响应包含一个时的最新任务。
TaskState 记录用于路由下一条消息的任务状态。

当任务状态为 InputRequired时,使用同一会话在正常 RunAsync 或 RunStreamingAsync 调用中发送请求的输入。 代理将传出消息 TaskId 设置为继续该任务。 对于其他状态,它会在 .. 中 ReferenceTaskIds发送上一个任务 ID。

保留会话并 SerializeSessionAsync 还原会话, DeserializeSessionAsync 以保留上下文、任务 ID、任务状态和状态包。 若要从已知上下文和任务 ID 创建会话,请使用 A2AAgent.CreateSessionAsync 重载。

Streaming

用于 RunStreamingAsync 在远程代理处理请求时接收更新。

using A2A;
using Microsoft.Agents.AI;

A2ACardResolver resolver = new(new Uri("https://a2a-agent.example.com"));
AIAgent agent = await resolver.GetAIAgentAsync();

await foreach (var update in agent.RunStreamingAsync(
    "Write a short story about a robot."))
{
    if (!string.IsNullOrEmpty(update.Text))
    {
        Console.Write(update.Text);
    }
}

参考: AIAgent.RunStreamingAsync。

流式更新可以表示消息、任务快照、状态更新或项目更新。

会话在流枚举完成后更新,而不是在每个更新之后更新。 若要从中断的流中恢复,请使用保存的延续令牌,如 Stream 重新连接中所示。

后台响应

A2A 代理支持长时间运行的操作 的后台响应 。 当远程代理返回处于或Working状态的任务Submitted时,响应包括用于轮询或流重新连接的延续标记。

注释

使用 Agent Framework 托管的代理.NET A2A 托管包始终使用消息进行响应,因此其响应不包含延续令牌。 有关详细信息,请参阅 任务支持。

轮询任务完成

设置为 AllowBackgroundResponses 请求立即返回,而不是等待任务完成。 这会设置 A2A 请求的配置 ReturnImmediately ,并需要显式会话:

using A2A;
using Microsoft.Agents.AI;

A2ACardResolver resolver = new(new Uri("https://a2a-agent.example.com"));
AIAgent agent = await resolver.GetAIAgentAsync();

AgentSession session = await agent.CreateSessionAsync();

// Request an immediate response when the remote agent creates a task.
AgentRunOptions options = new() { AllowBackgroundResponses = true };

// Start the initial run with a long-running task.
AgentResponse response = await agent.RunAsync(
    "Analyze quantum computing applications in cryptography.",
    session,
    options: options);

// Poll while the task is submitted or working.
while (response.ContinuationToken is { } token)
{
    // Wait before polling again.
    await Task.Delay(TimeSpan.FromSeconds(2));

    // Continue with the token.
    response = await agent.RunAsync(
        session,
        options: new AgentRunOptions { ContinuationToken = token });
}

Console.WriteLine(response);

参考: AIAgent.RunAsync、 AgentRunOptions。

传递延续令牌时, RunAsync 检索现有任务 GetTaskAsync ,而不是启动新的运行。 不要在该调用中包含新消息。

缺少的延续标记不一定意味着成功。 等待输入或身份验证的任务,以及失败、取消或拒绝的任务,也不会返回延续令牌。 检查应用程序需要区分这些结果时的任务状态 response.RawRepresentation 。

流重新连接

处于或Working状态的Submitted流式处理任务快照包括延续标记。 保存令牌(如果存在);以后的更新可能不包括它。 如果流中断,请使用保存的令牌重新连接到任务的事件流。

以下示例在保存继续标记以模拟中断后停止读取,然后重新连接到该令牌。

using A2A;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

A2ACardResolver resolver = new(new Uri("https://a2a-agent.example.com"));
AIAgent agent = await resolver.GetAIAgentAsync();

AgentSession session = await agent.CreateSessionAsync();

ResponseContinuationToken? continuationToken = null;

await foreach (var update in agent.RunStreamingAsync(
    "Analyze quantum computing applications in cryptography.",
    session))
{
    // Save the token for reconnection after an interruption.
    if (update.ContinuationToken is { } token)
    {
        continuationToken = token;

        // Stop reading to simulate a stream interruption.
        break;
    }
}

// Reconnect after the simulated interruption.
if (continuationToken is not null)
{
    await foreach (var update in agent.RunStreamingAsync(
        session,
        options: new() { ContinuationToken = continuationToken }))
    {
        if (!string.IsNullOrEmpty(update.Text))
        {
            Console.WriteLine(update.Text);
        }
    }
}

参考: AIAgent.RunStreamingAsync、 AgentRunOptions。

注释

重新连接不会从特定事件或文本偏移中恢复。 根据需要处理重复的任务快照或项目内容。

Tools

A2AAgent 是远程 A2A 代理周围的传输级包装器。 远程代理使用的任何工具都位于远程端,并且对代码不可见。 代理框架工具类型(函数工具、代码解释器、文件搜索、托管/本地 MCP 等)本身未配置 A2AAgent - 若要扩展远程代理的功能,请更改远程代理的配置。

若要让另一个代理调用远程代理,请使用 AsAIFunction()。 有关完整示例,请参阅 A2A 示例。

入门

安装 A2A 包:

pip install agent-framework-a2a --pre

初始 化

A2AAgent 可以通过三种方式初始化,具体取决于你事先对远程代理的了解程度。

直接 URL

对于已知终结点的开发或紧密耦合系统:

from agent_framework.a2a import A2AAgent

async with A2AAgent(name="remote", url="https://a2a-agent.example.com") as agent:
    response = await agent.run("Hello!")
    print(response.messages[0].text)

仅提供 URL 时,在 A2AAgent 内部创建最小代理卡并使用 JSON-RPC 进行连接。

创建的 HTTP 客户端 A2AAgent 不会持久保存响应 Cookie。 如果远程服务需要 Cookie 进行身份验证、会话或负载均衡器相关性,请传递一个httpx.AsyncClient。http_client= 将客户端限定为一个经过身份验证的主体,并在应用程序中将其关闭。 提供的 HTTP 客户端仍然是调用方拥有的,包括同时传递 client=时。

代理卡

如果有 AgentCard 注册表或目录,请直接传递它:

from agent_framework.a2a import A2AAgent

async with A2AAgent(agent_card=agent_card) as agent:
    response = await agent.run("Plan a trip to Paris.")
    print(response.messages[0].text)

提供 AgentCardA2AAgent默认值name和description卡片时。 它使用卡的 supported_interfaces协商传输。

已知 URI (A2ACardResolver)

在A2ACardResolvera2a-sdk标准已知路径/.well-known/agent.json():

import httpx
from a2a.client import A2ACardResolver
from agent_framework.a2a import A2AAgent

async with httpx.AsyncClient(timeout=60.0) as http_client:
    resolver = A2ACardResolver(httpx_client=http_client, base_url="https://a2a-agent.example.com")
    agent_card = await resolver.get_agent_card()

async with A2AAgent(agent_card=agent_card) as agent:
    response = await agent.run("What can you help me with?")
    print(response.messages[0].text)

Streaming

用于 stream=True 在远程代理处理请求时实时接收更新:

from agent_framework.a2a import A2AAgent

async with A2AAgent(name="remote", url="https://a2a-agent.example.com") as agent:
    stream = agent.run("Write a short story about a robot.", stream=True)
    async for update in stream:
        for content in update.contents:
            if content.text:
                print(content.text, end="", flush=True)

    final = await stream.get_final_response()
    print(f"\n({len(final.messages)} message(s))")

二进制附件

A2AAgent 以原始二进制 A2A 部件的形式发送数据支持 Content 。 零字节有效负载在流式处理和非流式处理运行中有效。 媒体类型、数据 URI 参数、base64 编码和字符验证仍适用。

长期任务

默认情况下, A2AAgent 等待远程代理在返回之前完成。 对于长时间运行的任务,设置为 background=True 显示一个延续令牌,可用于稍后轮询或订阅:

from agent_framework.a2a import A2AAgent

async with A2AAgent(name="worker", url="https://a2a-agent.example.com") as agent:
    # Start a long-running task
    response = await agent.run("Process this large dataset", background=True)

    if response.continuation_token:
        # Poll for completion later
        result = await agent.poll_task(response.continuation_token)
        print(result)

还可以重新订阅 SSE 流,而不是轮询:

# Resubscribe to the task's event stream
response = await agent.run(continuation_token=response.continuation_token)

对话标识(context_id)

A2AAgent 将持久协议状态 AgentSession.service_session_id 存储为 A2AServiceSessionId 映射:

领域 类型 Purpose
context_id str 标识 A2A 对话。
task_id str \| None 跟踪响应创建时的最新远程任务。
task_state TaskState \| None 记录最新的任务状态,以便下一个请求可以继续输入所需的任务或引用已完成的任务。

当应用程序已知道 A2A 上下文时,创建具有结构化状态的会话:

from agent_framework import AgentSession
from agent_framework.a2a import A2AAgent, A2AServiceSessionId

async with A2AAgent(name="remote", url="https://a2a-agent.example.com") as agent:
    session = AgentSession(
        service_session_id=A2AServiceSessionId(
            context_id="my-conversation-1",
            task_id=None,
            task_state=None,
        )
    )

    # The A2A message uses context_id="my-conversation-1".
    response = await agent.run("Hello!", session=session)

    # A2AAgent updates task_id and task_state from the response.
    response = await agent.run("Follow-up question", session=session)

还可以从第一个响应开始 AgentSession() 并填充 A2AAgent 结构化映射。 保留常规会话并使用 session.to_dict()AgentSession.from_dict(...);A2A 上下文、任务 ID 和任务状态保持不变。

对于任务, TASK_STATE_INPUT_REQUIRED下一条消息将设置继续 task_id 执行同一任务。 对于其他任务状态,将发送 reference_task_ids 上一个任务 ID,以便远程代理可以优化或继续从前面的结果。

转发所选运行上下文

选择function_invocation_kwargsclient_kwargs或必须访问远程服务时用作forwarded_kwargs允许列表:

async with A2AAgent(
    name="remote",
    url="https://a2a-agent.example.com",
    forwarded_kwargs=["tenant_id", "trace"],
) as agent:
    response = await agent.run(
        "Create the report.",
        function_invocation_kwargs={"tenant_id": "contoso", "secret": "not-forwarded"},
        client_kwargs={"trace": {"id": "abc"}},
    )

仅按其源映射分组的 SendMessageRequest.metadata 下面 agent_framework发送列出的密钥。 默认值不发送运行 kwargs,元数据不会添加到 HTTP 标头或消息历史记录。

接收服务使用独立的允许列表:

from agent_framework.a2a import A2AExecutor

executor = A2AExecutor(
    local_agent,
    accepted_function_invocation_kwargs=["tenant_id"],
    accepted_client_kwargs=["trace"],
)

默认情况下,服务不接受任何内容。 仅当客户端转发其密钥和服务接受匹配源映射中的相同密钥时,值才会到达本地代理。 将转发的元数据视为请求上下文,而不是身份验证或授权。

转发的值必须与 JSON 兼容。 映射键必须是字符串,数字必须是有限的,整数必须介于和2**53(含)之间-(2**53)。 Protobuf Struct 将数字存储为双精度值,因此整数以浮点值的形式到达。 发送请求之前引发 AgentInvalidRequestException 的选定值无效。

Authentication

请使用AuthInterceptor来保护 A2A 终结点:

from a2a.client.auth.interceptor import AuthInterceptor
from agent_framework.a2a import A2AAgent

class BearerAuth(AuthInterceptor):
    def __init__(self, token: str):
        self.token = token

    async def intercept(self, request):
        request.headers["Authorization"] = f"Bearer {self.token}"
        return request

async with A2AAgent(
    name="secure-agent",
    url="https://secure-a2a-agent.example.com",
    auth_interceptor=BearerAuth("your-token"),
) as agent:
    response = await agent.run("Hello!")

超时配置

A2AAgent接受秒int数。float 该值适用于连接、读取、写入和池超时组件。 传递对象 httpx.Timeout 以单独配置这些值:

import httpx
from agent_framework.a2a import A2AAgent

# Simple timeout (applies to all components)
async with A2AAgent(name="remote", url="https://example.com", timeout=120) as agent:
    ...

# Fine-grained timeout
async with A2AAgent(
    name="remote",
    url="https://example.com",
    timeout=httpx.Timeout(connect=10.0, read=120.0, write=10.0, pool=5.0),
) as agent:
    ...

如果未指定超时,则默认值为:10 秒连接、60 秒读取、10 秒写入、5s 池。

Tools

A2AAgent 是远程 A2A 代理周围的传输级包装器。 远程代理使用的任何工具都位于远程端,并且对代码不可见。 代理框架工具类型(函数工具、代码解释器、文件搜索、托管/本地 MCP 等)本身未配置 A2AAgent - 若要扩展远程代理的功能,请更改远程代理的配置。

如果希望 Foundry 代理以工具的形式调用 A2A 代理,请参阅工厂get_a2a_tool。FoundryChatClient

Go 通过 provider/a2aprovider 包支持远程 A2A 代理。

安装代理框架和 A2A 包:

go get github.com/microsoft/agent-framework-go
go get github.com/a2aproject/a2a-go/v2

连接到远程 A2A 代理

解析远程代理卡,从它创建 A2A 客户端,并将客户端包装为标准 Agent Framework 代理:

import (
    "context"

    "github.com/a2aproject/a2a-go/v2/a2aclient"
    "github.com/a2aproject/a2a-go/v2/a2aclient/agentcard"
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/a2aprovider"
)

ctx := context.Background()

card, err := agentcard.DefaultResolver.Resolve(ctx, "http://localhost:5000")
if err != nil {
    panic(err)
}

client, err := a2aclient.NewFromCard(ctx, card)
if err != nil {
    panic(err)
}

a := a2aprovider.NewAgent(
    client,
    a2aprovider.AgentConfig{
        Config: agent.Config{
            Name:        card.Name,
            Description: card.Description,
        },
    },
)

resp, err := a.RunText(ctx, "Hello!").Collect()

提供程序将 A2A context_id 和任务 ID 存储在代理框架会话中,以便后续消息可以保留会话连续性。

协议选择

如果远程代理播发多个传输绑定,请在创建 A2A 客户端时配置首选传输:

client, err := a2aclient.NewFromCard(
    ctx,
    card,
    a2aclient.WithConfig(a2aclient.Config{
        PreferredTransports: []a2a.TransportProtocol{a2a.TransportProtocolHTTPJSON},
    }),
)

想要首选 JSON-RPC 时使用 a2a.TransportProtocolJSONRPC 。

长期任务

A2A 任务通过代理框架延续标记浮出水面。 使用显式会话和 agent.AllowBackgroundResponses(true) 启动运行,然后在不传入新消息并附带继续令牌的情况下调用 Run 进行轮询:

session, err := a.CreateSession(ctx)
if err != nil {
    panic(err)
}

resp, err := a.RunText(
    ctx,
    "Process this large dataset.",
    agent.WithSession(session),
    agent.AllowBackgroundResponses(true),
).Collect()
if err != nil {
    panic(err)
}

for resp.ContinuationToken != "" {
    resp, err = a.Run(
        ctx,
        nil,
        agent.WithSession(session),
        agent.WithContinuationToken(resp.ContinuationToken),
    ).Collect()
    if err != nil {
        panic(err)
    }
}

对于中断的流式传输运行,请从最后一次收到的更新中获取 update.ContinuationToken,并在后续的流式传输运行中将其与 agent.WithContinuationToken(token) 和 agent.Stream(true) 一起传递。

使用远程 A2A 代理作为工具

解析每个远程代理,将其a2aprovider.NewAgent包装,并将其转换为工具。agenttool.New

tools := make([]tool.Tool, 0, len(agentURLs))

for _, agentURL := range agentURLs {
    card, err := agentcard.DefaultResolver.Resolve(ctx, agentURL)
    if err != nil {
        panic(err)
    }

    client, err := a2aclient.NewFromCard(ctx, card)
    if err != nil {
        panic(err)
    }

    remoteAgent := a2aprovider.NewAgent(client, a2aprovider.AgentConfig{
        Config: agent.Config{
            Name:        card.Name,
            Description: card.Description,
        },
    })

    tools = append(tools, agenttool.New(remoteAgent, agenttool.Config{}))
}

Tip

有关完整的可运行示例,请参阅 A2A 提供程序示例 和 A2A 代理作为工具示例 。

后续步骤

更深入: