A2A-Agent

Die A2AAgent Anwendung ermöglicht es Ihrer Anwendung, eine Verbindung mit Remote-Agents herzustellen, die über das A2A-Protokoll (Agent-to-Agent) verfügbar gemacht werden. Er umschließt jeden A2A-kompatiblen Endpunkt als Standard AIAgent, sodass Sie vertraute Methoden wie RunAsync und RunStreamingAsync für die Interaktion mit Remote-Agents verwenden können, unabhängig davon, mit welchem Framework oder welcher Technologie sie erstellt wurden.

Getting Started

Fügen Sie dem Projekt das erforderliche NuGet-Paket hinzu:

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

Agent Discovery

Bevor Sie mit einem A2A-Remote-Agent kommunizieren, müssen Sie ihn ermitteln und eine AIAgent Instanz erstellen. Das A2A-Protokoll definiert drei Ermittlungsstrategien, die jeweils vom Agent Framework unterstützt werden.

Well-Known-URI

A2A-Agents können ihre Agent-Karte in einem standardisierten Pfad auffindbar machen: https://{domain}/.well-known/agent-card.json. Verwenden Sie die A2ACardResolver Karte, um die Karte abzurufen und einen Agent in einem einzigen Anruf zu erstellen:

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 akzeptiert auch einen optionalen A2AClientOptions Parameter für die Protokollauswahl.

Catalog-Based Discovery

In Unternehmensumgebungen oder öffentlichen Marketplaces werden Agent-Karten häufig von einer zentralen Registrierung verwaltet. Wenn Sie bereits über eine AgentCard solche Registrierung verfügen, konvertieren Sie sie direkt in eine 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."));

Direkte Konfiguration

Erstellen Sie für eng gekoppelte Systeme oder Entwicklungsszenarien, in denen der Agentendpunkt im Voraus bekannt ist, eine A2AClient direkte Erstellung und Konvertierung in eine 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?"));

Protokollauswahl

A2A-Agents können mehrere Protokollbindungen wie HTTP+JSON und JSON-RPC verfügbar machen. Standardmäßig wird HTTP+JSON gegenüber JSON-RPC bevorzugt. Wird A2AClientOptions.PreferredBindings verwendet, um explizit zu steuern, welche Protokollbindung verwendet wird:

Note

Der Remote-A2A-Agent muss an einem Endpunkt verfügbar sein, der die ausgewählte Protokollbindung unterstützt.

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

Streamen

A2A unterstützt Streamingantworten über Server-Sent Ereignisse. Wird verwendet RunStreamingAsync , um Updates in Echtzeit zu empfangen, während der Remote-Agent die Anforderung verarbeitet:

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

Hintergrundantworten

A2A-Agents unterstützen Hintergrundantworten für die Behandlung lang ausgeführter Vorgänge. Wenn ein A2A-Remote-Agent eine Aufgabe anstelle einer sofortigen Nachricht zurückgibt, stellt das Agent Framework ein Fortsetzungstoken bereit, mit dem Sie Ergebnisse abfragen oder eine erneute Verbindung mit unterbrochenen Datenströmen herstellen können.

Abrufen des Vorgangsabschlusses

Verwenden Sie AllowBackgroundResponses für Nicht-Streaming-Szenarien, um ein Fortsetzungstoken zu empfangen und abzufragen, bis die Aufgabe abgeschlossen ist:

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 Reconnection

In Streamingszenarien kann jedes Update ein Fortsetzungstoken enthalten. Wenn der Datenstrom unterbrochen wird, verwenden Sie das Token, um die Verbindung wiederherzustellen und den Antwortdatenstrom von Anfang an abzurufen:

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 unterstützen die Erneute Verbindung des Datenstroms (abrufen desselben Antwortdatenstroms von Anfang an), nicht die Datenstromaufnahme von einem bestimmten Punkt im Datenstrom.

Note

Dokumentation für Python A2A-Agents wird in Kürze verfügbar sein.

Nächste Schritte

Benutzerdefinierter Anbieter