Standard sagents execution mode.

Replaces the separate execute_chain_with_state_updates and execute_chain_with_hitl loops with a single composable pipeline.

Pipeline

1. Call the LLM
2. Check for HITL interrupts (if HumanInTheLoop middleware present)
3. Execute tools
4. Propagate state updates from tool results
5. Check if target tool was called (if until_tool is set)
6. Loop if needs_response is true, or error if until_tool contract violated

Options

• :middleware — Agent's middleware list (for HITL checking)
• :should_pause? — Zero-arity function for infrastructure pause
• :max_runs — Maximum LLM calls (default: 50)
• :until_tool — Tool name (string) or list of tool names. When set, the mode returns {:ok, chain, tool_result} once the target tool is called, or {:error, chain, %LangChainError{}} if the LLM stops without calling it.
• :require_tool_success — Boolean (default false). When true, the mode terminates only when the target tool returns a successful (non-error) result; an error result keeps the loop running so the LLM can correct the call, bounded by :max_runs.

These two are the mode's internal representation. Callers using Sagents.Agent.execute/3 pass the friendlier mutually-exclusive :until_tool / :until_tool_success (each naming the target tool), which are collapsed into the pair above via collapse_until_tool/2.

Pausing with a cause

A pipeline step may pause the run with {:pause, chain, reason} — the 3-tuple sibling of {:pause, chain}, carrying why the step paused (a draining node, an unreachable backing store, whatever the step knows). The mode folds the reason into custom_context.pause_reason and returns the {:pause, chain} shape LLMChain.run/2 documents, so the result also passes the fallback machinery unchanged; the agent layer reads the reason back onto State.pause_reason. A step that pauses with the plain 2-tuple (like check_pause/2) keeps a nil reason.

The 3-tuple is a step-level shape only. A custom mode must not return it from run/2: LangChain.Chains.LLMChain.Mode's run_result() type does not admit it, and it corrupts into a generic error under with_fallbacks: (see Sagents.Mode.Steps.normalize_pause/1). Custom modes that want to report a pause cause should apply normalize_pause/1 to their final result, as this mode does, or set custom_context.pause_reason themselves.