A2A Agent

Funkcja A2AAgent umożliwia aplikacji łączenie się z agentami zdalnymi, którzy są uwidaczniani za pośrednictwem protokołu Agent-to-Agent (A2A). Opakowuje on dowolny punkt końcowy zgodny ze standardem AIAgentA2A, dzięki czemu można używać znanych metod, takich jak RunAsync i RunStreamingAsync do interakcji z agentami zdalnymi niezależnie od struktury lub technologii, z którymi zostały utworzone.

Wprowadzenie

Dodaj wymagany pakiet NuGet do projektu:

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

Odnajdywanie agentów

Przed komunikacją ze zdalnym agentem A2A należy go odnaleźć i utworzyć AIAgent wystąpienie. Protokół A2A definiuje trzy strategie odnajdywania, z których każda jest obsługiwana przez platformę Agent Framework.

identyfikator URI Well-Known

Agenci A2A mogą wykrywać kartę agenta w ustandaryzowanej ścieżce: https://{domain}/.well-known/agent-card.json. Użyj elementu A2ACardResolver , aby pobrać kartę i utworzyć agenta w jednym wywołaniu:

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

Wskazówka

GetAIAgentAsync Akceptuje również opcjonalny A2AClientOptions parametr wyboru protokołu.

odnajdywanie Catalog-Based

W środowiskach przedsiębiorstwa lub publicznych platformach handlowych karty agentów są często zarządzane przez centralny rejestr. Jeśli masz AgentCard już uzyskany z takiego rejestru, przekonwertuj go bezpośrednio na element 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."));

Konfiguracja bezpośrednia

W przypadku ściśle powiązanych systemów lub scenariuszy programowania, w których punkt końcowy agenta jest znany przed upływem czasu, utwórz bezpośrednio i przekonwertuj A2AClient go na element 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?"));

Wybór protokołu

Agenci A2A mogą uwidaczniać wiele powiązań protokołu, takich jak HTTP+JSON i JSON-RPC. Domyślnie kod HTTP+JSON jest preferowany przez protokół JSON-RPC. Użyj A2AClientOptions.PreferredBindings polecenia , aby jawnie kontrolować, które powiązanie protokołu jest używane:

Uwaga / Notatka

Zdalny agent A2A musi być dostępny w punkcie końcowym obsługującym wybrane powiązanie protokołu.

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

Usługa A2A obsługuje odpowiedzi przesyłania strumieniowego za pośrednictwem zdarzeń Server-Sent. Użyj RunStreamingAsync polecenia , aby odbierać aktualizacje w czasie rzeczywistym, ponieważ agent zdalny przetwarza żądanie:

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

Odpowiedzi w tle

Agenci A2A obsługują odpowiedzi w tle na potrzeby obsługi długotrwałych operacji. Gdy zdalny agent A2A zwraca zadanie zamiast natychmiastowego komunikatu, struktura agenta udostępnia token kontynuacji, którego można użyć do sondowania wyników lub ponownego nawiązania połączenia ze strumieniami przerwania.

Sondowanie pod kątem ukończenia zadania

W przypadku scenariuszy nieprzesyłania strumieniowego użyj polecenia AllowBackgroundResponses , aby otrzymać token kontynuacji i sondować, dopóki zadanie nie zostanie ukończone:

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

Ponowne nawiązywanie połączenia ze strumieniem

W scenariuszach przesyłania strumieniowego każda aktualizacja może zawierać token kontynuacji. Jeśli strumień zostanie przerwany, użyj tokenu, aby ponownie nawiązać połączenie i uzyskać strumień odpowiedzi od początku:

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

Uwaga / Notatka

Agenci A2A obsługują ponowne łączenie strumienia (uzyskiwanie tego samego strumienia odpowiedzi od początku), a nie wznowienie strumienia z określonego punktu w strumieniu.

Uwaga / Notatka

Dokumentacja agentów A2A języka Python jest dostępna wkrótce.

Następne kroki

Dostawca niestandardowy