A2A .NET SDK Comprehensive Documentation

1. 프로젝트 개요

A2A (Agent2Agent) .NET SDK는 Google의 A2A Protocol v0.2.1을 구현하는 .NET 라이브러리로, .NET 애플리케이션에서 에이전트 간 통신을 가능하게 합니다. 이 SDK는 ASP.NET Core 애플리케이션과 함께 작동하도록 설계되어 에이전트에 A2A 지원을 추가하는 간단한 방법을 제공합니다.

주요 기능

• 프로토콜 호환성: A2A Protocol v0.2.1의 대부분 기능 구현
• 다중 프레임워크 지원: .NET 9.0, .NET 8.0, .NET Standard 2.0 지원
• ASP.NET Core 통합: 간단한 통합 방법 제공
• 작업 관리: 표준화된 작업 관리 및 실행 지원
• 스트리밍: 실시간 스트리밍 응답 지원
• OpenTelemetry: 내장된 텔레메트리 및 관찰 가능성 지원

프로젝트 상태

라이브러리는 프로토콜 기능의 대부분을 구현했지만, 일부 시나리오는 여전히 불완전할 수 있습니다. 가장 큰 누락 기능은 푸시 알림을 사용한 클라이언트 콜백입니다.

2. A2A .NET Core 아키텍처

2.1 프로젝트 구조

src/
├── A2A/                    # 핵심 A2A 프로토콜 구현
│   ├── Client/            # 클라이언트 구성 요소
│   ├── JsonRpc/           # JSON-RPC 구현
│   ├── Models/            # 데이터 모델
│   ├── Server/            # 서버 측 구성 요소
│   └── openapi.yaml       # API 사양
└── A2A.AspNetCore/        # ASP.NET Core 통합

2.2 핵심 구성 요소

1. A2A Core Library: 핵심 프로토콜 구현 포함
2. A2A.AspNetCore: ASP.NET Core 통합 제공
3. Sample Projects: 다양한 사용 시나리오를 보여주는 예제 코드

3. A2A .NET 클라이언트 구현

3.1 A2AClient 클래스

A2AClient 클래스는 에이전트와 통신하기 위한 주요 클라이언트 인터페이스로, IA2AClient 인터페이스를 구현합니다.

주요 기능:

public class A2AClient : IA2AClient
{
    // 메시지 전송
    public Task<A2AResponse> SendMessageAsync(MessageSendParams taskSendParams)
    
    // 작업 가져오기
    public Task<AgentTask> GetTaskAsync(string taskId)
    
    // 작업 취소
    public Task<AgentTask> CancelTaskAsync(TaskIdParams taskIdParams)
    
    // 스트림 메시지 전송
    public async IAsyncEnumerable<SseItem<A2AEvent>> SendMessageStreamAsync(MessageSendParams taskSendParams)
    
    // 작업 재구독
    public async IAsyncEnumerable<SseItem<A2AEvent>> ResubscribeToTaskAsync(string taskId)
}

주요 특징:

1. JSON-RPC 통신: 모든 통신은 JSON-RPC 프로토콜을 통해 수행
2. 스트리밍 응답: 실시간 스트리밍을 위한 Server-Sent Events (SSE) 지원
3. 직렬화 최적화: 고성능 직렬화를 위해 System.Text.Json 소스 생성기 사용
4. 오류 처리: 완전한 오류 처리 및 상태 관리

3.2 JsonRpcContent 클래스

JSON-RPC 요청을 위한 전용 HTTP 콘텐츠 클래스:

public class JsonRpcContent : HttpContent
{
    public JsonRpcContent(JsonRpcRequest request)
    {
        _request = request;
        Headers.ContentType = new MediaTypeHeaderValue("application/json");
    }
}

3.3 A2ACardResolver 클래스

에이전트 카드 정보 파싱 및 검색에 사용:

public class A2ACardResolver
{
    public async Task<AgentCard> GetAgentCardAsync(Uri agentUri)
    public async Task<AgentCard> GetAgentCardAsync(string agentUrl)
}

4. A2A .NET 서버 구현

4.1 TaskManager 클래스

TaskManager는 작업 생명주기 관리를 담당하는 핵심 서버 측 구성 요소입니다.

주요 책임:

1. 작업 생명주기 관리: 작업 생성, 업데이트, 취소
2. 메시지 처리: 들어오는 메시지 및 작업 업데이트 처리
3. 이벤트 배포: 작업 상태 변경 이벤트 관리
4. 저장소 추상화: ITaskStore 인터페이스를 통한 작업 지속성

핵심 메서드:

