복사해서 바로 쓰는 JSON 템플릿 6개 · A2A v1.0

A2A Agent Card 예제

실용적인 A2A v1.0 템플릿을 둘러보고, 설계 결정을 이해한 다음, 자신의 에이전트에 맞게 예제를 조정하세요.

템플릿 둘러보기생성기 열기

공개 에이전트 검색

이 예제들을 사용하여 다른 A2A 클라이언트가 당신의 에이전트가 작업을 완료할 수 있는지 결정하기 전에 가져올 JSON의 형태를 만드세요.

마켓플레이스 제출

제공자, 스킬, 태그, 기능, 보안 메타데이터를 조정하여 검토자가 에이전트가 무엇을 하는지, 누가 운영하는지 이해할 수 있게 하세요.

내부 에이전트 카탈로그

팀이 워크플로우에 통합하기 전에 내부 에이전트 전반에 걸쳐 엔드포인트, 인증, 스킬 설명을 표준화하세요.

JSON 템플릿

지원, 예약, 쇼핑, 코딩, 리서치, 워크플로우 에이전트를 위한 예제 Agent Card.

템플릿 검증하기
필터

고객 지원 에이전트

제품 질문, 주문 조회, 반품, 에스컬레이션 인계를 처리합니다.

이렇게 만들어진 이유

  • OAuth 2.0 클라이언트 자격 증명이 주문 데이터를 보호합니다: Agent Card는 토큰 URL과 스코프를 선언하여 클라이언트가 대역 외 문서 없이 인증할 수 있게 합니다.
  • 지원 대화는 오래 지속되고 해결 업데이트가 비동기적으로 도착하기 때문에 streaming과 pushNotifications가 모두 true입니다.
  • 단일 스킬은 모호한 "고객 지원" 설명 대신 하나의 작업 경계(분류, 해결, 에스컬레이션)로 범위가 지정되어 있어 라우터가 정확하게 매칭할 수 있습니다.
