LLMAgent.run() submits a Task to an agent’s processing loop. It creates a TaskHandler and schedules the loop as a background asyncio.Task. Although run() is not itself an async coroutine, it returns the handler, an asyncio.Future subclass that can be awaited for a TaskResult. section 4.1 section 4.5
A Task carries an id_ and instruction; its TaskResult carries a task_id and content. The initial interface accepts an optional max_steps limit, allowing callers to bound the number of sub-steps. section 4.1 section 4.2.3
The processing loop delegates execution to TaskHandler:
- Call get_next_step() with the previous TaskStepResult, if one exists. It returns either a TaskStep or a completed TaskResult. section 4.2.3
- For a TaskStep, call run_step() and use its result in the next cycle. Each sub-step’s chat history is formatted and appended to the handler’s rollout. section 4.2.3
- Finish when a TaskResult is produced, or stop on a condition such as an irrecoverable error or the maximum sub-step count. section 4.2.3
Callers can await agent.run(task) directly, or retain the handler to inspect its rollout and check done(). Calling handler.result() before completion raises InvalidStateError. section 4.3
Run a tool-assisted task
For a Hailstone task starting at 4, submit the Task with handler = llm_agent.run(task, max_steps=5). After the handler completes, handler.result() yields a TaskResult whose content is 4 → 2 → 1. The rollout records the calls to next_number for 4 and 2. section 4.3
Extensions add capabilities at task-run boundaries. Skill discovery occurs when the handler is constructed, with skills_scopes and explicit_only_skills forwarded by run(). With configured memories, the loop loads recalled episodes and records task execution. The optional with_approval flag requests human review of a proposed result; rejection feeds operator feedback back into the loop. section 6.3.3 section 7.5.2 section 8.3.1
Figure 8.9 The sequence of interactions between a human operator, LLMAgent, and the TaskHandler it dispatches for carrying out the Result-Approval HITL pattern

Trace the handoff from task execution to human review and the approval or rejection paths. section 8.3.1
