Skip to slide
016 / 170

CH 02 · The Agent Loop · 04/11

Read as one page

Real 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. [1] No counter. A lap takes queued messages only when can_drain_pending_input is true. Your opening request sets that flag false (input is not empty), so it is sampled first.
  2. [2] clone_history() copies the conversation. A ResponseItem is 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_prompt shapes the copy for this model: it pairs calls with outputs, and it strips images or audio when that input is off.
  3. [3] run_sampling_request sends the list and handles the reply. If the stream fails, this function can retry before returning the error.
  4. [4] Go round again if the model asked for more work, or if you typed something during the lap.
  5. [5] Otherwise break returns control to you. A stop hook in the elided lines can add a prompt and force one more lap.
  6. [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_flight in turn.rs waits for those futures and records each successful output. A future that fails is logged and not written into the history.
  7. [7] A message or reasoning item does not by itself set needs_follow_up. Assistant text is stored in last_agent_message only 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 sets needs_follow_up. A completed response with end_turn false 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.