A2A 프로토콜 계약

A2A 프로토콜 계약은 Amazon Bedrock AgentCore 런타임에서 agent-to-agent 통신을 구현하기 위한 요구 사항을 정의합니다. 이 계약은 A2A 서버가 구현해야 하는 기술 요구 사항, 엔드포인트 및 통신 패턴을 지정합니다.

예제 코드는 AgentCore 런타임에서 A2A 서버 배포를 참조하세요.

프로토콜 구현 요구 사항

A2A 서버는 다음과 같은 특정 프로토콜 요구 사항을 구현해야 합니다.

컨테이너 요구 사항

A2A 서버는 다음 사양을 충족하는 컨테이너화된 애플리케이션으로 배포되어야 합니다.

경로 요구 사항

/ - POST

용도

JSON-RPC 2.0 메시지를 수신하고 에이전트의 기능을 통해 이를 처리하고 A2A 프로토콜 메시지를 사용하여 InvokeAgentRuntime API 페이로드를 완전히 전달합니다.

사용 사례

루트 엔드포인트는 다음과 같은 몇 가지 주요 용도로 사용됩니다.

요청 형식

A2A 서버는 JSON-RPC 2.0 형식의 요청을 예상합니다.

Content-Type: application/json
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Your message content here"
        }
      ],
      "messageId": "unique-message-id"
    }
  }
}

응답 형식

A2A 서버는 작업 및 아티팩트가 포함된 JSON-RPC 2.0 형식의 응답으로 응답합니다.

Content-Type: application/json
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "artifacts": [
      {
        "artifactId": "unique-artifact-id",
        "name": "agent_response",
        "parts": [
          {
            "kind": "text",
            "text": "Agent response content"
          }
        ]
      }
    ]
  }
}

/.well-known/agent-card.json - GET

용도

에이전트 검색 및 기능 광고를 위한 에이전트 카드 메타데이터 제공

사용 사례

에이전트 카드 엔드포인트는 다음과 같은 몇 가지 주요 용도로 사용됩니다.

응답 형식

에이전트의 자격 증명과 기능을 설명하는 JSON 메타데이터를 반환합니다.

Content-Type: application/json
{
  "name": "Agent Name",
  "description": "Agent description and purpose",
  "version": "1.0.0",
  "url": "https://bedrock-agentcore.region.amazonaws.com/runtimes/agent-arn/invocations/",
  "protocolVersion": "0.3.0",
  "preferredTransport": "JSONRPC",
  "capabilities": {
    "streaming": true
  },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "skills": [
    {
      "id": "skill-id",
      "name": "Skill Name",
      "description": "Skill description and capabilities",
      "tags": []
    }
  ]
}

/ping - GET

용도

A2A 서버가 작동하고 요청을 처리할 준비가 되었는지 확인합니다.

응답 형식

에이전트의 상태를 나타내는 상태 코드를 반환합니다.

{
  "status": "Healthy"
}

status는 필수이며 Healthy 또는 중 하나입니다HealthyBusy. 상태가 인 동안 HealthyBusy런타임 세션은 활성 상태로 유지됩니다.

선택적 time_of_last_update 필드(초 단위의 Unix 타임스탬프)를 포함하여가 status 마지막으로 변경된 시기를 보고할 수 있습니다.

인증 요구 사항

A2A 서버는 여러 인증 메커니즘을 지원합니다.

OAuth 2.0 베어러 토큰

A2A 클라이언트 인증의 경우 요청 헤더에 베어러 토큰을 포함합니다.

Authorization: Bearer <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>

SigV4 인증

Standard AWS SigV4 인증은 프로그래밍 방식 액세스에도 지원됩니다.

오류 처리

A2A 서버는 프로토콜 준수를 유지하기 위해 HTTP 200 상태 코드와 함께 오류를 표준 JSON-RPC 2.0 오류 응답으로 반환합니다.

오류 응답 예제:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32052,
    "message": "Validation error - Invalid request data"
  }
}

OAuth 인증 응답

OAuth로 구성된 에이전트는 RFC 6749(OAuth 2.0) 인증 표준을 따릅니다. 인증이 누락된 경우 서비스는 클라이언트가 GetRuntimeProtectedResourceMetadata API를 통해 권한 부여 서버 엔드포인트를 검색할 수 있도록 (RFC 7235에 따라) WWW-Authenticate 헤더와 함께 401 무단 응답을 반환합니다.

401 무단 - 인증 누락

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"