Skip to main content

Running Agents

Same underlying runtime, multiple ways to start a run. Pick the surface that matches what you're doing — interactive work in chat, scripted runs from the CLI, fixed pipelines via flows, or autonomous background runs via triggers.

Starting an interactive run​

Open a chat tab, pick an agent from the dropdown, type a message:

[tab] agent: generalist ▾   model: claude-sonnet-4 ▾
user: Rename getUser to fetchUser everywhere

You see every step inline. Interactive, checkpointed, rollback-able. Closing the tab doesn't kill the run immediately — it finishes the current step and exits — but you lose the live view.

Agent flows​

When you want a fixed pipeline instead of a chat loop, run a flow. The flow runtime reads a declarative graph (nodes = agents, edges = data flow) and executes it; each node is still a normal agent run, the flow is just wiring.

codebolt flow run plan-execute-review --input '{"task": "..."}'

Use flows for repeatable multi-agent patterns. See Reading a flow.

Background triggers​

Some agents run without you starting them. A background agent declares triggers: in its manifest:

triggers:
  - type: cron
    schedule: "0 9 * * 1"     # Mondays at 9 AM
  - type: file_change
    pattern: "src/**/*.ts"
  - type: webhook
    path: /hooks/my-agent

When the trigger fires, the agent runs. Results land in the Background Agents panel (desktop) or via codebolt agent history (CLI).

Use for scheduled audits ("every Monday, run the reviewer on last week's changes"), reactive work ("when any file under schema/ changes, regenerate types"), and webhook integrations ("when GitHub posts a PR event, run a reviewer and comment").

Watching a running agent​

The chat tab (or Background Agents panel) shows tool calls and LLM calls as they happen, with timing for each phase.

Every phase — deliberate, execute, reflect — appears with timing and inputs/outputs. Nothing is hidden.

Stopping a running agent​

There are two flavours: graceful (lets the agent finish its current phase, emit a clean run.stopped event, flush memory, exit) and force (immediate kill, run marked killed with reason forced). Use force only when graceful doesn't respond.

  • Esc in the chat tab — graceful stop at the next phase boundary.
  • Stop button in the agent run panel — same.
  • Force kill in the run details menu — for hung runs only.

Interrupting to add information​

If the agent is mid-task and you realise it's missing something, don't stop it — interject. Type a new message while the agent is working; it queues up and is delivered at the next phase boundary. The agent gets "user added context mid-run" as part of its next deliberation.

This is different from stopping and starting a new turn — the queued message shares the same thread and context.

Running multiple agents at once​

  • Different tabs — independent, parallel. Each has its own agent.
  • Child agents — one agent spawns another via codebolt_agent.start. The child runs as a nested run. See Agent run end-to-end.
  • Flow — a declared multi-agent pipeline, graph-based.
  • Swarm — a dynamic group of cooperating agents. See Running a swarm.

All of these are bounded by server-wide limits: max concurrent agent processes, max spawn rate, etc. See Self-hosting → Scaling if you hit them.

Agent history​

Every run is recorded — successful or failed, from any starting point.

Agents panel → History tab. Filter by agent, status, date.

Each entry has the run ID, agent, outcome, duration, token usage, cost, and a link to the trace.

Limits and budgets​

Every agent has limits in its manifest:

  • max_tool_calls — stop after N tool calls
  • max_tokens — stop when total tokens exceed N
  • max_wall_time_seconds — stop after N seconds of real time
  • max_cost_usd — stop when cumulative cost exceeds $N

Hitting any of these stops the run with terminal state killed and reason budget_<kind>. You can raise the limit for a specific run with --limits on the CLI or by editing the agent's yaml.

See also​