Agent Runs

curl -X POST https://upbutler.com/api/v1/monitors \
  -H "Authorization: Bearer $UPBUTLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support triage fleet", "kind": "agent", "agent": {"budget": {"usd": 2, "steps": 60}}}'
# → { "_id": "mon_…", "agent": { "token": "ar_Xf3kq9LmR2vT8wYzN4bC1dE7", "startUrl": "https://upbutler.com/api/v1/runs", … } }

curl -X POST https://upbutler.com/api/v1/runs \
  -H "Content-Type: application/json" \
  -d '{
    "token": "ar_Xf3kq9LmR2vT8wYzN4bC1dE7",
    "agent": "triage-bot-3",
    "runId": "job-4812",
    "task": "Triage ticket #4812",
    "budget": {"usd": 2, "tokens": 400000, "steps": 60, "durationSec": 900},
    "expectedDurationSec": 180,
    "metadata": {"ticket": 4812}
  }'

{
  "ok": true,
  "continue": true,
  "id": "run_0n3q8jz4k7m2p9x1c5v",
  "token": "rt_Qm7vB2xK9pL4sT1nW8cZ3yH6",
  "progressUrl": "https://upbutler.com/api/v1/runs/rt_Qm7vB2xK9pL4sT1nW8cZ3yH6/progress",
  "endUrl": "https://upbutler.com/api/v1/runs/rt_Qm7vB2xK9pL4sT1nW8cZ3yH6/end",
  "pingUrl": "https://upbutler.com/api/v1/runs/rt_Qm7vB2xK9pL4sT1nW8cZ3yH6/progress",
  "monitor": { "id": "mon_0n3q8jy9x1c4v7b2n6m", "name": "Support triage fleet" },
  "run": { "id": "run_0n3q8jz4k7m2p9x1c5v", "status": "running", "steps": 0, "usd": 0, "tokens": 0, "flags": [], "budgetUse": [] }
}

curl -X POST https://upbutler.com/api/v1/runs/rt_Qm7vB2xK9pL4sT1nW8cZ3yH6/progress \
  -H "Content-Type: application/json" \
  -d '{"step": "search", "message": "Looking up similar tickets", "toolCalls": ["search_tickets"], "usd": 0.012, "tokens": 1840}'

{
  "ok": true,
  "continue": true,
  "run": {
    "id": "run_0n3q8jz4k7m2p9x1c5v", "status": "running", "steps": 4, "usd": 0.31, "tokens": 48210, "flags": [],
    "budgetUse": [{ "dimension": "usd", "used": 0.31, "limit": 2, "pct": 15.5 }]
  }
}

{
  "ok": true,
  "continue": false,
  "action": "stop",
  "reason": "Automatic stop: over budget: $2.04 of $2.00",
  "run": { "id": "run_0n3q8jz4k7m2p9x1c5v", "status": "running", "steps": 41, "usd": 2.04, "tokens": 391820, "flags": ["budget"], "budgetUse": [ … ] }
}

curl -X POST https://upbutler.com/api/v1/runs/rt_Qm7vB2xK9pL4sT1nW8cZ3yH6/end \
  -H "Content-Type: application/json" \
  -d '{"status": "success", "summary": "Routed to billing"}'
# status: success | failed | cancelled   (+ "error" for failed, final "usd"/"tokens" not reported yet)

# One run
curl -X POST https://upbutler.com/api/v1/runs/run_0n3q8jz4k7m2p9x1c5v/stop \
  -H "Authorization: Bearer $UPBUTLER_API_KEY" -H "Content-Type: application/json" \
  -d '{"action": "stop", "reason": "Looping on search_tickets"}'

# Every flagged run of a monitor (or all of them: "onlyFlagged": false)
curl -X POST https://upbutler.com/api/v1/monitors/mon_0n3q8jy9x1c4v7b2n6m/runs/stop \
  -H "Authorization: Bearer $UPBUTLER_API_KEY" -H "Content-Type: application/json" \
  -d '{"onlyFlagged": true}'

# Changed your mind before the agent acted on it
curl -X POST https://upbutler.com/api/v1/runs/run_0n3q8jz4k7m2p9x1c5v/resume -H "Authorization: Bearer $UPBUTLER_API_KEY"

