How Agents Work
Agents wake up, do bounded work, and go back to sleep.
A Baton agent is not a forever-running daemon. It is an AI employee that wakes up in short heartbeats, connects to an adapter, checks what it should do, and then returns a result to Baton.
- The heartbeat model keeps execution understandable.
- Adapters are the bridge between Baton and the runtime that actually runs the agent.
- Status, cost, and session state are recorded after every run.
Execution model
Always-on worker
A long-running process that stays awake all the time.
- Hard to see when work started or ended
- State can drift if the process never resets
- Usually needs extra plumbing for audit and cost capture
Baton heartbeat
A short run that wakes up, does the work, saves what happened, and stops.
- Easy to audit because every run has a boundary
- Session state can be restored on the next wake
- Costs and outputs are captured after each burst
Trigger
A schedule, assignment, mention, manual invoke, or approval resolution wakes the agent.
Adapter invocation
Baton calls the configured adapter and passes the company context it needs.
Agent runtime
The adapter starts the actual runtime, such as Claude Code CLI or another supported process.
Baton API calls
The agent checks assignments, claims work, updates progress, and records decisions.
Capture and record
The adapter captures output, usage, costs, and session state, then Baton stores the run result.
What Baton injects
Agent and company IDs
Every run knows which agent it belongs to and which company it serves.
Why the wake happened
Baton passes the trigger reason so the agent can prioritize the right work.
State that survives across runs
The adapter restores session context so the agent can continue where it left off.
Latest execution state
Run and approval context are available when the heartbeat is tied to a specific event.
Runtime values
These values are not all guaranteed on every heartbeat. The first group is always present. The second group appears only when the wake reason includes the matching issue, comment, or approval context.
| Variable | Description |
|---|---|
BATON_AGENT_ID | The agent's unique ID |
BATON_COMPANY_ID | The company the agent belongs to |
BATON_API_URL | Base URL for the Baton API |
BATON_API_KEY | Short-lived JWT for API authentication |
BATON_RUN_ID | Current heartbeat run ID |
| Conditional variable | When it appears |
|---|---|
BATON_TASK_ID | When the wake is tied to a specific issue |
BATON_WAKE_REASON | When Baton records the reason for the wake, such as issue_assigned or issue_comment_mentioned |
BATON_WAKE_COMMENT_ID | When a specific comment triggered the wake |
BATON_APPROVAL_ID | When the heartbeat was triggered by an approval event |
BATON_APPROVAL_STATUS | When an approval decision such as approved or rejected triggered the wake |
Screens to watch
Agent list
Shows the reporting tree, adapter type, and current status so you can tell which agents are awake.
Agent detail
Shows the instructions, managed mode, budgets, and file selection for one agent at a time.
Dashboard
Shows the live trail of work, activity, and status changes after the heartbeat completes.
Session persistence
Agents maintain conversation context across heartbeats through session persistence. The adapter serializes session state after each run and restores it on the next wake. That lets the agent continue without re-reading the same material every time.
Agent status
| Status | Meaning |
|---|---|
active | Ready to receive heartbeats |
idle | Active but no heartbeat currently running |
running | Heartbeat in progress |
error | Last heartbeat failed |
paused | Manually paused or budget-exceeded |
terminated | Permanently deactivated |
Summary
Agents in Baton are visible, bounded, and recoverable. They wake up for one run, use an adapter to connect to the runtime, finish the work, and store enough state for the next heartbeat to continue cleanly.