A2A 호스팅

에이전트 프레임워크는 A2A(에이전트 간) 프로토콜을 통해 AI 에이전트를 노출하는 호스팅 패키지를 제공합니다. 호스트되면 A2A 규격 클라이언트는 클라이언트가 빌드된 프레임워크 또는 기술에 관계없이 에이전트를 검색하고 통신할 수 있습니다.

NuGet 패키지:

Microsoft.Agents.AI.Hosting.A2A.AspNetCore - ASP.NET Core에서 A2A 프로토콜 바인딩을 위한 엔드포인트 매핑. 이 패키지에는 전이적으로 포함됩니다 Microsoft.Agents.AI.Hosting.A2A.
Microsoft.Agents.AI.Hosting.A2A - AI 에이전트를 A2A 프로토콜(서버 등록, 요청 처리, 세션 관리)에 브리징하기 위한 핵심 호스팅 논리입니다.

시작하기

ASP.NET Core 호스팅 패키지를 설치합니다(코어 패키지에서 자동으로 끌어오기).

dotnet add package Microsoft.Agents.AI.Hosting.A2A.AspNetCore --prerelease
dotnet add package A2A.AspNetCore --prerelease
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

다음 예제에서는 A2A를 통해 단일 에이전트를 호스트하는 최소 ASP.NET Core 애플리케이션을 보여 줍니다. Microsoft Foundry를 AI 공급자로 사용합니다. 다른 옵션은 공급자를 참조하세요.

using A2A;
using A2A.AspNetCore;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

string endpoint = builder.Configuration["AZURE_AI_PROJECT_ENDPOINT"]
    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
string model = builder.Configuration["AZURE_AI_MODEL"] ?? "gpt-4o-mini";

// 1. Create and register the "weather-agent" agent in the DI container.
builder.Services.AddKeyedSingleton<AIAgent>("weather-agent", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(
            model: model,
            instructions: "You are a helpful weather assistant.",
            name: "weather-agent");
});

// 2. Register the A2A server for the "weather-agent" agent.
builder.AddA2AServer("weather-agent");

var app = builder.Build();

// 3. Map A2A protocol endpoints for the "weather-agent" agent.
app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");

// 4. Serve a minimal agent card for the "weather-agent" agent discovery.
app.MapWellKnownAgentCard(new AgentCard
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    SupportedInterfaces =
    [
        new AgentInterface
        {
            Url = "http://localhost:5000/a2a/weather-agent",
            ProtocolBinding = ProtocolBindingNames.HttpJson,
            ProtocolVersion = "1.0",
        }
    ]
});

app.Run();

이제 A2A HTTP+JSON 프로토콜 바인딩을 통해 /a2a/weather-agent에서 에이전트에 연결할 수 있으며, 에이전트 카드는 /.well-known/agent.json에서 검색할 수 있습니다. A2A 규격 클라이언트는 이 에이전트를 검색하고 통신할 수 있습니다.

프로토콜 바인딩

A2A 프로토콜은 두 개의 전송 바인딩을 정의합니다. 둘 다 지원됩니다.

Binding	메서드	설명
HTTP+JSON	`MapA2AHttpJson`	스트리밍에 대한 표준 HTTP 요청 및 Server-Sent 이벤트입니다.
JSON-RPC	`MapA2AJsonRpc`	HTTP를 통해 JSON-RPC 2.0.

클라이언트가 원하는 전송을 선택할 수 있도록 두 바인딩을 동시에 매핑할 수 있습니다. 필요한 경우 다른 경로를 사용할 수 있습니다.

app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");  // HTTP+JSON
app.MapA2AJsonRpc("weather-agent", "/a2a/weather-agent");   // JSON-RPC

에이전트 카드

에이전트 카드 는 클라이언트가 요청을 보내기 전에 해당 기능을 검색하고 이해할 수 있도록 에이전트의 메타데이터(이름, 설명, 버전 및 지원되는 인터페이스)를 설명합니다. 시작 섹션에는 최소 에이전트 카드가 표시됩니다. 프로덕션 사용을 위해 완전히 채워진 카드를 제공합니다.

using A2A;
using A2A.AspNetCore;

app.MapWellKnownAgentCard(new AgentCard
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    Version = "1.0",
    DefaultInputModes = ["text"],
    DefaultOutputModes = ["text"],
    SupportedInterfaces =
    [
        new AgentInterface
        {
            Url = "http://localhost:5000/a2a/weather-agent",
            ProtocolBinding = ProtocolBindingNames.HttpJson,
            ProtocolVersion = "1.0",
        }
    ]
});

메모

