SupervisedTaskHandler is a TaskHandler subclass for human-controlled, stepwise execution of an LLM agent’s task. Instead of advancing the processing loop automatically, an operator decides when to request and run each step, and can inspect or modify intermediate results. section 8.4 section 8.6
The handler reuses TaskHandler capabilities and adds ways to control task completion:
- Use get_next_step() to obtain the next TaskStep, then run_step() to execute it. Inspect or modify the step and its result before continuing. section 8.4 section 8.4.2
- Call complete(result) to accept a TaskResult, record episodic memory, and resolve the handler. Call reject(result, feedback) to create a RejectedTaskResult for the next step, or abort(error) to end with an exception. section 8.4.1
- The handler retains TaskHandler’s rollout and memory capabilities. It cannot be attached to an automatic background task; accessing or setting background_task raises TaskHandlerError. section 8.4.1
Create the handler through LLMAgent.run_supervised(), which loads memories and returns a SupervisedTaskHandler. Unlike run(), this method omits max_steps and with_approval: the operator oversees progress and can abort execution. A supervised run can also be closed by accepting a result or aborting with an exception. section 8.4.2 section 8.4.1
Supervise a Hailstone sequence
For a task to compute the sequence starting at 4, the operator alternates get_next_step() and run_step(), inspecting results as execution proceeds. When the agent returns a TaskResult with 4, 2, 1, pass it to complete(). section 8.4.2
Figure 8.10 Autonomous task execution advances the processing loop on its own, while supervised task execution gives a human operator full control over invocations of get_next_step() and run_step(), allowing them to pause and inspect or modify intermediate results as needed

Compare autonomous execution with supervised control of get_next_step() and run_step(). section 8.4
