Control plane

With a server and model key configured, this example creates a Pi agent and starts a capped run. Use a new agent ID on the first call; later requests can reuse it. The timeline returns one page, not necessarily the completed result.

// Node.js with the server's printed /v2 URL and API key.
const base = process.env.AGENTRUN_BASE_URL!.replace(/\/$/, '');
const token = process.env.AGENTRUN_API_KEY!;

// A local helper using native fetch, not an AgentRun SDK.
async function request(path: string, body?: unknown) {
  const response = await fetch(base + path, {
    method: body === undefined ? 'GET' : 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

await request('/agents', {
  definition: {
    id: 'triage', name: 'Issue triage', harness: 'pi',
    instructions: 'Triage the supplied issue. Ask for missing context.',
    tools: ['ask_person'], max_cost_usd: 2, cap_mode: 'strict',
  },
});

const { run_id } = await request('/agents/triage/runs', {
  input: { content: 'Checkout fails on Safari. What should we investigate?' },
  max_cost_usd: 1,
});
console.log(await request(`/runs/${run_id}/timeline?wait_ms=5000`));
console.log(await request(`/runs/${run_id}`));

Continue polling with the returned next_after cursor as after until final, or use server-sent events. For definition edits, send the current home_etag as If-Match to detect concurrent changes. Check /v2/capabilities for the harnesses available on your server.

The self-hosted server includes the console. Persist its data directory and retain the sealing key across deployments. That directory holds definitions, revisions, run databases, logs, workspaces, and agent learning files.

Before scheduling unattended triage, grant the example agent a tool that can retrieve issues and configure its access. Its initial ask_person tool can request context, but cannot fetch issues itself.

Send this configuration to POST /v2/triggers to run at 1:30 a.m. Los Angeles time. Every triggered run needs a cap, supplied by the trigger or definition. A schedule skips a firing while its previous run is active or waiting for input.

{
  "name": "nightly triage",
  "source": {
    "kind": "schedule",
    "cron": "30 1 * * *",
    "timezone": "America/Los_Angeles"
  },
  "target": {
    "kind": "start_run",
    "agent_id": "triage",
    "input": { "content": "Triage last night's issues." },
    "max_cost_usd": 2
  }
}

For incoming events, use { "kind": "webhook" } as the source. Configure AGENTRUN_SEAL_KEY, save the returned signing secret, and sign deliveries to /v2/hooks/{trigger_id}. Outbound webhooks notify your application when runs need input or end.

Set max_cost_usd on the definition for a default; a run can override it. The example uses cap_mode: "strict", reserving input at its worst-case price. Default expected mode accounts for likely cache hits and can exceed the cap on a cache miss.