Service 리소스를 만들어 Agent Registry에 에이전트 또는 모델 컨텍스트 프로토콜(MCP) 서버를 수동으로 등록할 때는 기능을 선언하는 JSON 구성 파일을 제공합니다. 에이전트 레지스트리는 소비자가 에이전트 A2A 기술 및 MCP 도구를 검색할 수 있도록 색인을 생성하기 전에 오픈소스 사양에 따라 이러한 파일을 검증합니다. 다음 JSON 구조와 예시를 사용하여 에이전트 카드 및 MCP 도구 사양의 형식을 지정하세요.
에이전트 카드 스키마
A2A 호환 에이전트를 등록할 때 agent-card.json 페이로드가 공식 Agent2Agent(A2A) 사양을 준수해야 합니다.
사양 파일의 최대 파일 크기는 150KB입니다.
skills 배열 필드는 키워드 검색 색인을 지원합니다.
에이전트 레지스트리는 A2A 에이전트 카드의 버전 1.0 및 0.3를 지원합니다. JSON 스키마 및 필드 정의를 보려면 버전을 선택하세요.
버전 1.0(권장)
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: 작업이 안전하지 않은 것으로 평가되는 경우에만 도구에 대화형 사용자 승인이 필요합니다.