agents — ReAct/MRKL agents, AgentExecutor, plan-and-execute

ReAct Tool-using Iterative 17 sub-modules

Architecture

flowchart LR
  subgraph Core["langchain_classic/agents/"]
    BASE["Base abstraction"]
    IMPLS["Concrete implementations"]
    BASE --> IMPLS
  end
  subgraph Up["Upstream callers"]
    U1["chains/"]
    U2["agents/"]
  end
  subgraph Down["Downstream"]
    D1["langchain_core"]
    D2["External providers"]
  end
  Up --> Core
  Core --> Down

Data Flow

sequenceDiagram
  participant Caller as Caller
  participant Agents as agents
  participant Core as langchain_core
  participant Ext as External
  Caller->>Agents: invoke(input)
  Note over Agents: Validate & route
  Agents->>Core: delegate primitive
  Core->>Ext: provider call
  Ext-->>Core: response
  Core-->>Agents: typed output
  Agents-->>Caller: result

Existence rationale

agents/ packages the act-observe-think loop that turns an LLM into a tool-using agent. Where a Chain runs a fixed pipeline, an Agent returns either "call this tool with these args" or "we're done, here's the final answer", and AgentExecutor runs that decision in a loop, accumulating a trajectory of (action, observation) pairs. Without agents/, library users would have to hand-write the parse → tool-dispatch → re-prompt cycle, which is exactly the boilerplate that distinguishes ReAct, MRKL, OpenAI Functions, OpenAI Tools, Structured Chat, and JSON Chat agents from one another. The module exists to (a) capture that loop once, (b) make agent flavours interchangeable behind a single executor, and (c) provide streaming via AgentExecutorIterator.

Design decisions visible in the code

Algorithm deep-dives

1. The agent loop (AgentExecutor._call)

Problem. Run an agent until it returns AgentFinish or hits an iteration / time cap, while invoking the right tool, propagating callbacks, and streaming intermediate state.

Trace.

1. Initialise intermediate_steps: list[tuple[AgentAction, str]] = [].
2. Loop:
3. Build prompt inputs {"input": q, "intermediate_steps": intermediate_steps, "tool_names": tool_names, "tools": tools_doc}.
4. The agent (a Runnable) runs prompt-formatter → LLM → output-parser → returns AgentAction|AgentFinish.
5. If AgentFinish: call on_agent_finish, return outputs.
6. Else for each AgentAction:

• tool = name_to_tool[action.tool]; if missing → InvalidTool returns an error string instead of raising (so the LLM can self-correct).
• observation = tool.run(action.tool_input) (sync) or arun (async). Wrapped in on_tool_start/end/error.
• Append (action, observation) to intermediate_steps.

1. Check iterations >= max_iterations or time_elapsed >= max_execution_time → return_stopped_response(early_stopping_method).
2. Output dict has output, optionally intermediate_steps.

Complexity. Per iteration: 1 LLM call + N tool calls (1 for single-action, ≥1 for multi). Total iterations bounded by max_iterations (default 15).

Why this design. The executor is stateless across calls — all state flows through intermediate_steps. This makes the agent serialisable mid-run for retry, makes streaming trivial (the iterator just yields after each step), and lets users implement custom termination by subclassing AgentExecutor and overriding _should_continue.

Edge cases.

• OutputParserException during parsing: if handle_parsing_errors=True (or a callable), error message becomes an observation and loop continues; else propagates.
• Tool not found: returns the error as observation (prevents fatal exception from a hallucinated tool name).
• early_stopping_method="generate": a final LLM call constructs a graceful answer from the trajectory.
• return_intermediate_steps=True: full trajectory in output dict (used by tracing / eval).

2. Scratchpad formatting (format_scratchpad/)

Problem. Different agent prompts expect different serialisations of the running trajectory. ReAct expects plaintext (Thought: … Action: … Observation: …), OpenAI tools expects a list of ToolMessage objects, XML expects <tool_input> tags.

