Agent OS Deployment API — the real interface behind this site

Everything below is the actual API this demo runs on — the same endpoints the UI you've been using calls. Public API keys aren't issued; when Agent OS is deployed for your business, your engineers get authenticated access to exactly this surface, plus webhooks.

Run an agent (SSE)

One POST, one server-sent-event stream: typed execution spans as they happen, then the validated result. Runs are metered (10 credits/day per guest session in the demo; deployment sets your own limits) and inputs are PII-masked before any provider call.

run.http

POST /api/agents/run
Content-Type: application/json

{ "slug": "deal-health-predictor",
  "input": { "deals": "Acme 120K proposal sent, no reply 12 days..." } }

# Response: text/event-stream
event: span
data: {"phase":"start","span":{"id":"s1","name":"PII scrub","kind":"validation","status":"running","startedAt":0}}

event: span
data: {"phase":"end","span":{"id":"s2","name":"llm.generate","kind":"llm","status":"ok","startedAt":12,"endedAt":2840,"detail":"groq · llama-3.3-70b · attempt 2/3"}}

event: result
data: {"output":[{"type":"table","columns":[...],"rows":[...]}],"voiceScript":"...","mode":"live","provider":"groq","promptVersion":"1.1.0"}

Span schema

The observability contract — what the execution theater renders is this stream, unedited.

span.d.ts

type Span = {
  id: string
  name: string
  kind: "validation" | "llm" | "tool" | "fallback" | "compose"
  startedAt: number      // ms since run start
  endedAt?: number       // absent while running
  status: "running" | "ok" | "error" | "skipped"
  detail?: string        // human-readable outcome line
  payload?: string       // abbreviated, PII-masked preview — never raw data
}

Intent mapping

Natural language → an agent's typed inputs, with a one-clarify-max contract so conversations always terminate in a run.

intent.http

POST /api/agents/intent
{ "slug": "deal-health-predictor",
  "utterance": "which deals are quietly dying?",
  "force": false }

# → {"ok":true,"mappable":true,"input":{...},"confirmation":"..."}
# or {"ok":true,"mappable":false,"question":"ONE clarifying question"}
# force:true guarantees mappable:true (one-clarify-max contract)

Fleet routing

The Voice Console's brain: one utterance in, the right agent out of the whole registry.

route.http

POST /api/os/route-intent
{ "utterance": "I need more viewings booked for my Marina listings" }

# → {"ok":true,"slug":"real-estate-lead-engine",
#     "agentName":"Real Estate Lead Engine","line":"Engaging ..."}

Webhooks — client installations

Deployed installations emit signed events on run completion and real-world writes (calendar bookings, sheet appends, CRM updates) so your systems stay in sync.

webhook.http

# Client installations only — configured at deployment
POST https://your-endpoint.example/agentos
X-AgentOS-Signature: sha256=...

{ "event": "run.completed",
  "workspace": "ws_...",
  "slug": "ai-voice-agent",
  "action": "book_appointment",
  "write": { "target": "calendar", "real": true, "detail": "Event created ..." } }

Technical evaluation? The whole system is inspectable live.

Run agents in the library, watch the spans, read every system prompt — then book a call to talk deployment.