Agents API

Create, run, and manage scheduled AI agents under /api/agents.

Agents are scheduled, evidence-grounded LLM jobs: they analyze your data on a cadence and emit outputs. Listing needs the read scope; creating/updating/running need write and an org-admin service account; deleting needs manage. Each run spends LLM tokens against the org's budget.

#List and get

  • GET /api/agents — the org's agents.
  • GET /api/agents/{agentId} — one agent (its instructions, model, grounding, cadence, and outputs). Use as a template for updates.

#Create and update

  • POST /api/agents — create an agent. instructions is the task prompt; grounding is the resources a run may read as evidence; outputs is what it produces; cadence is like a schedule. Bound cost with maxTokensPerRun and maxRounds.
  • PUT /api/agents/{agentId} — replace its fields.
  • PATCH /api/agents/{agentId}/active — pause or resume its schedule ({"active": false}).

#Run and inspect

  • POST /api/agents/{agentId}/run — run it now (async); returns a runId. Spends tokens.
  • GET /api/agents/{agentId}/runs — the agent's recent runs and their outputs.

#Delete

DELETE /api/agents/{agentId} — remove the agent and its run history (manage).