Solutions.

• format_log_to_str — ReAct text format
• format_to_openai_function_messages, format_to_openai_tool_messages — convert to chat messages
• format_xml, format_log_to_messages — XML and structured chat variants
• format_to_tool_messages (Claude tools)

The agent's prompt template references {agent_scratchpad}; the chosen formatter is the only thing that varies per flavour.

3. Output parsing (agents/output_parsers/)

Problem. Convert raw LLM text → AgentAction|AgentFinish.

ReAct (react_single_input.py):

1. Look for Final Answer: → AgentFinish(return_values={"output": text_after}).
2. Else regex Action: <tool>\nAction Input: <input> → AgentAction(tool, input, log=raw_text).
3. Both miss → OutputParserException (caller decides recovery).

OpenAI tools (openai_tools.py): no parsing — the LLM has already produced structured tool_calls; convert directly.

JSON Chat (json.py): expect {"action": "...", "action_input": ...} blob; parse with json.loads, fall back to parse_json_markdown for fenced blocks.

XML (xml.py): regex <tool>name</tool><tool_input>...</tool_input> → AgentAction.

Why pluggable. Each format makes the LLM more or less reliable depending on training data — Claude does best with XML, OpenAI tool-tuned models do best with native tools, smaller open models often ground better in JSON. The parser is interchangeable behind AgentOutputParser.

Error philosophy

Tolerate parser errors when configured; surface tool errors but feed them back as observations. The default behaviour is propagate (so the user notices), but handle_parsing_errors=True flips into a self-correct mode where the LLM sees its own mistake on the next iteration. This trades safety for autonomy — explicit opt-in.

InvalidTool (a built-in Tool returned when the LLM picks a non-existent name) is the cleanest example: the LLM hallucinated a tool, so we return "Tool X not found. Available tools: …" as the observation instead of crashing.

Performance characteristics

• Latency dominator: the LLM call inside the loop. With max_iterations=15 a worst-case agent run is 15× single-LLM latency.
• Optimisation lever: parallel tool calls (multi-action agents like OpenAI tools), which cut wall-clock for fan-out queries roughly N×.
• Streaming: AgentExecutorIterator yields after each step so a UI can show the chain-of-thought as it grows.
• Memory profile: intermediate_steps keeps every observation in memory; long-running agents with verbose tools (HTML scraping) can spike RAM.

Evolution clues

• The legacy AgentType enum + initialize_agent is gradually being replaced by create_*_agent factories that return Runnables. create_react_agent, create_openai_tools_agent, create_structured_chat_agent, create_tool_calling_agent, create_json_chat_agent, create_xml_agent, create_self_ask_with_search_agent all live next to their legacy class-based equivalents.
• tool_calling_agent/ is the newest and is provider-agnostic (works with any LLM exposing bind_tools) — the others are flavour-specific.
• openai_assistant/ wraps the OpenAI Assistants v2 API as a Runnable that sits outside the standard executor loop (the assistant handles the loop server-side).
• Naming inconsistencies (openai_functions_agent vs openai_functions_multi_agent vs openai_tools vs tool_calling_agent) reflect OpenAI's own API evolution: text → functions → parallel tool calls.

Step-by-Step Walkthrough

What Could Go Wrong

Performance Profile

Directory Map

agents/
├── __init__.py
├── agent.py
├── agent_iterator.py
├── agent_toolkits/
├── agent_types.py
├── chat/
├── conversational/
├── conversational_chat/
├── format_scratchpad/
├── initialize.py
├── json_chat/
├── load_tools.py
├── loading.py
├── mrkl/
├── openai_assistant/
├── openai_functions_agent/
├── openai_functions_multi_agent/
├── openai_tools/
├── output_parsers/
├── react/
├── schema.py
├── self_ask_with_search/
├── structured_chat/
├── tool_calling_agent/
├── tools.py
├── types.py
├── utils.py
└── xml/