How does LlamaIndex AgentRunner add structure over a bare ReAct loop?

Attempt it

AgentWorker holds the per-step logic. Given current state and message history, decide one next action (think, call tool, finish). AgentRunner orchestrates: it owns the Task, drives the worker step by step, persists task state between steps, supports inspection / resumption of a Task by id, and exposes a clean run_step / arun_step surface so you can interleave human review between steps. A bare ReAct while-loop conflates 'decide one step' with 'drive to completion'. You cannot pause it cleanly, you cannot inspect partial state, and you cannot swap the per-step logic without rewriting the loop. The runner/worker split is essentially the same separation LangGraph makes between the executor and a node. Control loop separate from per-step decision.

Your answer

Quick reference

TL;DR

AgentWorker decides one step; AgentRunner owns the Task, persists state between steps, and exposes pause resume inspect controls a bare ReAct while-loop cannot offer.

Memory aid

Sign in for the mnemonic that makes this stick. See Pro pricing.

Easy to grasp

Imagine a chess engine and a chess clock. The engine knows how to pick the next move given the current board. The clock knows whose turn it is, when to pause, and how to resume a game from a saved position. If you smash both into one program, you have a chess bot that always plays start to finish in one go. You cannot stop it mid-game, you cannot review the moves before the next one, and you cannot swap in a different engine without rewriting the clock. LlamaIndex's AgentWorker is the engine; AgentRunner is the clock plus the saved-game folder. Keeping them separate lets you do things a bot smashed into one program cannot.

Key concepts

LLM Frameworks Agents

Quick scan · 2–4 min

Everything important, quickly.

7 min: worker role, runner role, four capabilities the split unlocks, durable Task ids, parallel with LangGraph executor/node, generalisation in Workflows.

Code example

python

from llama_index.core.agent import ReActAgentWorker, AgentRunner
from llama_index.llms.openai import OpenAI

worker = ReActAgentWorker.from_tools(tools, llm=OpenAI(model="gpt-5.5"))
runner = AgentRunner(worker)

# Create the task; do not drive to completion yet
task = runner.create_task("Research X, draft a one-page brief.")

# Advance one step at a time, interleaving human review
step_output = runner.run_step(task.task_id)
print("after step:", runner.get_completed_steps(task.task_id))

if user_approves(step_output):
    while not step_output.is_last:
        step_output = runner.run_step(task.task_id)

result = runner.finalize_response(task.task_id)

Real-world examples

Real products, models, and research that use this idea.

LlamaIndex's official ReActAgent demos use the runner/worker split as the canonical pattern. The bare loop only appears in 'minimal' examples
Production document-QA agents pair LlamaIndex AgentRunner for stepped tool-use with custom human-approval gates between steps
LlamaIndex Workflows (the newer event-driven API) generalises the same orchestration vs decision separation into a Step decorator model

Interviewer follow-ups

What an interviewer would ask next. Try answering before peeking at the approach.

QHow does LlamaIndex Workflows generalise the runner/worker pattern?

Sign in or go Pro to see the approach for this follow-up.

QWhen would you write a custom AgentWorker rather than use ReActAgentWorker or FunctionCallingAgentWorker?

Sign in or go Pro to see the approach for this follow-up.

QHow does AgentRunner interact with LlamaIndex Tools and ToolMetadata?

Sign in or go Pro to see the approach for this follow-up.

60-second cheat sheet

The night-before-the-interview bullets. Scan these on the way to the call.

Sign in for 5 unlocks/day or go Pro for unlimited revision sheets. See Pro pricing.

References

Primary sources. Skim if you want the original framing.