Home Dashboard GitHub

Agent Runs

Run multi-turn agent sessions with per-turn model selection, governed tool execution, and budget enforcement.

Getting Started with Agent Runs

BrainstormRouter's session loop lets you run multi-turn agent sessions where each turn gets the best model (Thompson sampling), context refreshes (SOUL, MEMORY, SKILL, HEARTBEAT, WORKSPACE), tools execute through a governed MCP pipeline, and budgets enforce in real-time.

Prerequisites

  • A BrainstormRouter API key (sign up)
  • At least one provider connected (LLMS → Providers in the dashboard)

1. Bootstrap an Agent

Create an agent with an identity, budget, and department:

curl -X POST https://api.brainstormrouter.com/v1/agent/bootstrap \
  -H "Authorization: Bearer brk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "research-01",
    "display_name": "Research Agent",
    "budget_daily_usd": 10.0,
    "department": "Engineering"
  }'

2. Run Your First Session

Send a message and the agent loop streams events back as SSE:

curl -N https://api.brainstormrouter.com/v1/agents/research-01/run \
  -H "Authorization: Bearer brk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Research the latest AI safety papers and write a summary",
    "max_turns": 10,
    "budget_cap_usd": 2.0
  }'

You'll see events stream in real-time:

data: {}

event: br.model_selected
data: {"model":"claude-sonnet-4","provider":"anthropic","strategy":"thompson","turnIndex":0}

event: agent.tool_use
data: {"toolName":"web_search","args":{"query":"AI safety papers 2026"}}

event: agent.tool_result
data: {"toolName":"web_search","results":12,"latencyMs":312,"turnIndex":0}

event: br.model_selected
data: {"model":"gemini-2.5-flash","provider":"google","strategy":"thompson","turnIndex":1}

event: agent.message
data: {"text":"Here are the key findings...","model":"gemini-2.5-flash","turnIndex":1}

event: session.status_ended
data: {"reason":"completed","totalTurns":3,"totalCostUsd":0.008,"durationMs":4521}

Notice: Thompson sampling picked Claude for the research turn and Gemini for the synthesis turn — different models for different parts of the task, automatically.

3. SDK Examples

TypeScript

import BrainstormRouter from "brainstormrouter";

const client = new BrainstormRouter({ apiKey: "brk_..." });

const result = await client.agentRuns.run("research-01", {
  message: "Research AI safety papers and summarize",
  max_turns: 10,
  budget_cap_usd: 2.0,
});

Python

from brainstormrouter import BrainstormRouter

client = BrainstormRouter(api_key="brk_...")

result = client.agent_runs.run("research-01",
    message="Research AI safety papers and summarize",
    max_turns=10,
    budget_cap_usd=2.0,
)

4. SSE Event Types

EventDescription
session.status_runningLoop started
session.status_idleWaiting for user input
session.status_endedLoop finished (includes reason, cost, turns)
agent.messageAgent text response
agent.tool_useTool invocation (name, args)
agent.tool_resultTool execution result
br.model_selectedWhich model was picked and why
br.guardrail_interventionA guardrail fired (warn or block)
br.budget_warningApproaching budget limit
br.routing_savingsCounterfactual savings for this turn

5. Mid-Run Steering

Send events to a running session to steer the agent:

# Add a message mid-run
curl -X POST https://api.brainstormrouter.com/v1/agents/research-01/sessions/{sid}/events \
  -H "Authorization: Bearer brk_..." \
  -d '{"type": "user.message", "text": "Also check for papers on alignment"}'

# Interrupt a running session
curl -X POST https://api.brainstormrouter.com/v1/agents/research-01/sessions/{sid}/events \
  -H "Authorization: Bearer brk_..." \
  -d '{"type": "user.interrupt"}'

Events are delivered via PG LISTEN/NOTIFY and processed at the next turn boundary.

6. Budget Enforcement

When the per-run budget cap is hit, the loop stops with reason: "budget_exhausted". Per-agent daily budgets (set via the agent profile) are also checked after each turn.

data: {"spentUsd": 1.8, "capUsd": 2.0, "remainingUsd": 0.2}

event: session.status_ended
data: {"reason": "budget_exhausted", "totalTurns": 5, "totalCostUsd": 2.003}

7. Context Injection

Every turn refreshes the agent's context from six sources:

TypeSourceBudget
SOULSOUL.md or HR record800 tokens
MEMORYGovernance rules + user facts + archival1200 tokens
SKILLDomain knowledge + learned patterns600 tokens
HEARTBEATHealth warning (only when degraded)100 tokens
WORKSPACEActive working files800 tokens
REFERENCEDesign specs, style guides200+800 tokens

This is the Kairos pattern — memory and workspace changes mid-run are visible on the next turn. An agent that learns something on turn 2 can use it on turn 3.

Next Steps