JSON 스키마

Service 리소스를 만들어 Agent Registry에 에이전트 또는 모델 컨텍스트 프로토콜(MCP) 서버를 수동으로 등록할 때는 기능을 선언하는 JSON 구성 파일을 제공합니다. 에이전트 레지스트리는 소비자가 에이전트 A2A 기술 및 MCP 도구를 검색할 수 있도록 색인을 생성하기 전에 오픈소스 사양에 따라 이러한 파일을 검증합니다. 다음 JSON 구조와 예시를 사용하여 에이전트 카드 및 MCP 도구 사양의 형식을 지정하세요.

에이전트 카드 스키마

A2A 호환 에이전트를 등록할 때 agent-card.json 페이로드가 공식 Agent2Agent(A2A) 사양을 준수해야 합니다. 사양 파일의 최대 파일 크기는 150KB입니다. skills 배열 필드는 키워드 검색 색인을 지원합니다.

에이전트 레지스트리는 A2A 에이전트 카드의 버전 1.0 및 0.3를 지원합니다. JSON 스키마 및 필드 정의를 보려면 버전을 선택하세요.

A2A 에이전트 카드의 1.0 버전의 경우 페이로드가 공식 A2A v1.0 사양을 준수해야 합니다. 이 사양에서는 supportedInterfaces 배열 내에서 전송 엔드포인트를 선언합니다.

{
  "name": "string",
  "description": "string",
  "version": "string",
  "supportedInterfaces": [
    {
      "url": "string",
      "protocolBinding": "string",
      "protocolVersion": "string",
      "tenant": "string"
    }
  ],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ],
  "skills": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "examples": [
        "string"
      ]
    }
  ]
}

필드 정의

  • name: 인간이 읽을 수 있는 에이전트 이름입니다.
  • description: 에이전트의 목적에 대한 대략적인 요약입니다.
  • version: 에이전트 버전입니다(예: 1.0.0).
  • supportedInterfaces: 지원되는 전송 및 URL 조합의 배열입니다. 각 인터페이스에는 다음이 포함됩니다.
    • url: 이 인터페이스에 도달하는 엔드포인트 URL입니다.
    • protocolBinding: 이 URL에서 지원되는 프로토콜 바인딩입니다(예: HTTP+JSON, JSONRPC 또는 GRPC).
    • protocolVersion: 이 인터페이스가 노출하는 A2A 프로토콜 버전입니다(예: 1.0.0).
    • tenant(선택사항): 에이전트 소유자의 식별자입니다.
  • capabilities(선택사항): 다음과 같은 지원되는 운영 기능을 지정합니다.
    • extensions(선택사항): 프로토콜 확장 프로그램의 배열입니다.
    • streaming(선택사항): 에이전트가 스트리밍 응답을 지원하는지 여부를 나타내는 불리언입니다.
    • pushNotifications(선택사항): 작업 업데이트에 푸시 알림이 지원되는지 여부를 나타내는 불리언입니다.
    • extendedAgentCard(선택사항): 인증 시 에이전트가 확장된 에이전트 카드를 제공하는지 여부를 나타내는 불리언입니다.
  • defaultInputModes(선택사항): 입력으로 허용되는 MIME 유형의 배열입니다.
  • defaultOutputModes(선택사항): 출력으로 생성된 MIME 유형의 배열입니다.
  • skills: 에이전트가 보유한 설명적인 A2A 기술의 배열입니다.
    • id: A2A 기술의 고유한 프로그래매틱 식별자입니다.
    • name: 인간이 읽을 수 있는 A2A 기술 이름입니다.
    • description: A2A 기술이 수행하는 작업에 대한 자세한 설명입니다.
    • tags: A2A 기술을 분류하는 데 사용되는 키워드 문자열 배열입니다.
    • examples: 이 A2A 기술이 처리하는 예시 프롬프트 또는 시나리오의 배열입니다.

버전 0.3

A2A 에이전트 카드의 버전 0.3의 경우 페이로드가 v0.3.0 사양을 준수해야 합니다. 이 사양에서 기본 추론 URL과 프로토콜 버전은 최상위 필드로 선언됩니다.

{
  "name": "string",
  "description": "string",
  "version": "string",
  "protocolVersion": "string",
  "url": "string",
  "skills": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "examples": [
        "string"
      ]
    }
  ],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

