ReActV2: Production-ready agent module with native FC, semantic history, and forced submit

[isaacbmiller]

ReActV2

A ground-up rewrite of the ReAct agent module with better tool calling, history management, and optimization support.

Key Features

• Better small model support: X model goes form Y % correct to Z % correct. (Mostly enabled by native tool calling favored models aka GPT-oss-20b)
• When you include a tool, GEPA will now optimize it and include it as a native tool call.
• ReACt trajectory is no longer a dict, its a structured object
• Compaction now lets you increase max_iters without running into issues. You can even optimize the compaction step.
• Parallel tool calls
• More ergonomic conversation structure for telling the model when to use tools.
• Chat history continue
• submit function w forced submit
• prompt caching now works for anthropic because the message blocks dont change

out of scope:

• Optimize in a multi (user) turn setting? (idk probably not)
• Restart a trajectory from the middle of a step

Maybe measure:

• Long threads w lots of tools
• Short with few tools - 6-8 turns;
• Tau Banking

Benchmarks

BrowseComp n=50 (gpt-5-nano): v2 native FC vs v2 non-native FC v1

Metric	v1 ReAct (non-native only)	v2 Native FC	v2 non-Native FC
Avg Recall	x	x	x
Submitted	x	x	x
Crashes	x	x	x
parsing failures	x	x	x
Fallbacks to Json Adapter	x	x	x

Tau-Banking (gpt-oss-120b)

TBD

Compaction (qwen3-32b)

On browsecomp, max_iters > x failed before with long context. Now we are able to go N max_iters and see Y increase recall.

Prompt Caching (Haiku 4.5)

Whereas before we would get 0 Anthropic cache utilization, we now get up to X% by including the field: ... in our LM init.

[greptile-apps]

Greptile Summary

This PR introduces ReActV2, a ground-up rewrite of the DSPy ReAct agent with native function calling, a structured semantic history model (InputEvent/ActionEvent/OutputEvent), pluggable compaction, two-tier forced submit, and GEPA support for optimizing tool descriptions.

• New ReActV2 module (dspy/predict/reactv2.py): replaces flat-dict trajectories with typed history events, adds parallel tool calls, a submit tool for explicit termination, and a two-tier forced-submit fallback (forced react call → ChainOfThought extract).
• Semantic history (dspy/adapters/types/history.py): History is now a Pydantic model with discriminated-union events, backward-compatible LegacyEvent wrapping, and a compact_fn hook invoked on ContextWindowExceededError.
• Native FC adapter path (dspy/adapters/base.py, chat_adapter.py): use_native_function_calling=True strips ToolCalls/tools fields from the signature, tags it with __dspy_native_fc__, sends tool schemas to the LM, and takes a dedicated parse path; ToolCalls.model_validate now normalizes OpenAI and Responses API wire formats including JSON-string arguments.

Confidence Score: 3/5

The new non-native FC history formatting appends two consecutive user messages after each tool step, which causes hard API failures on Anthropic and other strict alternating-turn providers.

The core ReActV2 loop, forced-submit tiers, and ToolCalls normalizer are solid and well-tested. The main risk is in Adapter.format(): when a non-native FC call has an open episode, format_conversation_history closes the last ActionEvent with a user-role observation message, and then format() immediately appends user_message_output_requirements as a second consecutive user message. Anthropic's API returns a 400 for this message ordering. Any user running ReActV2 in text/non-native FC mode against Anthropic will see API failures after the first tool step.

dspy/adapters/base.py — the format() method's has_open_episode branch produces consecutive user messages in non-native FC mode.

Important Files Changed

