toki
de78479670
- Move contract files to inner/outer directory structure - Add create-contract and update-contract skills - Update agent-ops rules and domain rules - Update roadmap and SDD documentation - Update README files across apps
63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# 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`
|