iop/agent-spec/input/a2a-json-rpc-surface.md

spec_doc_type	spec_id	status	source_evidence
spec	input/a2a-json-rpc-surface	부분	type path notes contract agent-contract/outer/a2a-json-rpc-api.md A2A JSON-RPC 외부 HTTP 계약 type path notes code apps/edge/internal/input/a2a/server.go A2A HTTP server, JSON-RPC method dispatch, auth, SubmitRun 연동 type path notes code apps/edge/internal/input/a2a/task_store.go in-memory task store와 RunEvent drain type path notes code apps/edge/internal/input/a2a/types.go JSON-RPC envelope와 A2A task/message/artifact DTO type path notes test apps/edge/internal/input/a2a/server_test.go A2A handler 동작 검증 type path notes test apps/edge/internal/input/a2a/task_store_test.go task store drain 상태 검증

스펙: A2A JSON-RPC 입력 표면

목적

Edge가 A2A JSON-RPC 요청을 받아 내부 adapter + target 실행으로 넘기는 현재 MVP 동작을 설명한다.

기능 목록

기능	설명
A2A HTTP server	a2a.enabled=true이면 Edge input manager가 A2A HTTP server를 시작한다. 기본 RPC path는 /a2a다.
agent card	GET /.well-known/agent.json으로 현재 agent card를 제공한다.
bearer auth	a2a.bearer_token이 있으면 matching bearer authorization header를 요구한다.
JSON-RPC method 처리	JSON-RPC 2.0 envelope를 검증하고 message/send, tasks/get, tasks/cancel만 처리한다.
message/send 실행	text parts를 newline으로 이어 prompt를 만들고 Edge service SubmitRun을 호출한다.
blocking task	configuration.blocking이 true이거나 생략되면 HTTP 요청 안에서 run stream을 drain한 뒤 최종 task snapshot을 반환한다.
background task	non-blocking 요청은 working snapshot을 먼저 반환하고 background goroutine이 run stream을 drain한다.
task 조회	tasks/get이 process-local task store의 task snapshot을 반환한다.
task 취소	tasks/cancel은 working task에 대해 service CancelRun을 호출한다.
task artifact	completed task는 adapter output delta를 text artifact 하나에 누적한다.

범위

• 포함: A2A HTTP listener, agent card, bearer auth, JSON-RPC envelope, message text extraction, blocking/background task drain, task get/cancel.
• 제외: A2A streaming, durable task persistence, OpenAI-compatible chat 대체 표면, provider-pool model catalog route, full A2A spec 호환.

주요 흐름

sequenceDiagram
  participant Caller
  participant A2A as A2A server
  participant Service as Edge service
  participant Store as TaskStore

  Caller->>A2A: message/send(text parts)
  A2A->>Service: SubmitRun(prompt)
  Service-->>A2A: run id + stream
  A2A->>Store: task working 저장
  alt blocking
    A2A->>A2A: run stream drain
    A2A-->>Caller: final task snapshot
  else non-blocking
    A2A-->>Caller: working task snapshot
    A2A->>A2A: background drain
  end

계약

• iop.a2a-json-rpc-api: agent-contract/outer/a2a-json-rpc-api.md
• 내부 실행 wire: agent-contract/inner/edge-node-runtime-wire.md

설정/데이터/이벤트

• configs/edge.yaml의 a2a 섹션이 listener, path, node ref, adapter, target, session id, timeout, bearer token을 제공한다.
• A2A run metadata에는 현재 source=a2a와 blocking=true 또는 blocking=false가 들어간다. 이 metadata는 OpenAI-compatible request metadata 계약과 별개인 내부 run metadata다.
• TaskStore는 run event delta, complete, error, cancelled와 node disconnect를 관찰해 task status를 갱신한다.

검증

• go test ./apps/edge/internal/input/a2a
• go test ./apps/edge/internal/input
• go test ./apps/edge/internal/service

한계와 주의사항

• task state는 메모리에만 있고 Edge 재시작 시 사라진다.
• agent card URL은 현재 listen/path 기반 단순 표현이다. reverse proxy/public URL 계약은 별도로 확정해야 한다.
• A2A 표면은 현재 configured adapter/target으로만 run을 보낸다. request별 provider-pool model route는 이 spec의 현재 동작이 아니다.
• streaming capability는 agent card에서 false다.
• OpenAI-compatible chat/completions 대체 표면으로 쓰지 않는다.

변경 기록

• 2026-07-07: 현재 코드와 A2A 계약 기준으로 bootstrap spec 작성.
• 2026-07-07: 기능 목록 중심으로 축소하고 주요 흐름을 Mermaid sequence diagram으로 정리.