# A2A JSON-RPC API Contract

## 계약 메타

- id: `iop.a2a-json-rpc-api`
- boundary: `outer`
- status: active-mvp
- 원본 경로:
  - `apps/edge/internal/input/a2a/types.go`
  - `apps/edge/internal/input/a2a/server.go`
  - `packages/go/config/config.go`
  - `configs/edge.yaml`
- human docs: `apps/edge/README.md`

## 읽는 조건

- Edge A2A HTTP 입력 표면, JSON-RPC, `message/send`, `tasks/get`, `tasks/cancel`을 다룰 때
- 외부 agent 또는 다른 프로젝트가 Edge 실행 그룹에 작업을 위임하는 요청/응답을 바꿀 때
- A2A task 상태, artifact, blocking/background 동작, bearer auth를 검토할 때

## 범위

이 계약은 Edge의 A2A JSON-RPC HTTP 입력 표면이다.
외부 caller는 JSON-RPC 2.0 envelope로 작업을 보내고, Edge는 내부 `adapter + target` 실행으로 변환한다.

OpenAI-compatible API와 달리 A2A는 task 상태 공유와 agent-to-agent 작업 위임에 맞춘 표면이다.
내부 Edge-Node protobuf transport를 대체하지 않는다.

## 최소 요청 형태

- endpoint: `POST <a2a.path>`; 기본 path는 `/a2a`
- agent card: `GET /.well-known/agent.json`
- auth: `a2a.bearer_token`이 비어 있지 않으면 `Authorization: Bearer <token>` 필요
- supported methods: `message/send`, `tasks/get`, `tasks/cancel`

`message/send`의 최소 params는 `message.role`과 text `parts[]`다.
`configuration.blocking`은 생략 시 `true`로 동작한다.

## 필드 의미

- `jsonrpc`: 반드시 `"2.0"`이어야 한다.
- `method`: 지원 method 중 하나다.
- `params.message.parts[].text`: 내부 실행 prompt로 추출되는 text다.
- `configuration.blocking`: `true` 또는 생략이면 완료까지 대기하고, `false`이면 working task를 즉시 반환한다.
- `Task.id`: Edge-local task id다.
- `Task.status.state`: 현재 MVP 값은 `working`, `completed`, `failed`, `canceled`다.
- `Artifact.parts`: 완료 결과 text를 담는 최소 artifact 표현이다.

## 금지 사항

- A2A 요청에 특정 외부 제품 전용 wrapper field를 추가하지 않는다.
- A2A를 OpenAI-compatible chat/completions 대체 표면으로 만들지 않는다.
- Edge 내부 실행을 `model` 중심으로 표현하지 않는다. 입력 표면에서만 A2A Task/JSON-RPC 표현을 유지하고 내부는 `adapter + target`으로 변환한다.
- Node address, token, transport client 내부 상태를 A2A 응답에 노출하지 않는다.

## 변경 시 확인할 코드/테스트

- `apps/edge/internal/input/a2a/types.go`
- `apps/edge/internal/input/a2a/server.go`
- `apps/edge/internal/input/a2a/server_test.go`
- `apps/edge/internal/input/a2a/task_store_test.go`
- `packages/go/config/config.go`
- `apps/edge/README.md`