public class TaskManager : ITaskManager
{
    // 이벤트 핸들러
    public Func<MessageSendParams, Task<Message>>? OnMessageReceived { get; set; }
    public Func<AgentTask, Task> OnTaskCreated { get; set; }
    public Func<AgentTask, Task> OnTaskCancelled { get; set; }
    public Func<AgentTask, Task> OnTaskUpdated { get; set; }
    public Func<string, AgentCard> OnAgentCardQuery { get; set; }
    
    // 핵심 작업
    public async Task<AgentTask> CreateTaskAsync(string? contextId = null)
    public async Task<AgentTask?> CancelTaskAsync(TaskIdParams? taskIdParams)
    public async Task<A2AResponse?> SendMessageAsync(MessageSendParams messageSendParams)
    public async Task<IAsyncEnumerable<A2AEvent>> SendMessageStreamAsync(MessageSendParams messageSendParams)
    public async Task UpdateStatusAsync(string taskId, TaskState status, Message? message = null, bool final = false)
    public async Task ReturnArtifactAsync(string taskId, Artifact artifact)
}

4.2 ITaskStore 인터페이스

작업 저장을 위한 추상 인터페이스:

public interface ITaskStore
{
    Task<AgentTask?> GetTaskAsync(string taskId);
    Task SetTaskAsync(AgentTask task);
    Task UpdateStatusAsync(string taskId, TaskState status);
}

4.3 ASP.NET Core 통합

A2A.AspNetCore 라이브러리에서 제공하는 확장 메서드를 통해:

// JSON-RPC A2A 지원 추가
app.MapA2A(taskManager, "/echo");

// HTTP A2A 지원 추가
app.MapHttpA2A(taskManager, "/echo");

5. A2A .NET 데이터 모델

5.1 핵심 모델 클래스

AgentCard - 에이전트 카드

public class AgentCard
{
    public string Name { get; set; }                    // 에이전트 이름
    public string Description { get; set; }            // 에이전트 설명
    public string Url { get; set; }                     // 에이전트 URL
    public AgentProvider? Provider { get; set; }        // 제공자 정보
    public string Version { get; set; }                 // 버전 정보
    public AgentCapabilities Capabilities { get; set; } // 에이전트 기능
    public List<AgentSkill> Skills { get; set; }        // 에이전트 기술
    public List<string> DefaultInputModes { get; set; } // 기본 입력 모드
    public List<string> DefaultOutputModes { get; set; }// 기본 출력 모드
}

AgentTask - 에이전트 작업

public class AgentTask : A2AResponse
{
    public string Id { get; set; }                      // 작업 ID
    public string? ContextId { get; set; }              // 컨텍스트 ID
    public AgentTaskStatus Status { get; set; }         // 작업 상태
    public List<Artifact>? Artifacts { get; set; }      // 작업 아티팩트
    public List<Message>? History { get; set; }         // 메시지 기록
    public Dictionary<string, JsonElement>? Metadata { get; set; } // 메타데이터
}

Message - 메시지

public class Message : A2AResponse
{
    public MessageRole Role { get; set; }               // 메시지 역할 (User/Agent)
    public List<Part> Parts { get; set; }               // 메시지 부분
    public string? MessageId { get; set; }              // 메시지 ID
    public string? TaskId { get; set; }                 // 연관된 작업 ID
    public string? ContextId { get; set; }              // 컨텍스트 ID
    public Dictionary<string, JsonElement>? Metadata { get; set; } // 메타데이터
}

5.2 작업 상태

public enum TaskState
{
    Submitted,      // 제출됨
    Working,        // 작업 중
    InputRequired,  // 입력 필요
    Completed,      // 완료됨
    Canceled,       // 취소됨
    Failed,         // 실패
    Rejected        // 거부됨
}

5.3 메시지 부분 유형

여러 메시지 부분 유형 지원:

• TextPart: 텍스트 콘텐츠
• FilePart: 파일 콘텐츠
• DataPart: 데이터 콘텐츠

6. A2A .NET AgentServer 예제 상세 분석

6.1 프로젝트 개요

AgentServer 예제는 다음을 포함하여 여러 다른 유형의 에이전트를 생성하고 배포하는 방법을 보여줍니다:

1. EchoAgent: 간단한 에코 에이전트
2. EchoAgentWithTasks: 작업 지원이 있는 에코 에이전트
3. HostedClientAgent: 호스팅된 클라이언트 에이전트
4. ResearcherAgent: 연구자 에이전트 (상태 머신 구현)

6.2 EchoAgent 구현

public class EchoAgent
{
    private ITaskManager? _taskManager;

    public void Attach(TaskManager taskManager)
    {
        _taskManager = taskManager;
        taskManager.OnMessageReceived = ProcessMessage;
        taskManager.OnAgentCardQuery = GetAgentCard;
    }

