这使 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 代理作为工具示例 。
后续步骤
更深入: