A2A 프로토콜
A2A 프로토콜 (A2A Protocol)
Google의 Agent-to-Agent (A2A) 프로토콜로 Docker Agent 에이전트를 노출해서 다른 에이전트 프레임워크와 상호운용해요.
출처: 문서
본문
개요 (Overview)
docker agent serve a2a 명령은 A2A 프로토콜로 에이전트를 노출하는 A2A 서버를 시작해요. 이를 통해 Docker Agent와 A2A를 지원하는 다른 에이전트 프레임워크 간의 통신이 가능해져요.
Warning 초기 지원 (Early support) A2A 지원은 동작하지만 아직 진화 중이에요. 도구 호출, 아티팩트, 메모리 기능은 A2A 통합이 제한적이에요. 아래 limitations 참고.
사용법 (Usage)
# Start A2A server for an agent
$ docker agent serve a2a ./agent.yaml
# Specify a custom address
$ docker agent serve a2a ./agent.yaml --listen 127.0.0.1:9000
# Use an agent from an OCI registry
$ docker agent serve a2a myorg/agent:tag
플래그 (Flags)
| Flag | Default | Description |
|---|---|---|
-l, --listen <addr> |
127.0.0.1:8082 | 수신할 주소 |
-a, --agent <name> |
(first agent) | 구성에 여러 에이전트가 있을 때 노출할 에이전트 이름. 팀의 첫 에이전트가 기본값. |
-s, --session-db <path> |
<data-dir>/session.db |
SQLite 세션 데이터베이스 경로 |
--working-dir <path> |
current dir | 에이전트가 실행되는 작업 디렉터리 |
--env-from-file <file> |
(none) | .env 파일에서 추가 환경 변수 로드 (반복 가능) |
--models-gateway <url> |
(none) | 모든 제공자 트래픽을 모델 게이트웨이 URL로 라우팅 |
--code-mode-tools |
false | 실행할 JavaScript 스니펫을 받는 단일 "code" toolset으로 도구 노출 |
--hook-pre-tool-use <cmd> |
(none) | pre-tool-use 훅 추가 (반복 가능). Hooks 참고 |
--hook-post-tool-use <cmd> |
(none) | post-tool-use 훅 추가 (반복 가능) |
--hook-session-start <cmd> |
(none) | session-start 훅 추가 (반복 가능) |
--hook-session-end <cmd> |
(none) | session-end 훅 추가 (반복 가능) |
--hook-on-user-input <cmd> |
(none) | on-user-input 훅 추가 (반복 가능) |
--hook-stop <cmd> |
(none) | 모델이 응답을 마칠 때 발동하는 stop 훅 추가 (반복 가능) |
--auth-token <token> |
(none) | agent-card 및 호출 요청에 필요한 Bearer 토큰 |
--cors-origin <origins> |
(none) | 허용된 브라우저 origin, 쉼표 구분; 비어 있으면 CORS 비활성화 |
--insecure-no-auth |
false | 인증 없는 비루프백 리스너 허용 (안전하지 않음) |
--safety <policy> |
restricted | 도구 안전 정책; autonomous 는 이 명시적 CLI 플래그로만 허용 |
인증과 네트워크 노출 (Authentication and network exposure)
루프백 리스너는 인증 없이 실행될 수 있어요. 비루프백 리스너는 --insecure-no-auth 가 노출을 명시적으로 인정하지 않는 한 --auth-token 이 필요해요. 클라이언트는 agent-card 발견과 JSON-RPC 호출 모두에 Authorization: Bearer *** 을 보내야 해요. 브라우저 접근은 --cors-origin 으로 구성하며, 쉼표로 구분된 리터럴 origin 또는 ~ 접두사 정규식을 받고 일치하는 origin에만 자격 증명을 허용해요.
$ docker agent serve a2a ./agent.yaml --auth-token "$A2A_TOKEN" \
--cors-origin http://localhost:3000
도구 안전과 마이그레이션 (Tool safety and migration)
A2A 세션은 기본적으로 restricted 도구 안전 정책을 사용해요. 우선순위는 --safety 플래그, 에이전트 YAML, 런타임 YAML 순이에요. YAML은 strict, balanced, restricted 를 선택할 수 있고, safety: autonomous 는 시작을 멈추고 운영자에게 --safety autonomous 를 안내해요. 그 CLI 플래그만이 autonomous 도구 실행에 대한 유일한 의도적인 선택(opt-in)이에요.
기존 배포는 업그레이드 전에 명시적 정책을 선택해야 해요. 마이그레이션 027은 기존 세션을 run 으로 표시하므로 /invoke 를 통해 재개할 수 없어요; 클라이언트는 새 A2A 컨텍스트를 시작해야 해요. 다른 세션과 충돌하는 A2A 컨텍스트 ID는 그 세션을 변경하지 않고 거부돼요.
마이그레이션 027 이전의 바이너리로 다운그레이드하면 세션 데이터베이스가 더 새로운 스키마이므로(ErrNewerDatabase) 실패해요. 이전 데이터베이스를 복원하거나, 마이그레이션을 포함한 바이너리를 사용하세요. 마이그레이션 카탈로그 항목을 제거하지 않고 변경을 되돌려요.
기능 (Features)
- 자동 포트 선택 — 지정하지 않으면 사용 가능한 포트 선택
- Agent card — 표준 A2A 에이전트 메타데이터 제공
- 전체 Docker Agent 기능 — 모든 도구, 모델, 게이트웨이 기능 지원
- 다중 소스 — 파일이나 OCI 레지스트리에서 에이전트 로드
Tip 참고 (See also) MCP로 에이전트를 노출하려면 MCP Mode 참고. stdio 기반 통합은 ACP 참고. HTTP API는 API Server 참고.
현재 제한 사항 (Current Limitations)
- 도구 호출은 내부적으로 처리되며 별도의 A2A 이벤트로 노출되지 않음
- A2A 아티팩트 지원은 아직 통합되지 않음
- A2A 메모리 기능은 아직 통합되지 않음
- 다중 에이전트(하위 에이전트) 시나리오는 더 작업이 필요함