필드 정의

  • name: 인간이 읽을 수 있는 에이전트 이름입니다.
  • description: 에이전트의 목적에 대한 대략적인 요약입니다.
  • version: 에이전트 버전입니다(예: 1.0.2).
  • protocolVersion: 에이전트가 구현하는 A2A 프로토콜의 버전입니다. 버전 1.0에서는 이 최상위 필드를 지원 중단하므로 이 스키마의 값은 0.3 또는 0.3 패치 버전(예: 0.3.1)이어야 합니다.
  • url: 에이전트에 연결할 수 있는 엔드포인트 URL입니다.
  • capabilities(선택사항): 에이전트가 지원하는 운영 기능(예: streaming, pushNotifications, stateTransitionHistory)을 지정하는 객체입니다.
  • defaultInputModes(선택사항): 에이전트가 입력으로 허용하는 기본 MIME 유형을 정의하는 문자열 배열입니다(예: ["text/plain"]).
  • defaultOutputModes(선택사항): 에이전트가 출력으로 생성하는 기본 MIME 유형을 정의하는 문자열 배열입니다(예: ["text/plain"]).
  • skills: 에이전트가 보유한 설명적인 A2A 기술의 배열입니다.
    • id: A2A 기술의 고유한 프로그래매틱 식별자입니다.
    • name: 인간이 읽을 수 있는 A2A 기술 이름입니다.
    • description: A2A 기술이 수행하는 작업에 대한 자세한 설명입니다.
    • tags: A2A 기술을 분류하는 데 사용되는 키워드 문자열 배열입니다.
    • examples: 이 A2A 기술이 처리하는 예시 프롬프트 또는 시나리오의 배열입니다.

MCP 도구 스키마

MCP 서버를 등록할 때 toolspec.json 페이로드에 MCP Tool 객체 스키마를 준수하는 도구 목록이 포함되어야 합니다.

예상 페이로드는 표준 MCP 도구 또는 목록 요청에서 반환하는 것과 정확히 동일한 단일 tools 필드가 있는 JSON 객체입니다. 이 사양 파일의 최대 파일 크기는 150KB입니다.

{
  "tools": [
    {
      "name": "string",
      "description": "string",
      "inputSchema": {
        "type": "object",
        "properties": {}
      },
      "annotations": {
        "title": "string",
        "readOnlyHint": false,
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true
      },
      "_meta": {
        "com.googleapis.iap/PolicyHints": {
          "authorization": {
            "toolDisabled": false,
            "hitlMode": "HITL_MODE_ALWAYS"
          }
        }
      }
    }
  ]
}

필드 정의

  • tools: 서버에서 제공하는 도구 배열:

    • name: 도구의 프로그래매틱 식별자입니다.
    • description: 인간이 읽을 수 있는 도구의 목적에 대한 설명입니다.
    • inputSchema: 도구에 필요한 매개변수를 정의하는 JSON 스키마 객체입니다.
    • annotations: 조정자 에이전트가 도구와 상호작용하는 방식을 안내하는 동작 힌트입니다.

      • title: 인간이 읽을 수 있는 도구 제목입니다.
      • readOnlyHint: true인 경우 도구는 데이터만 검색하고 환경을 수정하지 않습니다. 기본값은 false입니다.
      • destructiveHint: true인 경우 도구는 영구적인 변경을 일으킬 수 있는 작업을 수행합니다. 기본값은 true입니다.
      • idempotentHint: true인 경우 도구를 반복적으로 호출해도 추가 효과가 없습니다. 기본값은 false입니다.
      • openWorldHint: true인 경우 도구가 외부 시스템과 상호작용합니다. 기본값은 true입니다.
    • _meta(선택사항): 구조화된 메타데이터를 도구에 연결하기 위한 모델 컨텍스트 프로토콜(MCP) 사양을 준수하는 프로토콜 수준 메타데이터입니다. 표준 annotations는 사전 정의된 힌트로 제한된 폐쇄형 객체이므로 _meta는 표준 MCP 클라이언트와의 호환성을 유지하면서 추가 메타데이터를 위한 확장 가능한 컨테이너를 제공합니다.

      제공업체 간의 이름 충돌을 방지하기 위해 _meta 내의 최상위 키는 리버스 도메인 표기법을 사용합니다. 에이전트 레지스트리는 apphub.googleapis.com/McpServer 확장 메타데이터 스키마에 대해 _meta를 검증하고 다음 네임스페이스를 지원합니다.

      • com.googleapis.iap/PolicyHints(선택사항): 도구 승인 및 휴먼인더루프(HITL) 제어를 시행하기 위해 IAP(Identity-Aware Proxy) 및 Agent Gateway에서 평가하는 정책 힌트입니다.

        • authorization(선택사항): 도구의 승인 구성:
          • toolDisabled(선택사항): 호출에 도구가 사용 중지되었는지 여부를 나타내는 불리언입니다. 도구를 사용 중지하려면 true로 설정합니다. 기본값은 false입니다. 즉, 이 필드를 생략하면 도구가 사용 설정됩니다.
          • hitlMode(선택사항): 도구의 휴먼인더루프(HITL) 실행 모드를 지정하는 문자열입니다.
            • HITL_MODE_UNSPECIFIED: HITL 모드가 지정되지 않았습니다.
            • HITL_MODE_DISABLED: 도구가 대화형 사용자 승인 없이 실행됩니다.
            • HITL_MODE_ALWAYS: 도구를 실행하기 전에 항상 대화형 인간 승인이 필요합니다.
            • HITL_MODE_IF_UNSAFE: 작업이 안전하지 않은 것으로 평가되는 경우에만 도구에 대화형 사용자 승인이 필요합니다.