A2A · AGENT CARD

Agent Card 설계

📋 JSON 전체 스펙 🔧 Skill 정의 💻 FastAPI 구현

Agent Card는 A2A 에이전트의 자기소개서입니다. 어떤 기능을 제공하고, 어떻게 호출하며, 어떤 인증이 필요한지를 기술합니다.

Agent Card란

Agent Card는 /.well-known/agent.json 경로에 노출되는 JSON 문서입니다. Orchestrator Agent가 원격 에이전트를 발견하고 호출하기 전, 이 파일을 먼저 조회해 지원 기능(Skills), 인증 방식, 입출력 모드를 파악합니다.

💡 Robot.txt + OpenAPI Spec의 결합
Agent Card = 에이전트 발견을 위한 robots.txt + 기능 명세를 위한 openapi.json의 역할을 동시에 수행합니다.

전체 Agent Card 예시

json/.well-known/agent.json
{
  "name": "Research Agent",
  "description": "웹 검색과 문서 요약을 전문으로 하는 리서치 에이전트",
  "url": "https://research-agent.example.com",
  "version": "2.1.0",
  "documentationUrl": "https://research-agent.example.com/docs",

  "capabilities": {
    "streaming": true,          // tasks/sendSubscribe 지원
    "pushNotifications": true,  // Webhook 알림 지원
    "stateTransitionHistory": false
  },

  "authentication": {
    "schemes": ["bearer"]  // "none", "bearer", "apiKey", "oauth2"
  },

  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"],

  "skills": [
    {
      "id": "web-search",
      "name": "Web Search",
      "description": "최신 정보를 웹에서 검색하고 요약합니다",
      "tags": ["search", "research", "information"],
      "examples": [
        "2024년 AI 트렌드를 검색해줘",
        "LangGraph 최신 릴리즈 내용 알려줘"
      ],
      "inputModes": ["text/plain"],
      "outputModes": ["text/plain", "application/json"]
    },
    {
      "id": "doc-summary",
      "name": "Document Summarizer",
      "description": "URL 또는 텍스트 문서를 요약합니다",
      "tags": ["summary", "document"],
      "examples": ["https://arxiv.org/abs/2501.xxxxx 요약해줘"],
      "inputModes": ["text/plain", "text/uri-list"],
      "outputModes": ["text/plain"]
    }
  ]
}

Agent Card 필드 레퍼런스

필드타입필수설명
namestring필수에이전트 이름. 사람이 읽는 식별자
descriptionstring권장에이전트 기능 요약. Orchestrator가 라우팅 결정에 사용
urlstring (URL)필수A2A 요청을 수신하는 HTTP 엔드포인트 기본 URL
versionstring권장에이전트 버전. semver 권장
capabilitiesobject필수streaming, pushNotifications, stateTransitionHistory 지원 여부
authenticationobject필수지원하는 인증 방식. schemes 배열
defaultInputModesstring[]필수기본 입력 MIME 타입 목록
defaultOutputModesstring[]필수기본 출력 MIME 타입 목록
skillsSkill[]권장에이전트가 제공하는 특화 기술 목록
documentationUrlstring (URL)선택상세 문서 링크

Skill 필드 레퍼런스

필드타입필수설명
idstring필수Skill 고유 식별자. tasks/send 시 skill 파라미터로 지정
namestring필수사람이 읽는 Skill 이름
descriptionstring권장Skill 상세 설명. Orchestrator LLM이 라우팅에 활용
tagsstring[]선택검색/분류용 태그
examplesstring[]권장이 Skill을 사용하는 예시 요청. Few-shot 힌트 역할
inputModesstring[]선택이 Skill에 특화된 입력 MIME 타입 (기본값 재정의)
outputModesstring[]선택이 Skill에 특화된 출력 MIME 타입 (기본값 재정의)

FastAPI로 Agent Card 노출

pythonagent_card.py — FastAPI 구현
from fastapi import FastAPI
from fastapi.responses import JSONResponse
import os

app = FastAPI()

AGENT_CARD = {
    "name": "Research Agent",
    "description": "웹 검색과 문서 요약 전문 에이전트",
    "url": os.getenv("AGENT_URL", "http://localhost:8000"),
    "version": "1.0.0",
    "capabilities": {
        "streaming": True,
        "pushNotifications": False,
        "stateTransitionHistory": False
    },
    "authentication": {"schemes": ["bearer"]},
    "defaultInputModes": ["text/plain"],
    "defaultOutputModes": ["text/plain"],
    "skills": [
        {
            "id": "web-search",
            "name": "Web Search",
            "description": "웹에서 최신 정보를 검색합니다",
            "examples": ["2025년 AI 동향 검색해줘"],
            "inputModes": ["text/plain"],
            "outputModes": ["text/plain"]
        }
    ]
}

@app.get("/.well-known/agent.json")
async def agent_card():
    return JSONResponse(
        content=AGENT_CARD,
        headers={"Cache-Control": "max-age=3600"}  # 1시간 캐시
    )
↑ 목차