toki/iop

toki de78479670 refactor: organize contract files and update agent-ops structure

- 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

2026-06-27 07:02:48 +09:00

2.6 KiB

Raw Blame History

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

2.6 KiB Raw Blame History