Refactor create_react_agent to use internal _AgentBuilder helper class

[Copilot]

This PR refactors the create_react_agent function to use an internal _AgentBuilder helper class, addressing maintainability and readability issues with the original implementation.

Problem

The create_react_agent function had grown to over 700 lines of complex, intertwined logic that was difficult to maintain, understand, and modify. The function handled multiple responsibilities including:

• Model and tool integration
• State schema management
• Prompt handling
• Node construction for LLM interaction
• Structured output generation
• Hook management (pre/post model)
• Complex routing logic
• Graph assembly

Solution

This refactoring introduces an internal _AgentBuilder class that encapsulates and organizes the agent construction logic into focused, manageable methods:

Core _AgentBuilder Methods

• __init__: Parameter validation and initialization
• _setup_model_and_tools(): Model resolution and tool binding
• _create_model_node(): Core LLM interaction node creation
• _create_structured_response_node(): Structured output formatting
• _create_model_router(): Execution flow routing after model calls
• _create_tools_router(): Post-tool-call routing for return_direct behavior
• _setup_hooks(): Pre/post model hook integration
• build(): Final graph assembly and compilation

Key Benefits

1. Improved Maintainability: Logic is now organized into focused methods with clear responsibilities
2. Enhanced Readability: The create_react_agent function is now just 25 lines vs 700+ lines
3. Better Testability: Individual components can be tested in isolation
4. No Breaking Changes: The public API remains exactly the same
5. No Unnecessary Abstractions: The helper class is internal and focused solely on organization

Example

The refactored create_react_agent function now simply delegates to the builder:

def create_react_agent(...) -> CompiledStateGraph:
    """Creates an agent graph that calls tools in a loop until a stopping condition is met."""
    builder = _AgentBuilder(
        model=model,
        tools=tools,
        prompt=prompt,
        response_format=response_format,
        # ... all other parameters
    )
    return builder.build()

The _AgentBuilder class handles all the complex logic internally while maintaining the exact same functionality and behavior.

Fixes #5692.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

1 Skipped Deployment

Name	Status	Preview	Comments	Updated (UTC)
langgraph-docs-preview	⬜️ Ignored (Inspect)	Visit Preview		Jul 29, 2025 0:36am