MapWellKnownAgentCard 는 에이전트 프레임워크 호스팅 패키지가 아닌 A2A SDK 패키지(A2A.AspNetCore)에서 제공됩니다.

팁 (조언)

호스트당 하나의 에이전트 카드만 제공될 수 있으므로 잘 알려진 경로를 통해 하나의 에이전트만 검색할 수 있습니다. 다른 에이전트는 여전히 URL을 통해 직접 연결할 수 있습니다. 자세한 옵션은 에이전트 검색 을 참조하세요.

`AddA2AServer` 작동 방식

메서드는 AddA2AServer 종속성 주입 컨테이너에 키 A2AServer 지정된 싱글톤을 등록합니다. 서버가 생성되면 다음과 같은 여러 내부 구성 요소를 확인하거나 만듭니다.

구성 요소	Default	Purpose
`IAgentHandler`	`A2AAgentHandler`	들어오는 A2A 요청을 `AIAgent`에 연결합니다. 메시지를 번역하고, 에이전트를 실행하고, 응답을 A2A 메시지로 반환합니다.
`AgentSessionStore`	`InMemoryAgentSessionStore`	에이전트가 동일한 `contextId`여러 요청에서 컨텍스트를 유지할 수 있도록 대화 세션을 저장합니다.
`ITaskStore`	`InMemoryTaskStore`	장기 실행 A2A 작업의 작업 상태를 추적합니다.
`AgentRunMode`	`DisallowBackground`	에이전트가 직접 메시지 대신 백그라운드 응답(A2A 작업)을 반환할 수 있는지 여부를 제어합니다.

Warning

기본값 InMemoryAgentSessionStore 이며 InMemoryTaskStore 개발 전용입니다. 상태는 애플리케이션 다시 시작 시 손실되며 여러 인스턴스에서 공유되지 않습니다. 프로덕션 배포의 경우 지속성 구현을 등록합니다.

기본값 재정의

호출 AddA2AServer하기 전에 DI 컨테이너에 키 지정된 서비스를 등록하여 이러한 구성 요소를 바꿀 수 있습니다. 서버는 에이전트 이름을 키로 사용하여 키가 설정된 서비스를 해결합니다.

사용자 지정 세션 저장소 - 영구 대화 스토리지:

builder.Services.AddKeyedSingleton<AgentSessionStore>("weather-agent", new MyDurableSessionStore());

builder.AddA2AServer("weather-agent");

사용자 지정 작업 저장소 - 지속성 작업 추적:

builder.Services.AddKeyedSingleton<ITaskStore>("weather-agent", new MyDurableTaskStore());

builder.AddA2AServer("weather-agent");

사용자 지정 에이전트 처리기 - 요청 처리를 완전히 제어합니다. IAgentHandler가 등록되면 기본 A2AAgentHandler을 완전히 대체합니다.

builder.Services.AddKeyedSingleton<IAgentHandler>("weather-agent", new MyCustomHandler());

builder.AddA2AServer("weather-agent");

에이전트 실행 모드 - A2AServerRegistrationOptions를 통해 구성:

builder.AddA2AServer("weather-agent", options =>
{
    options.AgentRunMode = AgentRunMode.DisallowBackground;
});

여러 에이전트

단일 애플리케이션에서 여러 에이전트를 호스트할 수 있습니다. 각 에이전트는 자체 A2A 서버 및 엔드포인트를 가져옵니다.

// Register agents in DI.
builder.Services.AddKeyedSingleton<AIAgent>("weather-agent", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(model: model, instructions: "You are a helpful weather assistant.", name: "weather-agent");
});

builder.Services.AddKeyedSingleton<AIAgent>("scientist", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(model: model, instructions: "You are a scientist.", name: "scientist");
});

// Register A2A servers.
builder.AddA2AServer("weather-agent");
builder.AddA2AServer("scientist");

var app = builder.Build();

// Map endpoints.
app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");
app.MapA2AHttpJson("scientist", "/a2a/scientist");

app.Run();

이 예제에서는 두 에이전트 모두 에이전트 카드가 없으므로 클라이언트는 엔드포인트 URL을 직접 알아야 합니다. 에이전트 카드 검색을 MapWellKnownAgentCard사용하여 추가할 수 있지만 호스트당 하나의 에이전트만 보급할 수 있습니다. 에이전트 카드를 참조하세요.

백그라운드 응답

메모

A2A 호스팅 에이전트에 대한 백그라운드 응답은 아직 지원되지 않습니다. 기본값AgentRunMode은 DisallowBackground 모든 응답이 즉시 A2A 메시지로 반환됨을 의미합니다.

다음 단계

A2A 공급자

참고하십시오

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-04-24