CH 02 · The Agent Loop · 04/11
Read as one pageReal code: the loop inside Codex's turn.rs
The walk above is one Codex turn. Here is run_turn, the loop in codex-rs/core/src/session/turn.rs. On the next slide you build the same skeleton in Python.
loop { // [1]
// ... (3 lines: a queued message is one you sent while the model was running)
let pending_input = if can_drain_pending_input {
sess.input_queue
.get_pending_input(&sess.active_turn)
.await
.0
} else {
Vec::new()
};
// ... (87 lines: record that input, then capture this lap's tools and settings)
// Construct the input that we will send to the model.
let sampling_request_input: Vec<ResponseItem> = async {
sess.clone_history() // [2]
// ...
run_sampling_request( // [3]
// ... (14 lines: pass the history and a cancel token, then match on success)
let SamplingRequestResult {
needs_follow_up: model_needs_follow_up,
// ... (14 lines: unpack the rest, then collect hook results that finished late)
let has_pending_input =
sess.input_queue.has_pending_input(&sess.active_turn).await;
// ...
let needs_follow_up = model_needs_follow_up || has_pending_input; // [4]
// ... (113 lines: if the history has grown too big, compact it and go round again)
if !needs_follow_up {
last_agent_message = sampling_request_last_agent_message;
// ... (105 lines: stop hooks, which can force one more lap; compaction after the turn)
break; // [5]
}
continue;
Source: openai/codex, codex-rs/core/src/session/turn.rs (Apache-2.0)
match ToolRouter::build_tool_call(item.clone()) {
// ... (1 line: log the call, record it, and queue it)
Ok(Some(call)) => {
// ... (24 lines: tracing, then record the call in the history)
let tool_future: InFlightFuture<'static> = Box::pin(
ctx.tool_runtime
.clone()
.handle_tool_call(call, cancellation_token),
);
output.needs_follow_up = true; // [6]
output.tool_future = Some(tool_future);
}
// ... (1 line: a message or reasoning item, not a tool call)
Ok(None) => {
// ... (36 lines: record the message and show it to the user)
output.last_agent_message = finalized_facts.and_then(|facts| facts.last_agent_message); // [7]
}
Source: openai/codex, codex-rs/core/src/stream_events_utils.rs (Apache-2.0)
What to notice
- [1] No counter. A lap takes queued messages only when
can_drain_pending_inputis true. Your opening request sets that flag false (inputis not empty), so it is sampled first. - [2]
clone_history()copies the conversation. AResponseItemis one history entry. This loop acts on a message, a function call, and that call's output. The type also holds reasoning, web search, compaction, and more.for_promptshapes the copy for this model: it pairs calls with outputs, and it strips images or audio when that input is off. - [3]
run_sampling_requestsends the list and handles the reply. If the stream fails, this function can retry before returning the error. - [4] Go round again if the model asked for more work, or if you typed something during the lap.
- [5] Otherwise
breakreturns control to you. A stop hook in the elided lines can add a prompt and force one more lap. - [6] A tool call is not run inline. It is queued as a future (work that finishes later) and sets
needs_follow_up. After the reply finishes streaming,drain_in_flightinturn.rswaits for those futures and records each successful output. A future that fails is logged and not written into the history. - [7] A message or reasoning item does not by itself set
needs_follow_up. Assistant text is stored inlast_agent_messageonly when the item is an agent message with text. A denied or directly answered tool request, in the next arm of this match, writes that answer into the history and setsneeds_follow_up. A completed response withend_turnfalse forces another lap even if no tool ran.
Read it yourself: in turn.rs, compare the doc comment above run_turn with this chapter's pseudo-code. Then search try_run_sampling_request for end_turn: what happens when the API says the turn is unfinished but no tool was called?
Finished this idea?
Your learning progress stays in this browser.