Agent turn execution
An agent turn is one complete response cycle for a user request. It admits the work for a session, prepares a model-ready request, manages model and tool rounds, then stores and delivers one final result. This page extends the agent runtime overview and connects to model provider integration, context memory and compression, and agent tools and guardrails.
Turn lifecycle
The turn lifecycle moves one request from an admitted session to a durable response. The same transcript supports model calls, tool results, recovery, and later turns.
flowchart TD
A[User request] --> B[Turn admission]
B --> C[Context and request assembly]
C --> D[Preflight size gate]
D --> E[Model call]
E --> F{Response type}
F -->|Retry or recovery| D
F -->|Tool calls| G[Persist and run tools]
G --> H{More model work?}
H -->|Yes| C
H -->|No| I[Finalize turn]
F -->|Final text| I
I --> J[Persist and deliver result]
Turn admission
The turn facade admits one active turn for a session before the conversation loop starts. A durable lease prevents concurrent workers from changing the same transcript, while activity and relay scopes let hosts track cancellation, liveness, and task outcome. The facade returns early when admission is interrupted or times out. References: agent/turn_facade.py• L22-57, agent/turn_facade.py• L79-121, agent/turn_facade.py• L188-216
Turn context
Turn context converts the incoming request and stored history into the working state for the loop. It restores or builds the session prompt, adds the current user turn, prepares memory and hook context, sets budgets, and persists enough state for recovery before the first provider call. References: agent/turn_context.py• L483-500, agent/turn_context.py• L1017-1020, agent/conversation_loop.py• L1553-1593
Request preparation
Each model attempt uses a request-local view of the transcript. This view can include current-turn context and provider-specific shaping without changing the durable conversation history except at defined turn or compression boundaries.
Request assembly
Request assembly combines the working transcript with the active system prompt, tools, memory or hook context, and any model-specific additions. It then normalizes the request and creates the provider-facing cache plan so the model sees a consistent message sequence. References: agent/turn_request_assembly.py• L106-127, agent/turn_request_assembly.py• L140-205, agent/turn_request_assembly.py• L232-284
Preflight gate
The preflight gate checks whether the assembled request can fit the active model context. When needed, it grows a managed local window or runs context compression, refunds work that never reached the provider, and stops safely when compression cannot make enough progress. References: agent/turn_preflight_gate.py• L20-101, agent/turn_preflight.py• L57-102, agent/turn_preflight.py• L145-225
Preflight can also run after tool results because tool output increases the next request. That check uses provider usage when available and otherwise uses a route-aware estimate. The context memory and compression page describes the compression system in more detail. References: agent/turn_preflight.py• L244-306, agent/turn_preflight.py• L347-428
Model interaction
After the request passes preflight, the loop makes a provider call and treats the response as a controlled state transition. A response can be usable text, tool work, an incomplete output, or a failure that requires recovery.
Model calls
The call phase selects streaming or non-streaming delivery, runs provider middleware, and marks the request as active for interrupt and redirect handling. A user correction that arrives during the call discards the stale response and rebuilds the request from the correction. References: agent/turn_api_call.py• L47-65, agent/turn_api_call.py• L68-157
Retry and recovery
The retry loop surrounds each provider attempt with rate-limit checks, request creation, the model call, and response validation. Error handling classifies the failure before it chooses a retry, credential recovery, context recovery, provider fallback, or terminal result. Restart signals cause the outer loop to rebuild the request instead of replaying stale request data. References: agent/conversation_loop.py• L1496-1525, agent/turn_api_error.py• L52-221, agent/turn_retry_state.py• L9-15
Retries are bounded by attempt and iteration budgets. The loop gives special handling to context overflow, incomplete output, malformed responses, content refusal, and user interrupts. It stops rather than sending a request that is known not to fit or cannot be made safe. References: agent/turn_api_error.py• L253-425, agent/turn_response_check.py• L131-218, agent/turn_iteration_prep.py• L437-566
Response routing
Response intake normalizes provider output into the agent’s assistant message shape and records provider hooks and usage. The loop then routes the message to either the tool-round path or the final-text path. Incomplete reasoning and provider-specific incomplete responses can request another call without becoming a false final answer. References: agent/turn_response_intake.py• L120-197, agent/conversation_loop.py• L1663-1677
Tool rounds
Tool rounds extend one user turn across several model calls. The model proposes calls, the agent validates and records them, tools produce results, and the next model request uses those results as new context.
Tool execution
The tool-round path validates the model’s calls and applies tool guardrails before execution. It persists the assistant tool-call message before running side effects, then records tool results and stops the turn if persistence or a guardrail halt prevents safe continuation. References: agent/turn_tool_round.py• L46-81, agent/turn_tool_round.py• L87-150, agent/turn_tool_round.py• L163-190
Tool policy and dispatch are shared with the wider tool system. See agent tools and guardrails for the capabilities and safety rules that apply inside this round. References: agent/turn_tool_round.py• L93-127, agent/turn_tool_round.py• L202-230
Tool continuation
After successful tool execution, the loop may compact the expanded transcript and then returns to request assembly. It keeps the current user-turn boundary aligned after compaction so new context and results remain attached to the correct turn. References: agent/turn_tool_round.py• L192-230, agent/turn_preflight.py• L244-360, agent/turn_context_compaction.py• L116-123
Turn completion
Completion turns the loop’s working state into a durable, host-readable result. It must preserve what the user saw, close the transcript with a valid assistant boundary, and report whether the turn completed, failed, or was interrupted.
Final response
The final-text path removes temporary retry scaffolding and applies stop gates before it accepts a response. It can ask the model to continue after an empty answer, a dropped tool call, a truncated answer, or an acknowledgement that did not complete the task. Once accepted, it transforms and flushes the response before leaving the loop. References: agent/turn_final_response.py• L56-68, agent/turn_final_response.py• L130-249, agent/turn_final_response.py• L320-376
Finalization
Finalization resolves budget fallbacks, recovers streamed text when needed, shapes the transcript tail, persists the session, and runs post-turn hooks. It assembles a result envelope with the final response, transcript, usage, model route, completion state, and failure information. Cleanup errors are reported without replacing a response that is already available. References: agent/turn_finalizer.py• L522-634, agent/turn_finalizer.py• L684-752
Result delivery
The public conversation entry point stamps the result with the current-turn boundary and closes failed turns that would otherwise leave a user-only durable tail. The facade then releases leases and scopes, while simple callers receive the result’s final_response string. References: agent/conversation_loop.py• L1694-1745, agent/conversation_loop.py• L1792-1835, agent/turn_facade.py• L218-220
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to request assembly must preserve the separation between the durable transcript and the provider-facing request copy. This affects prompt caching, replay, and context-size checks.
- Changes to tool execution must keep the persist-before-side-effect order and the matching assistant tool-call and tool-result rows.
- Changes to retry or fallback paths must preserve restart signals so the next request is rebuilt with the active provider, context, and user correction.
- Changes to finalization must keep the result envelope, durable assistant boundary, and current-turn boundary aligned for every terminal path.
- Changes to compression or transcript rewriting must re-anchor the current user turn before later context injection or delivery.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The request remains over the model window after compression | The provider call is not sent, and the turn ends with context-recovery guidance | Preflight fail-closed checks and bounded compression attempts |
| Tool-call persistence fails before execution | Side effects are skipped, and the turn reports a persistence failure | Persist the assistant tool-call block before dispatch |
| A user correction crosses an in-flight model call | The stale response is discarded and the turn is rebuilt from the correction | Redirect state and restart signals |
| The model returns a malformed or empty response repeatedly | Retries and fallbacks end in a failed result instead of an endless loop | Response-shape checks, retry limits, and fallback routing |
| The loop ends after a tool result with no final text | The transcript could leave the next request with an invalid or silent tail | Finalization adds a visible completion boundary and explanation |
Key files
| File | Why to read it |
|---|---|
| agent/turn_facade.py | Shows turn admission, lease ownership, scopes, and the caller-facing boundary |
| agent/conversation_loop.py | Shows the high-level phase order and the public result path |
| agent/turn_context.py | Shows how one user request becomes turn state and how API messages are built |
| agent/turn_request_assembly.py | Shows the request-local model payload and pressure measurement |
| agent/turn_preflight.py | Shows context-size checks and compression before or after model work |
| agent/turn_api_call.py and agent/turn_api_error.py | Show provider calls, interrupts, retries, and fallback decisions |
| agent/turn_tool_round.py | Shows validation, durable tool-call staging, execution, and continuation |
| agent/turn_final_response.py | Shows acceptance and recovery of a final text response |
| agent/turn_finalizer.py | Shows persistence, result assembly, delivery metadata, and post-turn cleanup |