Overview
The Agents API v1 is the versioned protocol of the agents bus, spoken by the krad CLI and by any program that writes a line of JSON to a loopback socket.
The Agents API is the protocol of Krad ADE's agents bus. Agents in the app's terminals and chats use it to list each other, wait for each other and, from a lead, start and close Workers. Scripts and extensions use it to read the app's Kraddies, automations, sessions and changes. Programs outside the app use it to watch every agent's state as it changes.
The krad CLI speaks it, and so can any program that opens a TCP socket and writes a line of JSON. The machine-readable description is sdk/schema/krad-agents-api.json in the app's repository; the test suite reads and writes back each of its examples byte for byte.
{"api_version":1,"token":"6f1c0d9e2b7a4c58e3f09a1d7b6c2e40","from":"Client","request":"Hello"}
{"Hello":{"api_version":1,"build":"0.3.3","pid":48211}}Who it is for
| Client | Reaches the bus through | Can |
|---|---|---|
| An agent or shell in one of the app's terminals | The KRAD_ADE_* variables the app sets in that terminal | List and wait for the agents of its environment, read their screens, use sessions, worktrees, files, changes, Kraddies, automations, memory and variants |
| A lead, the chat of a session the user made its orchestrator | Its terminal's variables; the app recognises it | All of the above, plus start, direct and close its Workers, close sessions of its group and pick a variant winner |
| A script, extension or tool outside the app | The API discovery file | List and watch the agents of every environment |
| A webhook receiver | An address added in Settings › Webhooks | Receive app events as signed HTTP posts |
Version 1
Every request carries its API version, and every refusal carries a stable error code. Version 1 changes only by addition; see Compatibility.
Reference
Transport
Loopback TCP, the envelope, the Hello handshake, limits and deadlines.
Authentication
Tokens, callers and their rights, api.json and the security model.
Requests
Every request and its response, with exact JSON.
Agent states
The six states and the four coarse states.
Subscriptions
SubscribeAgents: snapshot, seq, stream, resume, heartbeat and filters.
App events and webhooks
Event records, the event journal and signed webhooks.
Errors and exit codes
Stable error codes and the CLI's exit codes.
krad CLI
Every command and the request it makes.
Cookbook
Shell, Python and Node.js clients.
Compatibility
What is stable in v1 and how it changes.
For how the bus fits in the app, see Agents bus. The words used here (session, group, lead, Worker, Kraddie, keepsake) follow the app's vocabulary.