Cookbook
Short Agents API clients in shell, Python and Node.js that list agents, watch them, wait and read, close finished Workers and receive webhooks.
From the app's terminals
krad agents list --json | jq -r '.Agents[] | "\(.environment):\(.terminal) \(.state) \(.title)"'Outside the app
Programs outside the app's terminals read api.json and call as "Client", which may list and watch agents. Both examples list the agents, then subscribe and print each change.
import json, os, socket
from pathlib import Path
base = os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config"
api = json.loads((Path(base) / "krad-ade" / "api.json").read_text())
host, port = api["endpoint"].rsplit(":", 1)
def envelope(request):
line = {"api_version": 1, "token": api["token"], "from": "Client", "request": request}
return (json.dumps(line) + "\n").encode()
def call(request):
with socket.create_connection((host, int(port))) as sock:
sock.sendall(envelope(request))
return json.loads(sock.makefile().readline())
for agent in call("List")["Agents"]:
print(agent["environment"], agent["terminal"], agent["state"], agent["title"])
with socket.create_connection((host, int(port))) as sock:
sock.sendall(envelope({"SubscribeAgents": {}}))
for line in sock.makefile():
message = json.loads(line)
if "AgentEvent" in message:
event = message["AgentEvent"]
print(event["seq"], event["terminal"], event["previous"], "->", event["state"])
elif "Error" in message:
raise SystemExit(message["Error"]["code"])Windows
On Windows the file is in %APPDATA%\krad-ade unless XDG_CONFIG_HOME or HOME is set, so adjust base there.
A long-lived watcher should also resume with since_seq and stream after a drop and treat 45 seconds of silence as a lost app. See Subscriptions.
Receive webhooks
Add the webhook
In Settings › Webhooks, add the address of your receiver, pick the event kinds and set a secret.
Send a test
Press "Test event". The app posts one ping.
Check the signature
Verify x-krad-signature-256 as shown in App events and webhooks, and answer with a 2xx to stop the retries.