Filter 7: agentic_loop

[leseb]

Purpose

Manage the agentic inference loop lifecycle for the Responses API. Observes whether tool calls are present in the response, checks exit conditions, manages iteration state, and signals via filter_results whether to loop back for another inference round or exit to the client.

Does not classify tool calls by type or execute them — classification is handled by tool_parse; execution by sub-filters routed via branch chains.

Behavior

• Read state.tool_calls from ResponsesState
• If no tool calls → set action = "done", exit loop
• Check exit conditions:
  • Response finish_reason == "length" / status == "incomplete" → exit as incomplete
  • Request-level max_tool_calls reached → exit as incomplete
  • Iteration limit reached (max_infer_iters) → exit as incomplete
• If tool calls present and no exit condition:
  • Increment state.iteration
  • Reset tool_choice to "auto" after first iteration
  • Set action = "loop" to signal branch chain re-entry
• Loop control via filter_results + branch chain re-entrance:
  • agentic_loop.action = "loop" — branch re-enters at responses_proxy
  • agentic_loop.action = "done" — exit loop

Branch Chain Re-entrance

The loop is driven by praxis-core's ReEnter rejoin mode (proposal #36, released). A branch chain on agentic_loop matches action = loop and rejoins at the named responses_proxy filter:

- filter: responses_proxy
  name: inference
- filter: agentic_loop
  max_infer_iters: 10
  branch_chains:
    - name: tool-loop
      on_result:
        filter: agentic_loop
        key: action
        result: loop
      rejoin: inference
      max_iterations: 15
      chains:
        - name: tool-execution
          filters:
            - filter: headers
              request_add:
                - name: X-Agentic-Loop
                  value: "true"

Two iteration limits serve complementary purposes:

• max_infer_iters (filter config) — application-level cap that marks the response as incomplete when reached
• max_iterations (branch chain) — infrastructure-level safety cap that prevents infinite loops; should be ≥ max_infer_iters

Architectural Decision

Renamed from tool_dispatch to agentic_loop to reflect its role as a pure loop controller. Classification (client vs server tool calls) and execution are intentionally excluded — those responsibilities belong to tool_parse and sub-filters routed via branch chains. This avoids duplication between the loop controller and the classify→route→execute pipeline.

Config

filter: agentic_loop
max_infer_iters: 10

Praxis trait methods

• on_request — check tool calls, exit conditions, manage iteration state, set loop signal

Branch chains only evaluate on_result conditions during the request phase (after on_request), so all loop control must happen here. On the first pass, tool_calls is empty and the filter signals done. After stream_events/tool_parse populate tool_calls during response-body processing, the branch chain re-enters the pipeline and on_request runs again with populated tool calls.

Dependencies

• ResponsesState in request extensions (created by openai_responses_validate for all Responses API create requests)
• Branch chain re-entrance in praxis-core (proposal Filter 17: chat_completions_to_responses_sse #36, released)
• tool_parse for tool call classification (future)
• Tool execution sub-filters routed via branch chains (future)

Reference

• Proposal: Responses API Filters — Filter 7
• Part of Epic: Responses API and Agentic Loop Orchestration #93

[leseb]

Design note: concurrent write safety

Tool dispatch is the first consumer that creates concurrent writes to the conversation store — multiple server-side tool calls in a single turn can complete in parallel and need to append results to the same conversation.

The current ConversationRecord with INSERT OR REPLACE on a single JSON blob is last-writer-wins under concurrency. When implementing tool dispatch, the store should use append-only item rows instead of overwriting the blob. This also needs transactions to atomically persist tool results + updated response state.

See #19 comment for the full schema normalization path.

[leseb]

Note: terminal-event reconciliation for tool_calls

The stream_events accumulator (landed in #433) incrementally builds state.tool_calls from function_call_arguments.delta/done SSE events. However, when a terminal event (response.completed) arrives, handle_terminal_event overwrites response_object, output_items, and usage from the authoritative payload — but does not rebuild or clear state.tool_calls.

This means tool_calls can be stale (accumulated from deltas) while output_items reflects the terminal truth.

When implementing tool_dispatch, either:

1. Derive tool calls from state.output_items at dispatch time (preferred — single source of truth), or
2. Make terminal handling also replace state.tool_calls from the terminal event's output function-call items.

See: apis/src/openai/responses/stream_events/accumulator.rs, handle_terminal_event.