What is an agent runner?
The engine that actually calls the model, runs each tool, and writes down what happened.
Agent runner — An agent runner is the component that executes an agent's steps — calling the model, running tools, handling retries, writing logs — on a schedule or in response to events. It is the engine an agent's behaviour runs on.
Why it matters
An agent's behaviour, the prompts and rules that decide what it does, is only half the system. The other half is whatever actually runs those steps: calling the model, executing the tool calls it returns, retrying a failed step, and writing each action to a log. That component is the agent runner. Without it, an agent is a description of behaviour with nothing to carry it out.
Runners fall into two categories: scheduled ones that wake up at set times, like a daily inbox sweep, and event-driven ones that fire when something happens, like a new reply arriving. Either way, a run has to survive being interrupted partway through, whether that is a server restart or a network failure mid-call. A runner built to be resumable can pick a run back up where it stopped; one that is not has to start over, which risks repeating actions like a duplicate email. Running agents from a single long-lived process on someone's laptop fails both tests: it is not visible to the rest of the team, and it stops the moment the laptop closes.
How an agent runner operates
- 1
A trigger fires
A scheduled time arrives, or an event like a new reply comes in.
- 2
The runner starts a run
Recording that this run began, so it can be tracked and resumed.
- 3
It calls the model and executes tool calls
Each step's result feeds into deciding the next one.
- 4
Failures are retried, not silently dropped
A transient error does not mean the run disappears.
- 5
The run's steps are logged
So a person can see exactly what the agent did and when.
The mistake to watch for
Questions
- How is an agent runner different from a cron job?
- A cron job just fires on a schedule. An agent runner also handles the model calls, tool execution, retries and logging inside each run, and can be triggered by events as well as time.
- What does it mean for a run to be idempotent?
- Running the same step twice, because of a retry after a failure, produces the same result rather than a duplicate action, like sending the same email twice.
- Can a person see what an agent runner is doing right now?
- In a well-built system, yes. Each run and its steps are logged as they happen, not only after the fact, so a stuck or failing run is visible before it becomes a bigger problem.