Agent Runs

Agent Runs are goal-directed executions where an AI Agent decomposes a high-level objective into sub-tasks, executes them, evaluates results, and re-plans as needed. Write/send/delete actions require human approval.

Status: Planned (Phase 2, Milestone M2.1)

Endpoints

Method	Path	Description	Auth	Rate Limit
POST	/agent-runs	Create an agent run	JWT + Entitlement	10/min
GET	/agent-runs	List user agent runs	JWT	60/min
GET	/agent-runs/:id	Get run detail + trace	JWT	60/min
POST	/agent-runs/:id/steps/:stepId/approve	Approve a paused action	JWT	30/min
POST	/agent-runs/:id/steps/:stepId/reject	Reject a paused action	JWT	30/min
DELETE	/agent-runs/:id	Cancel a run	JWT	10/min
GET	/agent-runs/:id/trace	Full immutable trace	JWT	60/min

Create Agent Run

Request

Field	Type	Required	Description
goal	string	Yes	High-level objective for the agent
contextIds	string[]	No	Context IDs to bind to the run
budget	object	No	Budget constraints
budget.maxCredits	number	No	Max credits to spend
budget.maxMinutes	number	No	Max wall-time in minutes

Response

{
  "data": {
    "id": "run-abc123",
    "goal": "Research our top 5 competitors and add comparison to Notion",
    "status": "planning",
    "plan": [],
    "budget": { "maxCredits": 100, "maxMinutes": 30, "spent": 0 },
    "createdAt": "2026-07-15T10:00:00.000Z"
  }
}

Agent Run Status Lifecycle

pending → planning → running → completed
                   ↘ awaiting_approval → running (approved)
                   ↘ awaiting_approval → cancelled (rejected)
                   ↘ failed
         → cancelled (user-initiated)

Approval Gate

When the agent encounters a risky action (write, send, delete), it pauses and waits for human approval.

Approve

POST /agent-runs/:id/steps/:stepId/approve

Reject

POST /agent-runs/:id/steps/:stepId/reject
{ "reason": "Don't update that Notion page yet" }

Trace

The trace is an append-only log of every action the agent took, including inputs, outputs, and model decisions.

{
  "data": {
    "steps": [
      {
        "stepId": "step-1",
        "action": "web_search",
        "input": { "query": "competitor pricing SaaS 2026" },
        "output": { "results": [...] },
        "status": "completed",
        "startedAt": "2026-07-15T10:01:00.000Z",
        "completedAt": "2026-07-15T10:01:15.000Z"
      }
    ]
  }
}