    public Task<Message> ProcessMessage(MessageSendParams messageSendParams)
    {
        var messageText = messageSendParams.Message.Parts.OfType<TextPart>().First().Text;
        var message = new Message()
        {
            Role = MessageRole.Agent,
            MessageId = Guid.NewGuid().ToString(),
            ContextId = messageSendParams.Message.ContextId,
            Parts = [new TextPart() { Text = $"Echo: {messageText}" }]
        };
        return Task.FromResult(message);
    }
}

6.3 ResearcherAgent 구현

ResearcherAgent는 더 복잡한 상태 머신 구현을 보여줍니다:

public class ResearcherAgent
{
    private enum AgentState
    {
        Planning,                    // 계획 단계
        WaitingForFeedbackOnPlan,   // 계획 피드백 대기
        Researching                 // 연구 단계
    }

    public async Task Invoke(string taskId, string message)
    {
        switch (_agentStates[taskId])
        {
            case AgentState.Planning:
                await DoPlanning(taskId, message);
                break;
            case AgentState.WaitingForFeedbackOnPlan:
                if (message == "go ahead")
                    await DoResearch(taskId, message);
                else
                    await DoPlanning(taskId, message);
                break;
            case AgentState.Researching:
                await DoResearch(taskId, message);
                break;
        }
    }
}

7. AgentServer 예제 실행 방법

7.1 환경 요구사항

• .NET 9.0 SDK 이상
• 선택사항: OpenTelemetry Collector (텔레메트리 데이터용)

7.2 실행 단계

1. 프로젝트 복제:

   git clone https://github.com/a2aproject/a2a-dotnet
   cd a2a-dotnet
   

2. 예제 디렉토리로 이동:

   cd samples/AgentServer
   

3. 프로젝트 실행:

   dotnet run
   

4. 서비스 실행 확인: 서비스는 다음 포트에서 시작됩니다:

   • HTTP: http://localhost:5048
   • HTTPS: https://localhost:7014

7.3 사용 가능한 엔드포인트

• /echo - 간단한 에코 에이전트
• /echotasks - 작업 지원이 있는 에코 에이전트
• /hostedclient - 호스팅된 클라이언트 에이전트
• /researcher - 연구자 에이전트

7.4 API 호출 테스트

에이전트 카드 가져오기

curl -X GET http://localhost:5048/echo/.well-known/agent.json

에코 에이전트에 메시지 전송

curl -X POST http://localhost:5048/echo \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "messageId": "12345",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Hello, world!"
          }
        ]
      }
    }
  }'

연구자 에이전트 작업 생성

curl -X POST http://localhost:5048/researcher \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "messageId": "research-1",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Research the current price of butter"
          }
        ]
      }
    }
  }'

8. 시퀀스 다이어그램

8.1 간단한 메시지 처리 시퀀스 다이어그램

sequenceDiagram
    participant Client as Client
    participant Server as A2A Server
    participant Agent as Agent Implementation
    participant TaskMgr as TaskManager

    Client->>Server: POST /echo (JSON-RPC message/send)
    Server->>TaskMgr: SendMessageAsync()
    TaskMgr->>Agent: OnMessageReceived()
    Agent->>Agent: ProcessMessage()
    Agent-->>TaskMgr: Return Message
    TaskMgr-->>Server: Return A2AResponse
    Server-->>Client: JSON-RPC Response

8.2 작업 처리 시퀀스 다이어그램

sequenceDiagram
    participant Client as Client
    participant Server as A2A Server
    participant TaskMgr as TaskManager
    participant Agent as Agent Implementation
    participant Store as TaskStore

    Client->>Server: POST /researcher (message/send)
    Server->>TaskMgr: SendMessageAsync()
    TaskMgr->>TaskMgr: CreateTaskAsync()
    TaskMgr->>Store: SetTaskAsync()
    TaskMgr->>Agent: OnTaskCreated()
    Agent->>Agent: State Change (Planning)
    Agent->>TaskMgr: UpdateStatusAsync(Working)
    TaskMgr->>Store: UpdateStatusAsync()
    Agent->>TaskMgr: ReturnArtifactAsync()
    Agent->>TaskMgr: UpdateStatusAsync(InputRequired)
    TaskMgr-->>Server: Return AgentTask
    Server-->>Client: JSON-RPC Response

    Note over Client,Store: Client sends follow-up message

    Client->>Server: POST /researcher (message/send, taskId)
    Server->>TaskMgr: SendMessageAsync()
    TaskMgr->>Store: GetTaskAsync()
    TaskMgr->>Agent: OnTaskUpdated()
    Agent->>Agent: State processing logic
    Agent->>TaskMgr: UpdateStatusAsync(Completed)
    TaskMgr-->>Server: Return AgentTask
    Server-->>Client: JSON-RPC Response

