The agent loop & events
The small engine at Tau's center, and the event stream every frontend renders.
The agent loop is the small, reusable engine that turns messages, tools, and provider streams into a flow of progress events. It’s the part that makes something an agent rather than a chat box.
What the loop does
For each turn, the loop:
- takes the current system prompt, transcript, tools, and model selection;
- asks the provider to stream a response;
- emits events as text and tool calls arrive;
- collects the assistant message;
- executes any requested tools;
- appends the tool results to the transcript;
- continues according to tool results, queued messages, and the host’s optional
finish_turndecision.
That “call a tool, feed the result back, continue” cycle is what lets the model read a file, see its contents, and then decide what to edit.
Terminating tool results
Normally a tool call causes another model request. A tool can instead return
AgentToolResult(..., terminate=True) to submit a final answer without that
follow-up. As in Pi, a nonempty batch terminates only when every final result
opts in, after tool-result hooks. All sibling tools finish first; partial updates
have no effect. Mixed batches continue, and queued steering/follow-up messages
still receive responses. The flag stays in tool-execution events, not transcript
messages. See final submissions.
Host-controlled turn finalization
The portable AgentHarnessConfig and run_agent_loop() accept finish_turn.
This callback runs after the assistant and tool results have been appended, but
before TurnEndEvent. For example, stop whenever a submission succeeds, even
in a mixed batch and even with queued work:
from tau_agent import AgentHarnessConfig, AgentTurnContext, AgentTurnDecision
from tau_agent.provider import CancellationToken
def finish_turn(
turn: AgentTurnContext, signal: CancellationToken | None
) -> AgentTurnDecision | None:
if turn.message.stop_reason in {"error", "aborted"}:
return None
if any(
result.tool_name == "submit_results" and not result.is_error
for result in turn.tool_results
):
return AgentTurnDecision(action="end")
return None
config = AgentHarnessConfig(
provider=provider, model=model, system=system, tools=tools,
finish_turn=finish_turn,
)
The callback may be synchronous or asynchronous. It receives the active
cancellation token (or None for a direct loop without one) and an
AgentTurnContext with:
message: the finalized assistant response;tool_results: a tuple of the turn’s finalized transcript tool results;messages: a tuple of the full transcript at this boundary;new_messages: a tuple of this invocation’s messages, including prompt messages but excluding earlier history.
These are shallow snapshots: tuples prevent list edits, but their message objects are shared, not deep-copied. Treat them as read-only.
Return None to preserve normal scheduling, or:
AgentTurnDecision(action="end"): emitturn_end, thenagent_endwithout polling steering/follow-up queues again. Queued messages remain available for a later run. This is a successful finish, not cancellation.AgentTurnDecision(action="continue"): ensure one subsequent model request. If tools, steering, or a follow-up already select that request, they satisfy the decision; there is no extra duplicate request. Otherwise it is a context-only request. This can also override a terminating tool batch.
The callback runs for error and aborted responses too, including synthetic
cancellation and turn-limit messages, but their decisions are ignored: those
remain hard exits. Repeated continue decisions can run indefinitely unless
max_turns or cancellation stops them. Callback exceptions propagate to the host;
they are not a graceful stop mechanism, and the harness resets its running state
on exit.
This is Pi’s finishTurn scheduling contract with Python names and typed
dataclasses. It is a harness API, not a CodingSessionConfig option or extension
hook. No frontend or provider-specific policy is required in the agent core.
What the loop does not do
The loop knows nothing about CLI arguments, Textual widgets, session file
locations, or resource discovery. Those belong to tau_coding. Keeping them out
is what makes the loop reusable across every frontend.
Event-first design
Every meaningful step is observable as an event, so print mode, Rich rendering,
and the Textual TUI all share the same core. Frontends render from these
provider-neutral events — never from raw provider chunks. The portable tau_agent.events.AgentEvent stream contains:
AgentStartEvent/AgentEndEvent— a run begins / endsTurnStartEvent/TurnEndEvent— one assistant response and its tool resultsMessageStartEvent/MessageUpdateEvent/MessageEndEvent— a message’s Pi-compatible lifecycleToolExecutionStartEvent/ToolExecutionUpdateEvent/ToolExecutionEndEvent— a tool runs
Streaming detail is nested under
MessageUpdateEvent.assistant_message_event. Those provider-neutral nested
events cover text, thinking, and tool-call start/delta/end updates. Provider
completion or failure is represented by the final assistant message delivered
through MessageEndEvent.
tau_coding.events.CodingSessionEvent extends that portable stream for
frontends and SDK users with agent_settled, queue updates, compaction,
session-entry/session-info changes, thinking-level changes, and automatic-retry
events. Extensions observe those same event names, but the session-to-extension
adapter enriches turn_start with a zero-based turn_index and millisecond
timestamp, and turn_end with the matching index. See
Extensions for their complete
payload table.
The final AssistantMessage is authoritative: it persists text, thinking, and tool
calls as ordered content blocks. Nested update events provide responsive rendering,
while saved sessions and provider history replay use the finalized structured message.
It also carries optional monotonic response timing: accumulated time awaiting
provider events through completion and through the first text, thinking, or
tool-call output. Measuring only provider-event awaits excludes frontend rendering
and persistence work between stream pulls. Saved usage and timing remain paired for
effective output-speed and TTFT statistics.
Its provider field names Tau’s configured provider. When a gateway reports a
more specific backend, response_provider records the backend that served that
request. For example, Hugging Face responses expose the selected Inference
Provider there while provider remains huggingface.
Because the contract is events, a frontend’s job is reduced to: send a prompt, consume the stream, draw what you see.
→ See Build your own frontend for the concrete API, and Architecture overview for where the loop sits.