에이전트의 사람이 읽을 수 있는 이름.
마켓플레이스 목록과 클라이언트 UI에 표시됩니다. 짧고 구체적으로 유지하세요——클라이언트는 후보 에이전트를 비교할 때 이를 주요 레이블로 사용합니다.
흔한 실수: "AI Assistant"와 같은 일반적인 이름을 사용하면 라우팅 시스템이 구분할 근거가 없어집니다.
"name": "GeoSpatial 경로 계획 에이전트"
스키마 참조 · 14 fieldsA2A v1.0
A2A Agent Card 스키마, 필드별 상세 설명
Agent Card는 A2A 클라이언트에게 에이전트가 누구인지, 어디로 연락해야 하는지, 무엇을 할 수 있는지, 접근이 어떻게 보호되는지를 알려주는 표준화된 JSON 문서입니다. 이 참조는 모든 v1.0 필드의 타입, 요구 사항, 예제, 그리고 검증기가 가장 자주 발견하는 실수를 다룹니다.
검색이 작동하는 방식
하나의 well-known URL이 모든 A2A 통합을 시작합니다.
A2A 클라이언트는 well-known URI에서 Agent Card를 가져와 자신의 작업에 따라 스킬, 기능, 보안 요구 사항을 평가한 후, 우선 인터페이스——supportedInterfaces의 첫 번째 항목——를 호출합니다. capabilities.extendedAgentCard가 true이면, 인증된 클라이언트는 GetExtendedAgentCard 작업을 통해 더 풍부한 Agent Card를 요청할 수 있습니다.
사양은 /.well-known/agent-card.json을 표준 위치로 등록합니다. 이전 v0.x 배포는 /.well-known/agent.json을 사용했으므로, 우리 검증기는 둘 다 확인합니다.
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}필드 참조
모든 AgentCard 필드와 합격 또는 불합격을 결정하는 세부 사항.
필수 플래그는 공식 사양의 v1.0 protobuf 정의를 따릅니다. 앵커 링크를 통해 각 필드는 이슈, 리뷰, CI 출력에서 인용할 수 있습니다.
에이전트가 무엇을 하는지, 다른 에이전트가 언제 이를 호출해야 하는지.
이는 당신의 에이전트가 작업에 적합한지 판단하는 사람 통합자와 LLM 기반 라우터 모두를 위한 주요 자유 텍스트 신호입니다. 작업 영역, 핵심 능력, 경계를 명시하세요.
흔한 실수: 20자 미만의 한 줄 설명. 라우터는 설명되지 않은 것을 매칭할 수 없습니다.
"description": "고급 경로 계획, 교통 분석, 맞춤형 지도 생성 서비스를 제공합니다."
엔드포인트와 프로토콜 바인딩의 순서가 있는 목록. 첫 번째 항목이 선호됩니다.
v1.0의 새로운 기능: 이전의 최상위 url, preferredTransport, additionalInterfaces 필드를 대체합니다. 각 항목은 자체 url, protocolBinding(JSONRPC, GRPC, HTTP+JSON, 또는 사용자 정의 바인딩 URI), protocolVersion, 그리고 선택적인 테넌트 라우팅 키를 선언합니다——이를 통해 하나의 에이전트가 여러 프로토콜 버전과 전송을 동시에 제공할 수 있습니다.
흔한 실수: 서버가 실제로 해당 URL에서 제공하지 않는 바인딩을 선언하는 것——사양은 각 항목이 정확할 것을 요구합니다.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]누가 에이전트를 운영하는지: 조직과 웹사이트.
마켓플레이스와 기업 감사를 위한 신뢰 신호입니다. v1.0은 name 필드를 organization으로 이름을 변경했습니다. 존재하는 경우 객체 내의 url이 필수입니다.
흔한 실수: 여전히 provider.name(v1.0 이전)을 사용하는 것. v1.0 Agent Card를 읽는 검증기는 이를 인식하지 못합니다.
"provider": {
"organization": "예시 Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}프로토콜이 아닌 에이전트 자체의 버전.
클라이언트가 Agent Card가 실질적으로 변경되었을 때 이를 감지하고 호환성을 재평가할 수 있게 합니다. 일반적으로 semver인 자체 릴리스 방식을 따르세요.
흔한 실수: 이를 A2A 프로토콜 버전과 혼동하는 것——이제 각 supportedInterfaces 항목에 있습니다.
"version": "1.2.0"
에이전트의 사람이 읽을 수 있는 문서로의 링크.
통합자에게 검색 문서에 속하지 않는 전체 API 계약, 속도 제한, 약관을 읽을 수 있는 곳을 제공합니다.
흔한 실수: 기술 문서 대신 마케팅 홈페이지를 가리키는 것.
"documentationUrl": "https://docs.example.com/agent"
프로토콜 기능 플래그: streaming, pushNotifications, extensions, extendedAgentCard.
클라이언트는 선언되지 않은 기능을 호출해서는 안 됩니다——선언되지 않은 스트리밍 호출은 오류를 반환합니다. extendedAgentCard: true는 GetExtendedAgentCard 작업을 통해 더 풍부한 인증된 Agent Card를 제공함을 알립니다. v1.0은 stateTransitionHistory를 제거했습니다.
흔한 실수: 서버에 스트리밍 엔드포인트가 없는데 streaming: true를 선언하는 것. 클라이언트가 이를 호출하면 실패합니다.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}명명된 인증 스킴: API 키, HTTP 인증, OAuth 2.0, OpenID Connect, 또는 상호 TLS.
각 명명된 스킴은 하나의 구체적인 스킴 객체(apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme)를 감쌉니다. 클라이언트는 여기서 인증 방법을 발견합니다——자격 증명 자체는 항상 대역 외에서 얻습니다.
흔한 실수: 실제 API 키나 토큰을 Agent Card에 포함시키는 것. Agent Card는 공개 문서입니다.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}에이전트를 호출하는 데 필요한 선언된 스킴(및 범위).
각 항목은 securitySchemes의 스킴 이름을 필요한 범위에 매핑하며, OpenAPI의 보안 요구 사항 패턴을 반영합니다. 의도적으로 공개된 에이전트의 경우 두 필드를 모두 완전히 생략하세요.
흔한 실수: securitySchemes를 선언했지만 security 요구 사항이 없어, 클라이언트가 인증이 강제되는지 추측하게 만드는 것.
"security": [{ "google": ["openid", "profile", "email"] }]에이전트가 모든 스킬에서 수락하는 미디어 타입.
text/plain, application/json, image/png와 같은 표준 MIME 타입. 개별 스킬은 자체 inputModes로 재정의할 수 있습니다.
흔한 실수: 필드를 생략하는 것. v1.0에서는 필수입니다——클라이언트는 요청을 구성하기 위해 이것이 필요합니다.
"defaultInputModes": ["application/json", "text/plain"]
에이전트가 모든 스킬에서 반환하는 미디어 타입.
호출자에게 텍스트, 구조화된 JSON, 이미지, 또는 파일 중 무엇을 기대해야 하는지 알려줍니다. 스킬은 outputModes로 스킬별로 재정의할 수 있습니다.
흔한 실수: 에이전트가 실제로 구조화된 산출물을 반환하는데 text/plain만 나열하는 것.
"defaultOutputModes": ["application/json", "image/png"]
에이전트가 성공할 가능성이 높은 구체적인 능력.
각 스킬은 id, name, description, tags가 필요합니다. examples, 스킬별 모드, 스킬별 보안은 선택 사항입니다. 스킬은 검색의 단위입니다——라우터는 작업을 이에 대해 매칭하므로, 각각을 단일 작업 경계로 범위를 지정하세요.
흔한 실수: 태그가 없는 스킬. 태그는 v1.0에서 필수가 되었고 스킬 수준 매칭을 주도합니다.
"skills": [{
"id": "route-optimizer-traffic",
"name": "트래픽 인식 경로 최적화 프로그램",
"description": "실시간 교통정보를 활용하여 최적의 주행경로를 계산합니다...",
"tags": ["maps", "routing", "traffic"],
"examples": ["통행료를 피하면서 A에서 B까지의 경로를 계획하세요."]
}]Agent Card가 제공자에 의해 발행되었음을 증명하는 JSON Web Signature.
각 서명은 RFC 8785(JCS)로 정규화된 Agent Card에 대해 계산된 base64url 보호 JWS 헤더와 서명 값을 가집니다. 클라이언트는 공개 웹에서 가져온 Agent Card를 신뢰하기 전에 적어도 하나의 서명을 검증해야 합니다.
흔한 실수: 카드에 서명한 후 아무 필드나 편집하는 것——공백에 영향이 없는 값 변경조차 JWS를 무효화합니다.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]에이전트를 나타내는 아이콘의 URL.
카탈로그와 클라이언트 UI에서 사용됩니다. 안정적인 위치에서 HTTPS를 통해 제공하세요.
흔한 실수: 당신의 목록 뒤에서 변경될 수 있는, 신뢰할 수 없는 다른 도메인의 아이콘에 링크하는 것.
"iconUrl": "https://agent.example.com/icon.png"
버전 마이그레이션
v0.x Agent Card를 A2A v1.0으로 이전하기.
당신의 Agent Card에 여전히 최상위 url이나 preferredTransport가 있다면, v1.0 이전의 것입니다. 검증기는 이 각각을 자동으로 표시합니다.
| v0.x 필드 | v1.0 대체 | 변경 이유 |
|---|---|---|
| url | supportedInterfaces[0].url | 선호되는 엔드포인트는 이제 단순히 첫 번째 인터페이스 항목입니다. |
| preferredTransport | supportedInterfaces[] ordering | 선호도는 별도의 필드 대신 배열 순서로 표현됩니다. |
| additionalInterfaces | supportedInterfaces[] | 모든 인터페이스가 하나의 순서 있는 배열에 존재합니다. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | 각 인터페이스가 자체 프로토콜 버전을 선언하여 다중 버전 지원을 가능하게 합니다. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | capabilities 객체로 이동했습니다. RPC는 GetExtendedAgentCard로 이름이 변경되었습니다. |
| provider.name | provider.organization | 명확성을 위해 이름이 변경되었습니다. |
| capabilities.stateTransitionHistory | — removed | v1.0의 일부가 아닙니다. 필요한 경우 확장으로 동등한 동작을 모델링하세요. |
보일러플레이트
v1.0 Agent Card를 위한 TypeScript 타입.
이 인터페이스를 클라이언트, 서버, 또는 CI 검사에 넣어 타입 안전하게 Agent Card를 파싱하고 생성하세요. 이는 Agent Card가 실제로 게시되는 camelCase JSON 형식으로, 공식 사양 저장소의 protobuf 정의를 반영합니다.
대신 Agent Card를 직접 작성하고 계신가요? 생성기는 정확히 이 형태를 만들어냅니다.
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }무결성
Agent Card 서명, 간단히.
Agent Card는 공개 웹에서 가져오기 때문에, v1.0은 서명을 공식화합니다: Agent Card(signatures 필드와 기본값 제외)는 RFC 8785 JSON Canonicalization으로 정규화된 다음 JWS로 서명됩니다. 클라이언트는 Agent Card에 따라 행동하기 전에 kid/jku 헤더 또는 신뢰할 수 있는 키 저장소를 통해 적어도 하나의 서명을 검증해야 합니다. 여러 서명은 키 순환을 지원합니다.
게시 전 체크리스트
HTTPS를 통해 /.well-known/agent-card.json에서 Agent Card를 제공하세요.
모든 supportedInterfaces 항목에 접근 가능하며 선언된 바인딩을 사용합니다.
스킬에는 필수 태그와 명확한 작업 경계를 가진 설명이 있습니다.
선언된 기능이 서버와 일치합니다——선언되지 않은 기능은 오류를 반환해야 하고, 선언된 기능은 작동해야 합니다.
securitySchemes는 인증 방법을 설명합니다. Agent Card 어디에도 자격 증명이 나타나지 않습니다.
Agent Card 내용이 변경될 때마다 version이 증가합니다.
완전한 v1.0 Agent Card.
OAuth 2.0, 스트리밍, 푸시 알림을 갖춘 고객 지원 에이전트——모든 필수 필드가 존재합니다. 더 많은 패턴은 예제 라이브러리에 있습니다.
{
"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"
]
}
]
}자주 묻는 질문
Agent Card 스키마 관련 자주 묻는 질문
Agent Card가 리뷰를 통과하는지 결정하는 버전 변경, 검색 필드, 게시 세부 사항.
A2A v1.0 Agent Card에서 무엇이 변경되었나요?
v1.0은 url, preferredTransport, additionalInterfaces를 하나의 순서 있는 supportedInterfaces 배열로 통합했으며, 각 항목이 자체 url, protocolBinding, protocolVersion을 선언합니다. supportsAuthenticatedExtendedCard는 capabilities.extendedAgentCard로 이동했고, provider.name은 provider.organization이 되었으며, 스킬 태그가 필수가 되었고, JWS Agent Card 서명은 RFC 8785 정규화로 공식화되었습니다.
Agent Card는 API 스키마와 같은 것인가요?
아니요. Agent Card는 에이전트를 위한 검색 문서입니다. 신원, 인터페이스, 기능, 스킬, 모드, 제공자, 보안 메타데이터를 요약하는 반면, 전체 API 스키마는 상세한 요청과 응답 형태를 설명합니다. 서비스에 대해 README나 OpenAPI 개요가 하는 역할을 합니다: 호출할지, 어떻게 호출할지 결정하기에 충분한 정보입니다.
검색에 가장 중요한 필드는 무엇인가요?
name, description, supportedInterfaces, skills(태그 포함), defaultInputModes, defaultOutputModes, capabilities, provider, 그리고 보안 메타데이터입니다. 라우팅 시스템은 작업을 당신의 description과 스킬 태그에 대해 매칭한 다음, 인터페이스와 기능을 사용하여 실제 호출을 계획합니다.
비공개 스킬이 공개 Agent Card에 나타나야 하나요?
인증되지 않은 검색에 안전한 스킬만 게시하세요. 더 풍부한 비공개 Agent Card가 필요하다면, capabilities.extendedAgentCard를 true로 설정하고 인증된 GetExtendedAgentCard 작업을 통해 민감한 스킬을 노출하세요.
Agent Card는 어디에 게시되나요?
well-known URI인 https://{your-domain}/.well-known/agent-card.json에서 application/a2a+json 콘텐츠 타입으로 게시됩니다(실제로는 application/json도 작동합니다). 이전 구현은 /.well-known/agent.json을 사용했으므로, 전환 기간 동안 둘 다 게시하는 것이 실용적인 선택입니다.
스키마를 활용하기
첫 검증에서 통과하는 Agent Card를 만드세요.
서비스 세부 정보에서 v1.0 형태의 Agent Card를 생성하거나, 기존 Agent Card를 검증기에 붙여넣어 정확히 어떤 필드에 주의가 필요한지 확인하세요.