Agent APIs: Veda & Kairo

Two first-class agents that other systems call — and they compose: Kairo does work; Veda governs it. Govern any AI-agent action through one API call, and run governed operations with a full, tamper-evident audit trail — without building the governance yourself.

Authentication & conventions

• Auth: Authorization: Bearer <JWT>. Tokens carry role and region claims.
• Roles: operator+ may request authorizations; platform_admin signs human-in-loop approvals and administers Kairo.
• Audit: every consequential decision is appended to a hash-chained, replayable log and returns an audit_id. Nothing is silently mutated.
• Errors: { "detail": "…" } — 401 auth, 403 role/region, 409 conflict, 422 invalid body, 429 quota.

Agent Veda — Governance API Live

Value add. One call governs any agent action. The action is deliberated by eight independent worldviews; a deterministic rule (never a model) synthesises the verdict, so it can't be gamed by optimising one metric. An action outside the caller's declared perimeter is refused before deliberation — cheap and safe. You pick the trust level per call.

Verdicts & autonomy

POST /v1/agents/authorize — the primary integration point

Governs a single intended action. Requires role operator+.

POST /v1/agents/authorize
Authorization: Bearer <JWT>

{
  "agent_id": "build-agent-7",
  "action": "deploy service atmasphere to production",
  "context": "Monday release train; reviewed by two engineers",
  "philosophies": [],
  "perimeter": { "allowed_actions": ["deploy", "rollback", "scale"] },
  "autonomy_level": "human_in_loop"
}

200 OK
{
  "audit_id": "a_9f2c…",
  "timestamp": "2026-07-29T12:00:00Z",
  "verdict": "ALLOW",
  "conditions": ["retain_rollback_plan", "notify_on_call"],
  "agent_id": "build-agent-7",
  "autonomy_level": "human_in_loop",
  "approval_required": true,
  "execute": false
}

Enforcement: if execute===true, run the action honouring every string in conditions; if approval_required===true, don't run until it's signed (below); otherwise surface the verdict and stop.

Approvals, evidence & loops

Machine-readable spec: OpenAPI 3.1 (veda-openapi.yaml) — drops into Swagger, Postman, or client codegen.

Agent Kairo — Governed Operations API Contract

Value add. Operations that pay for themselves, on the record. Kairo detects incidents and orchestrates remediation — including the unglamorous cost work: finding idle or over-provisioned compute, right-sizing it, retiring waste — and does none of it on trust. Every action is a declared plan, routed for approval where impact warrants a human, and written to a tamper-evident, replayable trail. Cost optimisation stops being the place observability goes to die.

Endpoints (contract)

How they compose

external system / scheduler
      │  POST /v1/kairo/remediations  (plan_id, action, perimeter, autonomy)
      ▼
   Kairo ─────────────► Veda  POST /v1/agents/authorize
      │                  │  ① suspension ② breakers ③ perimeter
      │                  │  ④ eight-worldview council ⑤ autonomy tier
      │                  ▼
      │        verdict + conditions + execute + audit_id  (hash-chained)
      ▼
 execute only if execute==true, honouring conditions ──► write result + audit

Net value: a single, governed way to act on infrastructure — cheaper by construction (deny-by-default, cost-aware remediation) and auditable by construction (plan → approval → chained evidence).

Veda endpoints are live in the platform runtime. Kairo endpoints are the integration contract over the shipped control-plane model; confirm availability against the running service before production use. Questions: support@atmakosh.com.