8.3 스트리밍 처리 시퀀스 다이어그램

sequenceDiagram
    participant Client as Client
    participant Server as A2A Server
    participant TaskMgr as TaskManager
    participant Agent as Agent Implementation

    Client->>Server: POST /echo (JSON-RPC message/stream)
    Server->>TaskMgr: SendMessageStreamAsync()
    TaskMgr->>Agent: OnMessageReceived()
    
    loop Streaming Response
        Agent->>TaskMgr: Generate Event
        TaskMgr->>Server: A2AEvent
        Server->>Client: Server-Sent Event
    end
    
    Agent->>TaskMgr: Complete Processing
    TaskMgr->>Server: End Stream
    Server->>Client: Close Connection

9. A2A .NET 주요 설계 패턴

9.1 이벤트 기반 아키텍처

TaskManager는 이벤트 기반 패턴을 사용합니다:

• OnMessageReceived: 들어오는 메시지 처리
• OnTaskCreated: 작업 생성 이벤트
• OnTaskUpdated: 작업 업데이트 이벤트
• OnTaskCancelled: 작업 취소 이벤트

9.2 전략 패턴

다른 에이전트 구현은 다른 처리 전략을 가질 수 있습니다:

• 상태 비저장 처리 (EchoAgent)
• 상태 저장 처리 (ResearcherAgent)
• 작업 지향 처리 (EchoAgentWithTasks)

9.3 저장소 추상화

ITaskStore 인터페이스를 통한 작업 저장소 추상화:

• InMemoryTaskStore: 메모리 내 저장소 구현
• 데이터베이스 저장소 구현으로 확장 가능

10. A2A .NET 성능 및 관찰 가능성

10.1 성능 최적화

1. 소스 생성 직렬화: System.Text.Json 소스 생성기 사용
2. AOT 호환성: Native AOT 컴파일 지원
3. 비동기 처리: async/await 패턴의 포괄적 사용
4. 스트리밍 처리: 대용량 데이터 스트리밍 지원

10.2 관찰 가능성

통합된 OpenTelemetry 지원:

• 분산 추적: ActivitySource 통합
• 메트릭 수집: 작업 상태 및 성능 메트릭
• 로깅: 구조화된 로깅 지원

// OpenTelemetry 구성 예제
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource(TaskManager.ActivitySource.Name)
        .AddSource(A2AJsonRpcProcessor.ActivitySource.Name)
        .AddConsoleExporter()
        .AddOtlpExporter());

11. A2A .NET 요약

A2A .NET SDK는 .NET 애플리케이션에서 에이전트 간 통신을 구현하기 위한 완전하고 프로덕션 준비된 솔루션을 제공합니다.

11.1 주요 장점

1. 표준화된 프로토콜: Google의 A2A Protocol 표준 기반
2. 쉬운 통합: 간단한 ASP.NET Core 통합
3. 유연한 아키텍처: 여러 에이전트 구현 패턴 지원
4. 고성능: 최적화된 직렬화 및 비동기 처리
5. 관찰 가능성: 내장된 텔레메트리 및 모니터링 지원
6. 확장성: 추상 인터페이스가 사용자 정의 구현 지원

11.2 사용 사례

1. AI 에이전트 시스템: 지능형 에이전트 상호작용 시스템 구축
2. 마이크로서비스 아키텍처: 서비스 간 지능형 통신
3. 워크플로 엔진: 복잡한 비즈니스 프로세스의 에이전트 기반 처리
4. 챗봇: 다중 에이전트 협업 대화 시스템

11.3 향후 개발

1. 푸시 알림: 완전한 클라이언트 콜백 지원
2. 더 많은 저장소 백엔드: 데이터베이스 및 분산 저장소 지원
3. 보안 강화: 더 포괄적인 인증 및 권한 부여 메커니즘
4. 프로토콜 업데이트: A2A Protocol의 최신 버전과 보조 맞춤

11.4 개발 권장사항

1. 간단하게 시작: 기본 개념을 이해하기 위해 EchoAgent 사용
2. 상태 관리 이해: ResearcherAgent의 상태 머신 구현 연구
3. 오류 처리 강조: 포괄적인 오류 처리 및 복구 메커니즘 구현
4. 모니터링 및 디버깅: 시스템 모니터링을 위해 OpenTelemetry 활용
5. 테스트 주도: 포괄적인 단위 테스트 및 통합 테스트 작성

이 SDK는 .NET 개발자에게 차세대 지능형 에이전트 시스템을 구축하기 위한 강력하고 유연한 플랫폼을 제공합니다. 명확한 아키텍처와 풍부한 예제를 통해 개발자는 빠르게 시작하고 복잡한 에이전트 간 통신 애플리케이션을 구축할 수 있습니다.