customer-support.json
{
  "name": "고객 지원 에이전트",
  "description": "고객 지원 질문에 답변하고, 주문 컨텍스트를 검색하고, 해결되지 않은 문제를 인간 팀에 에스컬레이션합니다.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/customer-support",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "예제 주식회사",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "resolve-customer-support-request",
      "name": "고객 지원 요청 해결",
      "description": "고객 지원 요청을 분류하고, 필요한 상황을 수집하고, 해결 방법을 제안하고, 신뢰도가 낮을 ​​경우 에스컬레이션합니다.",
      "tags": [
        "support",
        "orders",
        "returns"
      ],
      "examples": [
        "주문한 상품을 반품할 수 있도록 도와주세요."
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

예약 에이전트

예약 가능한 시간대를 찾고 예약 확인을 준비합니다.

이렇게 만들어진 이유

  • 여기서는 헤더의 API 키만으로 충분합니다: 예약은 테넌트 범위이지만 OAuth가 해결하는 위임된 사용자 동의 문제는 수반하지 않습니다.
  • defaultOutputModes는 application/json만 있어, 호출자가 산문이 아닌 구조화된 예약 제안을 받는다는 것을 나타냅니다.
  • pushNotifications가 true이므로 클라이언트가 폴링하지 않아도 슬롯 보유 백엔드가 확정된 후 에이전트가 예약을 확인할 수 있습니다.
booking.json
{
  "name": "예약 에이전트",
  "description": "가용성을 검색하고 예약 옵션을 제안하며 승인을 위해 약속 예약을 준비합니다.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/booking",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "예제 주식회사",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "application/json"
  ],
  "skills": [
    {
      "id": "find-and-prepare-booking",
      "name": "예약 찾기 및 준비",
      "description": "리소스 가용성을 확인하고, 예약 창을 비교하고, 체계적인 예약 제안을 반환합니다.",
      "tags": [
        "booking",
        "calendar",
        "availability"
      ],
      "examples": [
        "내일 오후에 30분 약속을 잡아보세요."
      ]
    }
  ],
  "securitySchemes": {
    "apiKey": {
      "apiKeySecurityScheme": {
        "location": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ]
}

쇼핑 에이전트

제품, 재고, 가격, 구매 제약 조건을 비교합니다.

이렇게 만들어진 이유

  • 순위가 매겨진 추천은 계산되는 대로 스트리밍되므로 streaming은 true이지만 pushNotifications는 false로 유지됩니다——응답이 완료된 후에는 아무 일도 일어나지 않습니다.
  • 스킬 설명은 트레이드오프와 근거를 반환하기로 약속하는데, 이는 이 에이전트가 단순히 제품을 나열하는 것이 아니라 순위를 설명한다는 것을 오케스트레이터에 알립니다.
  • OAuth 스코프가 구매 관련 데이터를 게이트합니다. 공개 쇼핑 데모는 보안을 완전히 생략해도 유효한 Agent Card로 남을 수 있습니다.
shopping.json
{
  "name": "쇼핑 에이전트",
  "description": "사용자 제약 조건과 제품을 비교하고 절충 사항을 고려하여 순위가 매겨진 구매 옵션을 반환합니다.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/shopping",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "예제 주식회사",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "application/json"
  ],
  "skills": [
    {
      "id": "compare-shopping-options",
      "name": "쇼핑 옵션 비교",
      "description": "후보 제품을 평가하고, 제약 조건을 기준으로 필터링하고, 근거와 함께 순위가 매겨진 권장 사항을 반환합니다.",
      "tags": [
        "shopping",
        "commerce",
        "recommendations"
      ],
      "examples": [
        "1,200달러 미만의 경량 노트북을 비교해 보세요."
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/shopping/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

코딩 에이전트

코딩 작업을 검토하고, 패치를 제안하고, 구현 결정을 설명합니다.

이렇게 만들어진 이유

  • extendedAgentCard는 true입니다: 공개 Agent Card는 일반적인 "코드 변경 구현" 스킬을 나열하며, 저장소별 스킬은 GetExtendedAgentCard를 통해 인증된 클라이언트에게만 공개됩니다.
  • 에이전트가 사람이 읽을 수 있는 설명과 기계가 적용 가능한 패치를 함께 반환하기 때문에 text/plain과 application/json 출력이 모두 선언되어 있습니다.
  • 긴 컴파일-테스트 루프에는 스트리밍이 중요합니다. 클라이언트는 조용한 몇 분간의 호출 대신 중간 진행 상황을 볼 수 있습니다.
coding.json
{
  "name": "코딩 에이전트",
  "description": "코드 분석, 변경 제안, 구현 노트 반환을 통해 소프트웨어 엔지니어링 작업을 지원합니다.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/coding",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "예제 주식회사",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": true
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "implement-code-change",
      "name": "코드 변경 구현",
      "description": "코딩 요청을 읽고, 관련 파일을 검사하고, 패치 제안을 반환하고, 확인 단계를 요약합니다.",
      "tags": [
        "coding",
        "review",
        "patches"
      ],
      "examples": [
        "사용자 API에 페이지 매김을 추가합니다."
      ]
    }
  ],
  "securitySchemes": {
    "apiKey": {
      "apiKeySecurityScheme": {
        "location": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ]
}

리서치 에이전트

출처를 수집하고, 증거를 추출하고, 구조화된 리서치 노트를 반환합니다.

이렇게 만들어진 이유

  • securitySchemes가 전혀 없습니다: 엔드포인트는 의도적으로 공개되어 있으며, 필드를 생략하는 것이 그것을 말하는 올바른 방법입니다——빈 스킴 맵은 모호할 것입니다.
  • 리서치 요약은 자연어 질문에서 시작하기 때문에 입력은 text/plain만 있습니다. 구조화된 출력은 application/json 노트로 도착합니다.
  • 이것은 최소한으로 유용한 v1.0 Agent Card입니다: 신원, 하나의 인터페이스, 기능, 모드, 그리고 태그가 잘 붙은 하나의 스킬.
research.json
{
  "name": "리서치 에이전트",
  "description": "원본 자료를 수집하고, 증거를 추출하고, 인용이 포함된 구조화된 연구 노트를 생성합니다.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/research",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "예제 주식회사",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "prepare-research-brief",
      "name": "연구 개요 준비",
      "description": "승인된 출처를 검색하고, 주장과 증거를 추출하고, 간결한 연구 개요를 반환합니다.",
      "tags": [
        "research",
        "evidence",
        "citations"
      ],
      "examples": [
        "재생 가능 에너지 정책에 대한 인용 개요를 준비합니다."
      ]
    }
  ]
}

내부 워크플로우 에이전트

승인, 상태 확인, 후방 업무 워크플로우 업데이트를 조정합니다.

이렇게 만들어진 이유

  • application/json이 유일한 입력 및 출력 모드입니다: 이 에이전트는 다른 시스템에 의해 호출되며 사람이 산문을 입력하는 경우는 결코 없습니다.
  • OAuth 2.0과 extendedAgentCard의 조합은 기업 감사에 적합합니다——보안 팀은 인증 요구 사항을 공개적으로 볼 수 있으며 민감한 워크플로우 스킬은 인증 뒤에 유지됩니다.
  • 승인 체인은 몇 시간 또는 며칠이 걸리기 때문에 pushNotifications는 필수적입니다. 웹훅이 상태 변화에 대한 폴링을 대체합니다.
internal-workflow.json
{
  "name": "내부 워크플로우 에이전트",
  "description": "내부 승인을 조정하고, 시스템 상태를 확인하고, 운영팀을 위한 워크플로 업데이트를 준비합니다.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/workflow",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "예제 주식회사",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": true,
    "extendedAgentCard": true
  },
  "defaultInputModes": [
    "application/json"
  ],
  "defaultOutputModes": [
    "application/json"
  ],
  "skills": [
    {
      "id": "coordinate-internal-workflow",
      "name": "내부 워크플로우 조정",
      "description": "워크플로 의도를 수신하고, 정책 요구 사항을 확인하고, 승인을 수집하고, 최종 상태를 보고합니다.",
      "tags": [
        "workflow",
        "operations",
        "approval"
      ],
      "examples": [
        "급여 업데이트 배포에 대한 승인을 요청합니다."
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/workflow/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

자신 있게 조정하기

Agent Card 예제를 조정하는 방법

각 Agent Card 예제는 복사하기에 충분할 만큼 의도적으로 완전하지만, Agent Card를 변경 없이 그대로 게시해서는 안 됩니다. 이를 여러분 자신의 A2A 서버를 위한 필드 맵으로 취급하세요: 신원, 엔드포인트, 제공자, 인증, 기능, 모드, 스킬 세부 사항을 프로덕션 값으로 교체하세요.

가장 뛰어난 Agent Card는 평이한 언어와 기계가 읽을 수 있는 메타데이터로 에이전트의 작업 경계를 설명합니다. 클라이언트는 에이전트가 무엇을 할 수 있고 할 수 없는지, 어떤 URL을 호출해야 하는지, 자격 증명이 필요한지 판단할 수 있어야 합니다.

게시하기 전에

모든 example.com URL을 배포된 A2A 엔드포인트와 제공자 웹사이트로 교체하세요.

실제 작업 경계에 맞게 스킬 이름, 설명, 태그(v1.0에서 필수), 예제를 다시 작성하세요.

provider.organization을 설정하고 Agent Card 내용이 변경될 때마다 최상위 version을 올리세요.

엔드포인트가 의도적으로 공개된 경우에만 인증 필드를 제거하세요.

defaultInputModes와 defaultOutputModes를 서버가 실제로 수락하고 반환하는 것과 일치시키세요.

최종 JSON을 검증하고 서비스 도메인의 /.well-known/agent-card.json에 게시하세요.

예제 검증하기스키마 가이드 읽기

구축할 준비가 되었습니다

예제로 시작한 다음 자신만의 것으로 만드세요.

Agent Card 생성기에서 아무 패턴이나 열어 JSON을 검토하고 게시하기 전에 검증하세요.

Agent Card 생성기 열기Agent Card 검증하기