Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of mappen te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen om mappen te wijzigen.
Hiermee A2AAgent kan uw toepassing verbinding maken met externe agents die beschikbaar worden gemaakt via het A2A-protocol (Agent-to-Agent). Het verpakt elk A2A-compatibel eindpunt als een standaard AIAgent, zodat u vertrouwde methoden zoals RunAsync en RunStreamingAsync interactie met externe agents kunt gebruiken, ongeacht het framework of de technologie waarmee ze zijn gebouwd.
Getting Started
Voeg het vereiste NuGet-pakket toe aan uw project:
dotnet add package Microsoft.Agents.AI.A2A --prerelease
Agentdetectie
Voordat u communiceert met een externe A2A-agent, moet u deze detecteren en een AIAgent exemplaar maken. Het A2A-protocol definieert drie detectiestrategieën, die elk worden ondersteund door het Agent Framework.
Well-Known-URI
A2A-agents kunnen hun agentkaart detecteren op een gestandaardiseerd pad: https://{domain}/.well-known/agent-card.json. Gebruik de A2ACardResolver opdracht om de kaart op te halen en een agent te maken in één aanroep:
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!"));
Tip
GetAIAgentAsync accepteert ook een optionele A2AClientOptions parameter voor protocolselectie.
Catalog-Based Detectie
In bedrijfsomgevingen of openbare marketplaces worden agentkaarten vaak beheerd door een centraal register. Als u al een AgentCard dergelijk register hebt verkregen, converteert u het rechtstreeks naar een 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."));
Directe configuratie
Voor nauw gekoppelde systemen of ontwikkelscenario's waarbij het agenteindpunt van tevoren bekend is, maakt u een A2AClient rechtstreeks en converteert u het naar een 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(name: "my-agent", description: "A helpful assistant.");
Console.WriteLine(await agent.RunAsync("What can you help me with?"));
Protocolselectie
A2A-agents kunnen meerdere protocolbindingen beschikbaar maken, zoals HTTP+JSON en JSON-RPC. HTTP+JSON heeft standaard de voorkeur boven JSON-RPC. Gebruik A2AClientOptions.PreferredBindings dit om expliciet te bepalen welke protocolbinding wordt gebruikt:
Note
De externe A2A-agent moet beschikbaar zijn op een eindpunt dat ondersteuning biedt voor de geselecteerde protocolbinding.
using A2A;
using Microsoft.Agents.AI;
A2ACardResolver agentCardResolver = new(new Uri("https://a2a-agent.example.com"));
AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
// Prefer HTTP+JSON protocol binding. For JSON-RPC, set PreferredBindings = [ProtocolBindingNames.JsonRpc]
A2AClientOptions options = new()
{
PreferredBindings = [ProtocolBindingNames.HttpJson]
};
AIAgent agent = agentCard.AsAIAgent(options: options);
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
Streaming
A2A ondersteunt streamingreacties via Server-Sent Gebeurtenissen. Gebruik RunStreamingAsync deze functie om updates in realtime te ontvangen wanneer de externe agent de aanvraag verwerkt:
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);
}
}
Achtergrondantwoorden
A2A-agents ondersteunen achtergrondreacties voor het verwerken van langlopende bewerkingen. Wanneer een externe A2A-agent een taak retourneert in plaats van een direct bericht, biedt het Agent Framework een vervolgtoken dat u kunt gebruiken om resultaten te peilen of opnieuw verbinding te maken met onderbroken streams.
Polling voor taakvoltooiing
Gebruik voor scenario's zonder AllowBackgroundResponses streaming een vervolgtoken en poll totdat de taak is voltooid:
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();
// AllowBackgroundResponses must be true so the server returns immediately with a continuation token
// instead of blocking until the task is complete.
AgentRunOptions options = new() { AllowBackgroundResponses = true };
// Start the initial run with a long-running task.
AgentResponse response = await agent.RunAsync(
"Conduct a comprehensive analysis of quantum computing applications in cryptography.",
session,
options: options);
// Poll until the response is complete.
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);
Stream Opnieuw verbinden
In streamingscenario's kan elke update een vervolgtoken bevatten. Als de stream wordt onderbroken, gebruikt u het token om opnieuw verbinding te maken en de antwoordstroom vanaf het begin te verkrijgen:
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(
"Conduct a comprehensive analysis of quantum computing applications in cryptography.",
session))
{
// Save the continuation token to reconnect later if the stream is interrupted.
// Continuation tokens are only returned for long-running tasks. If the A2A agent
// returns a message instead of a task, the continuation token will not be initialized.
if (update.ContinuationToken is { } token)
{
continuationToken = token;
}
}
// If the stream was interrupted and a continuation token was captured,
// reconnect to the response stream using the saved continuation token.
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);
}
}
}
Note
A2A-agents ondersteunen het opnieuw verbinden van stromen (het verkrijgen van dezelfde antwoordstroom vanaf het begin), niet het hervatten van stromen vanaf een specifiek punt in de stream.
Tools
A2AAgent is een transportniveau-wrapper rond een externe A2A-agent. Welke hulpprogramma's de externe agent ook live gebruikt aan de externe kant en zijn onzichtbaar voor uw code. Agent Framework-hulpprogrammatypen (functiehulpprogramma's, code-interpreter, bestandszoekopdrachten, gehoste/lokale MCP, enzovoort) zijn niet geconfigureerd op zichzelf A2AAgent . Als u de mogelijkheden van de externe agent wilt uitbreiden, wijzigt u de configuratie van de externe agent.
Getting Started
Installeer het A2A-pakket:
pip install agent-framework-a2a --pre
Initialisatie
A2AAgent kan op drie manieren worden geïnitialiseerd, afhankelijk van hoeveel u van tevoren weet over de externe agent.
Directe URL
Voor ontwikkel- of nauw gekoppelde systemen waar het eindpunt bekend is:
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)
Wanneer er alleen een URL wordt opgegeven, A2AAgent maakt u intern een minimale agentkaart en maakt u verbinding met behulp van JSON-RPC.
Agentkaart
Als u een AgentCard van een register of catalogus hebt, geeft u deze rechtstreeks door:
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)
Wanneer er een AgentCard wordt opgegeven, A2AAgent worden de standaardinstellingen name en description de kaart gebruikt. Het onderhandelt over vervoer met behulp van de kaart supported_interfaces.
Well-Known URI (A2ACardResolver)
Gebruik A2ACardResolver van de app a2a-sdk om de externe agent te detecteren op het standaard bekende pad (/.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
Gebruik stream=True deze functie om updates in realtime te ontvangen wanneer de externe agent de aanvraag verwerkt:
from agent_framework.a2a import A2AAgent
async with A2AAgent(name="remote", url="https://a2a-agent.example.com") as agent:
async with agent.run("Write a short story about a robot.", stream=True) as stream:
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))")
Langdurige taken
Standaard wacht A2AAgent totdat de externe agent klaar is voordat het wordt geretourneerd. Voor langlopende taken kunt background=True u een vervolgtoken weergeven dat u kunt gebruiken om later te peilen of u te abonneren:
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)
U kunt zich ook opnieuw abonneren op de SSE-stream in plaats van polling:
# Resubscribe to the task's event stream
response = await agent.run(continuation_token=response.continuation_token)
Gespreksidentiteit (context_id)
Wanneer u belt A2AAgent.run() met een AgentSession, wordt de A2A context_id automatisch afgeleid van session.service_session_id als het uitgaande bericht nog geen bericht bevat. Hiermee kunt u de gesprekscontinuïteit behouden voor meerdere A2A-aanroepen:
from agent_framework import AgentSession
from agent_framework.a2a import A2AAgent
async with A2AAgent(name="remote", url="https://a2a-agent.example.com") as agent:
session = AgentSession(service_session_id="my-conversation-1")
# context_id is automatically set to "my-conversation-1"
response = await agent.run("Hello!", session=session)
# Subsequent calls with the same session continue the conversation
response = await agent.run("Follow-up question", session=session)
Als een bericht een expliciete context_id waarde in zijn additional_properties bevat, heeft die waarde voorrang op de back-up afgeleid van de sessie.
Authentication
Gebruik een AuthInterceptor voor beveiligde A2A-eindpunten:
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!")
Time-outconfiguratie
A2AAgent accepteert een timeout parameter voor het beheren van time-outs voor aanvragen:
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.0) 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:
...
Wanneer er geen time-out is opgegeven, zijn de standaardwaarden: 10s connect, 60s read, 10s write, 5s pool.
Tools
A2AAgent is een transportniveau-wrapper rond een externe A2A-agent. Welke hulpprogramma's de externe agent ook live gebruikt aan de externe kant en zijn onzichtbaar voor uw code. Agent Framework-hulpprogrammatypen (functiehulpprogramma's, code-interpreter, bestandszoekopdrachten, gehoste/lokale MCP, enzovoort) zijn niet geconfigureerd op zichzelf A2AAgent . Als u de mogelijkheden van de externe agent wilt uitbreiden, wijzigt u de configuratie van de externe agent.
Als u wilt dat een Foundry-agent een A2A-agent aanroept als hulpprogramma, raadpleegt u de get_a2a_tool fabriek.FoundryChatClient