curl https://upbutler.com/api/v1/runs/rt_Qm7vB2xK9pL4sT1nW8cZ3yH6/signal
# → { "ok": true, "continue": true, "run": { "id": "run_…", "status": "running" } }

POST https://agents.example.com/hooks/upbutler-stop
webhook-id: evt_0n3q8jz9d2f4g6h8j0k
webhook-timestamp: 1791590451
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "id": "evt_0n3q8jz9d2f4g6h8j0k",
  "type": "run.stop_requested",
  "timestamp": "2026-10-10T09:20:51.204Z",
  "workspaceId": "ws_0n3q8jy8r5t1y3u7i9o",
  "data": {
    "monitor": { "id": "mon_0n3q8jy9x1c4v7b2n6m", "name": "Support triage fleet" },
    "run": { "id": "run_0n3q8jz4k7m2p9x1c5v", "runId": "job-4812", "agent": "triage-bot-3", "task": "Triage ticket #4812", "status": "running", "steps": 41, "usd": 2.04, "tokens": 391820 },
    "signal": { "continue": false, "action": "stop", "reason": "Automatic stop: over budget: $2.04 of $2.00" },
    "stop": { "action": "stop", "by": "UpButler", "source": "policy", "at": "2026-10-10T09:20:51.198Z" }
  }
}

"monitors": [{
  "id": "mon_0n3q8jy9x1c4v7b2n6m", "name": "Support triage fleet", "kind": "agent", "state": "down",
  "runs": {
    "running": 7,
    "detection": { "stuckAfterSec": 600, "loopRepeats": 5, "autoStop": ["budget"], "defaultBudget": { "usd": 2, "steps": 60 } },
    "flagged": [{
      "id": "run_0n3q8jz4k7m2p9x1c5v", "agent": "triage-bot-3", "task": "Triage ticket #4812",
      "startedAt": "2026-10-10T09:12:03.000Z", "lastProgressAt": "2026-10-10T09:20:44.000Z",
      "steps": 38, "usd": 1.8, "tokens": 352000,
      "budgetUse": [{ "dimension": "usd", "used": 1.8, "limit": 2, "pct": 90 }],
      "detections": [{ "rule": "loop", "severity": "down", "at": "2026-10-10T09:19:10.000Z", "message": "the same step repeated 5× in a row: search_tickets" }],
      "killSwitch": null,
      "lastSteps": [{ "at": "…", "type": "progress", "step": "search_tickets", "toolCalls": ["search_tickets"], "usd": 0.05 }, …]
    }],
    "recent": [{ "id": "run_…", "agent": "triage-bot-1", "status": "success", "endedAt": "…", "usd": 0.13 }, …]
  }
}]

# With the incident token from the page (the responder must allow "stop_runs", and claim first)
curl -X POST https://upbutler.com/api/v1/incidents/$INCIDENT_ID/claim -H "Authorization: Bearer $INCIDENT_TOKEN"

curl https://upbutler.com/api/v1/incidents/$INCIDENT_ID/runs -H "Authorization: Bearer $INCIDENT_TOKEN"

curl -X POST https://upbutler.com/api/v1/incidents/$INCIDENT_ID/runs/stop \
  -H "Authorization: Bearer $INCIDENT_TOKEN" -H "Content-Type: application/json" \
  -d '{"reason": "Same fetch five times with no new data; $1.80 of $2.00 spent"}'
# → { "action": "stop", "stopped": [{ "id": "run_…", "agent": "triage-bot-3", "task": "Triage ticket #4812" }], … }

import { withRun, RunStopped } from '@upbutler/sdk';

try {
  await withRun(
    { token: process.env.UPBUTLER_RUN_TOKEN!, agent: 'triage-bot', task: `Triage ticket #${id}`, budget: { usd: 2, steps: 60 }, expectedDurationSec: 180 },
    async (run) => {
      // A tool call: fingerprinted by name + arguments, so the same call again and again is a loop.
      const similar = await search(q);
      await run.toolCall('search_tickets', { q });           // throws RunStopped when told to stop

      // LLM usage: UpButler reads result.usage, it never sees the call. Prices are USD per million tokens.
      const res = await run.llm((signal) => anthropic.messages.create({ model, max_tokens: 1024, messages }, { signal }), { inputPerMTok: 3, outputPerMTok: 15 });

      await run.step('route', { message: 'billing' });        // sends the buffered usage with it
    },
  );
} catch (e) {
  if (!(e instanceof RunStopped)) throw e;                    // already ended as cancelled
  console.warn('Stopped by UpButler:', e.signal.reason);
}

