A2A-agent

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!"));

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:

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);
        }
    }
}