Filename	Overview
dspy/adapters/base.py	New history formatting and native FC preprocessing; consecutive user messages produced in non-native FC mode after each tool observation will break Anthropic and other strict alternating-turn providers.
dspy/predict/reactv2.py	New ReActV2 module with semantic history, two-tier forced submit, and parallel tool calls; submit tool lambda allows unknown args to silently propagate into the final Prediction.
dspy/adapters/chat_adapter.py	Native FC formatting path added; misleading AdapterParseError message when zero str output fields are present in _parse_native_fc.
dspy/adapters/types/history.py	New typed semantic event model (InputEvent, ActionEvent, OutputEvent, LegacyEvent) with backward-compatible coercion and pluggable compaction; logic is clean.
dspy/adapters/types/tool.py	Adds ToolCalls model validator that normalizes OpenAI/Responses-API wire formats, including proper JSON string decoding via json_repair; looks correct.
dspy/clients/lm.py	Fixes _convert_chat_request_to_responses_request loop bug where only the last message was emitted; native FC messages (tool_calls/tool roles) are still not converted for the Responses API path.
dspy/teleprompt/gepa/gepa.py	Extends GEPA to optimize tool descriptions alongside predictor instructions; tool feedback always inherits from the first predictor, which is correct for ReActV2 but fragile for multi-predictor modules.
tests/predict/test_reactv2.py	Comprehensive tests covering submit, history semantics, compaction, native FC format, tool normalization, GEPA integration, and forced-submit tiers; good coverage.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant ReActV2
    participant History
    participant Adapter
    participant LM
    participant Tool

    Caller->>ReActV2: forward(**input_args)
    ReActV2->>History: append_input(input_args)
    loop Each iteration (max_iters)
        ReActV2->>Adapter: format(signature, history, tools)
        Adapter->>LM: chat/FC request
        LM-->>Adapter: next_thought + tool_calls
        Adapter-->>ReActV2: Prediction(next_thought, tool_calls)
        loop Each tool call
            ReActV2->>Tool: __call__(**args)
            Tool-->>ReActV2: result / error
        end
        ReActV2->>History: append_action(thought, tool_calls, observations)
        alt submit tool called successfully
            ReActV2->>History: append_output(result)
            ReActV2-->>Caller: Prediction(history, **result)
        end
    end
    ReActV2->>ReActV2: _forced_submit()
    note over ReActV2: Tier 1 - react with tool_choice=submit
    note over ReActV2: Tier 2 - ChainOfThought extract
    ReActV2-->>Caller: Prediction(history, termination_reason)

Loading

Comments Outside Diff (1)

1. dspy/adapters/base.py, line 285-296 (link)

   Consecutive user messages in non-native FC mode breaks Anthropic (and strict alternating-turn) providers

   When has_open_episode is True and the conversation already contains at least one ActionEvent, format_conversation_history appends the last observation as a {"role": "user", ...} message. Immediately after, user_message_output_requirements is also appended as another {"role": "user", ...} message. Anthropic's API rejects consecutive user-role messages with a 400 error, and any provider that enforces strict turn alternation will also fail.

   Concrete failing path: user calls ReActV2.forward() with a non-native FC adapter (e.g. default ChatAdapter) targeting an Anthropic model, after at least one tool call has been recorded in history. The final messages list becomes […, assistant, user(obs), user(output_req)], which Anthropic rejects.

   Consider merging the observation and output-requirements into a single user message, or appending output_req as a suffix to the last observation message.

_{Reviews (7): Last reviewed commit: "Clean up ReActV2 branch" | Re-trigger Greptile}

[greptile-apps]

Responses API converter silently drops native FC messages

When native function calling is active, the conversation history contains {"role": "assistant", "tool_calls": [...]} messages (no content key) and {"role": "tool", "content": "...", "tool_call_id": "..."} messages. The converter only inspects msg.get("content"), so for assistant FC messages content_blocks is always empty and the entire tool_calls array is silently dropped. For tool role messages, tool_call_id is discarded. Any caller that uses native FC against a Responses API backend (e.g. use_responses_api=True on a reasoning model) will send a malformed request where the model has no memory of what tools it previously called.

for msg in request.pop("messages"):
    content_blocks = []
    c = msg.get("content")
    # assistant FC messages have no "content" → content_blocks stays []
    # tool_calls array is never read
    # tool role messages lose tool_call_id
    input_items.append({"role": msg.get("role", "user"), "content": content_blocks})

The Responses API equivalent for an assistant FC turn is a function_call output item, and for the tool result it is a function_call_output input item. Both require the call_id. The converter needs to handle these shapes before native FC and Responses API can be used together safely.

[greptile-apps]

Submit tool schema maps non-primitive output types to "string", breaking agent termination

_ANNOTATION_TO_JSON_TYPE only covers bare Python primitives (str, int, float, bool, list). For any real generic alias such as list[str], list[MyModel], or a Pydantic model, .get(annotation, "string") falls back to "string" and the submit schema is {"type": "string"}.

When the model later calls submit(answers=["a", "b"]), Tool._validate_and_parse_args runs jsonschema.validate(instance=["a", "b"], schema={"type": "string"}), which raises ValidationError. That is caught and re-raised as ValueError, which forward() catches in the tool-execution except block and records as an error observation (is_error=True). Because the loop checks if tool_call.name == "submit" and not obs.is_error, the submit is silently swallowed and the agent eventually exhausts max_iters without ever terminating — for any signature whose output field is not a bare primitive.

A minimal fix is to use get_origin to produce a richer schema for generic aliases:

from typing import get_origin

def _annotation_to_json_schema(annotation) -> dict:
    origin = get_origin(annotation)
    if origin is list:
        return {"type": "array"}
    return {"type": _ANNOTATION_TO_JSON_TYPE.get(annotation, "string")}