# `Dsxir.Predictor.ReAct`

Tool-using agent predictor. Drives a per-step `Predict` loop until the model
emits `next_tool_name: "finish"` or `:max_iters` is reached.

## Declaration

    predictor :agent, Dsxir.Predictor.ReAct,
      signature: MySig,
      tools: [calculator_tool, web_search_tool],
      max_iters: 8

## Trace shape

Each iteration pushes one trace entry under the outer predictor's name. The
step `inputs` map carries the rendered `:trajectory` string plus the original
user inputs; the step `prediction` is a `%Dsxir.Prediction{}` with
`next_thought`, `next_tool_name`, `next_tool_args`. `Dsxir.Module.Runtime.call/4`
additionally records the outer entry with the final prediction. Both layers
are intentional — the outer entry is a legitimate compound demo candidate.

## `trace_name` and bootstrap optimization

The default `trace_name: :react` keeps per-step entries separate from any
user-declared predictor. Setting `trace_name:` to the same atom as the
declared predictor (e.g. `trace_name: :agent` when the predictor is
`:agent`) makes the step entries land in the same `demos_pool` slot as the
outer entry under bootstrap optimization. Step-shape demos and outer-shape
demos render differently in the prompt and the bootstrap optimizer will not
reshape them; collision is a footgun. Keep `trace_name` distinct from any
declared predictor name.

## Errors

Tool exceptions are caught inside the loop and surfaced as
`"Execution error in {tool}: {message}"` observations. Exhausting
`:max_iters` raises `Dsxir.Errors.Framework.PredictorError` with the full
trajectory attached.

---

*Consult [api-reference.md](api-reference.md) for complete listing*