Агент A2A

Это A2AAgent позволяет приложению подключаться к удаленным агентам, предоставляемым через протокол "агент — агент" (A2A). Она упаковывает любую конечную точку, совместимую с A2A, как стандартную AIAgent, поэтому вы можете использовать знакомые методы, такие как RunAsync и RunStreamingAsync взаимодействовать с удаленными агентами независимо от того, с какой платформой или технологией они были созданы.

Getting Started

Добавьте необходимый пакет NuGet в проект:

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

Обнаружение агентов

Прежде чем взаимодействовать с удаленным агентом A2A, необходимо обнаружить его и создать AIAgent экземпляр. Протокол A2A определяет три стратегии обнаружения, каждая из которых поддерживается платформой агента.

URI Well-Known

Агенты 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!"));

Tip

GetAIAgentAsync также принимает необязательный A2AClientOptions параметр для выбора протокола.

Обнаружение Catalog-Based

В корпоративных средах или общедоступных платформах карточки агента часто управляются центральным реестром. Если у вас уже есть полученный 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(name: "my-agent", description: "A helpful assistant.");

Console.WriteLine(await agent.RunAsync("What can you help me with?"));

Выбор протокола

Агенты A2A могут предоставлять несколько привязок протокола, таких как HTTP+JSON и JSON-RPC. По умолчанию для JSON-RPC предпочтительнее http+JSON. Используется A2AClientOptions.PreferredBindings для явного управления используемой привязкой протокола:

Note

Удаленный агент A2A должен быть доступен в конечной точке, поддерживающей выбранную привязку протокола.

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

Стриминг

A2A поддерживает потоковую передачу ответов с помощью событий Server-Sent. Используется 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);
    }
}

Фоновые ответы

Агенты A2A поддерживают фоновые ответы для обработки длительных операций. Когда удаленный агент A2A возвращает задачу вместо немедленного сообщения, платформа агента предоставляет маркер продолжения, который можно использовать для опроса результатов или повторного подключения к прерванным потокам.

Опрос для завершения задачи

Для сценариев без потоковой передачи используйте AllowBackgroundResponses для получения маркера продолжения и опроса до завершения задачи:

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

Повторное подключение потока

В сценариях потоковой передачи каждое обновление может включать маркер продолжения. Если поток прерван, используйте маркер для повторного подключения и получения потока ответа с самого начала:

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 поддерживают повторное подключение потока (получение одного потока отклика с самого начала), а не возобновление потоков из определенной точки в потоке.

Note

В ближайшее время будет представлена документация по агентам Python A2A.

Дальнейшие действия

Настраиваемый поставщик