import os
from upbutler import start_run, RunStopped

try:
    with start_run(token=os.environ["UPBUTLER_RUN_TOKEN"], agent="triage-bot", task=f"Triage ticket #{id}",
                   budget={"usd": 2, "steps": 60}, expected_duration_sec=180) as run:
        similar = search(q)
        run.tool_call("search_tickets", {"q": q})            # raises RunStopped when told to stop

        # LLM usage: UpButler reads result.usage, it never sees the call. Prices are USD per million tokens.
        res = run.llm(lambda: client.messages.create(model=model, max_tokens=1024, messages=messages),
                      input_per_mtok=3, output_per_mtok=15)

        run.step("route", message="billing")                 # sends the buffered usage with it
except RunStopped as e:                                       # already ended as cancelled
    print("Stopped by UpButler:", e.signal.get("reason"))

import { startRun } from '@upbutler/sdk';

const run = await startRun({ token: process.env.UPBUTLER_RUN_TOKEN!, agent: 'triage-bot', onStop: 'return' });
try {
  for (const ticket of tickets) {
    const signal = await run.step('triage', { message: `ticket ${ticket.id}` });
    if (!signal.continue) break;                    // the contract: stop when told to
    await triage(ticket);
  }
} finally {
  await run.end({ status: run.stopped ? 'cancelled' : 'success' });
}

export UPBUTLER_RUN_TOKEN=ar_Xf3kq9LmR2vT8wYzN4bC1dE7

# Start → run the command → end with its exit code. A stop sends SIGTERM (SIGKILL after 10 s).
upbutler run --agent nightly-report --task "Build the weekly report" \
  --budget-usd 5 --budget-seconds 1800 --expect 600 -- python agent.py

# Inside the command, one line of output is one progress ping (the line is not printed):
echo '::upbutler:: {"step":"export","usd":0.02,"tokens":1800,"toolCalls":["sql_query"]}'
echo '::upbutler:: writing the report'

# The command also gets UPBUTLER_RUN_ID, UPBUTLER_RUN_PROGRESS_URL, UPBUTLER_RUN_SIGNAL_URL, UPBUTLER_RUN_END_URL.

import { query } from '@anthropic-ai/claude-agent-sdk';
import { withRun } from '@upbutler/sdk';

await withRun({ token: process.env.UPBUTLER_RUN_TOKEN!, agent: 'repo-fixer', task: prompt, budget: { usd: 5 }, pollSec: 20 }, async (run) => {
  const abortController = new AbortController();
  run.abortSignal.addEventListener('abort', () => abortController.abort());   // stop → abort the agent loop

  for await (const msg of query({ prompt, options: { abortController } })) {
    if (msg.type === 'assistant') {
      for (const block of msg.message.content) {
        if (block.type === 'tool_use') await run.toolCall(block.name, block.input);   // throws RunStopped
      }
    }
    if (msg.type === 'result') run.usage({ total_cost_usd: msg.total_cost_usd, ...msg.usage });
  }
});

from agents import Agent, Runner, RunHooks
from upbutler import start_run

class UpButlerHooks(RunHooks):
    def __init__(self, run):
        self.run = run

    async def on_tool_end(self, context, agent, tool, result):
        # Fingerprint = tool + what it returned: the same answer again and again is a loop.
        self.run.tool_call(tool.name, {"result": str(result)[:2000]})   # raises RunStopped → the run ends

    async def on_agent_end(self, context, agent, output):
        self.run.usage(tokens=context.usage.total_tokens)

with start_run(token=RUN_TOKEN, agent="support-agent", task=question, budget={"tokens": 400_000}) as run:
    result = await Runner.run(agent, question, hooks=UpButlerHooks(run))

from upbutler import start_run, tool_fingerprint

with start_run(token=RUN_TOKEN, agent="research-graph", task=topic, budget={"steps": 80}) as run:
    for chunk in graph.stream(inputs, stream_mode="updates"):
        for node, update in chunk.items():
            # One ping per node that ran; the same node producing the same update is a loop.
            run.step(node, fingerprint=tool_fingerprint(node, update))   # raises RunStopped → leaves the stream