This template showcases a ReAct agent implemented using LangGraph, works seamlessly with LangGraph Studio. ReAct agents are uncomplicated, prototypical agents that can be flexibly extended to many tools.
🎉 Latest v0.2.0 Release: Complete evaluation system and multi-model support! Check the release notes for all new features.
The core logic, defined in src/react_agent/graph.py, demonstrates a flexible ReAct agent that iteratively reasons about user queries and executes actions. The template features a modular architecture with shared components in src/common/, MCP integration for external documentation sources, and comprehensive testing suite.
⭐ Star this repo if you find it helpful! Visit our webinar series for tutorials and advanced LangGraph development techniques.
- SiliconFlow Integration: Complete support for Chinese MaaS platform with open-source models (Qwen, GLM, DeepSeek, etc.)
- Qwen Models: Complete Qwen series support via
langchain-qwqpackage, including Qwen-Plus, Qwen-Turbo, QwQ-32B, QvQ-72B - OpenAI: GPT-4o, GPT-4o-mini, etc.
- OpenAI-Compatible: Any provider supporting OpenAI API format via custom API key and base URL
- Anthropic: Claude 4 Sonnet, Claude 3.5 Haiku, etc.
- Dual Evaluation Framework: Graph trajectory evaluation + Multi-turn chat simulation for comprehensive agent testing
- LLM-as-Judge Methodology: Scenario-specific evaluation criteria with professional assessment systems
- Multi-Model Benchmarking: Compare performance across different model providers and configurations
- LangSmith Integration: Complete evaluation tracking with historical analysis and collaboration features
- Model Context Protocol (MCP): Dynamic external tool loading at runtime
- DeepWiki MCP Server: Optional MCP tools for GitHub repository documentation access and Q&A capabilities
- Web Search: Built-in traditional LangChain tools (Tavily) for internet information retrieval
Note
New in LangGraph v0.6: LangGraph Context replaces the traditional config['configurable'] pattern. Runtime context is now passed to the context argument of invoke/stream, providing a cleaner and more intuitive way to configure your agents.
- Context-Driven Configuration: Runtime context passed via
contextparameter instead ofconfig['configurable'] - Simplified API: Cleaner interface for passing runtime configuration to your agents
- Backward Compatibility: Gradual migration path from the old configuration pattern
- Local Development Server: Complete LangGraph Platform development environment
- 70+ Test Cases: Unit, integration, and end-to-end testing coverage with complete DeepWiki tool loading and execution testing
- ReAct Loop Validation: Ensures proper tool-model interactions
The ReAct agent:
- Takes a user query as input
- Reasons about the query and decides on an action
- Executes the chosen action using available tools
- Observes the result of the action
- Repeats steps 2-4 until it can provide a final answer
The agent comes with web search capabilities and optional DeepWiki MCP documentation tools, but can be easily extended with custom tools to suit various use cases.
See these LangSmith traces to understand how the agent works in practice:
- DeepWiki Documentation Query - Shows agent using DeepWiki MCP tools to query GitHub repository documentation
- Web Search Query - Demonstrates Tavily web search integration and reasoning loop
- Install uv (if not already installed):
curl -LsSf https://astral.sh/uv/install.sh | sh- Clone the repository:
git clone https://github.com/webup/langgraph-up-react.git
cd langgraph-up-react- Install dependencies (including dev dependencies):
uv sync --dev- Copy the example environment file and fill in essential keys:
cp .env.example .env-
Edit the
.envfile with your API keys: -
Define required API keys in your
.envfile:
# Required: Web search functionality
TAVILY_API_KEY=your-tavily-api-key
# Required: If using Qwen models (default)
DASHSCOPE_API_KEY=your-dashscope-api-key
# Recommended: SiliconFlow platform for multi-model support and evaluation
SILICONFLOW_API_KEY=your-siliconflow-api-key
# Optional: OpenAI model service platform keys
OPENAI_API_KEY=your-openai-api-key
# Optional: If using OpenAI-compatible service platforms
OPENAI_API_BASE=your-openai-base-url
# Optional: If using Anthropic models
ANTHROPIC_API_KEY=your-anthropic-api-key
# Optional: Regional API support for Qwen models
REGION=international # or 'cn' for China mainland (default)
# Optional: Always enable DeepWiki documentation tools
ENABLE_DEEPWIKI=trueThe primary search tool uses Tavily. Create an API key here.
The template uses qwen:qwen-flash as the default model, defined in src/common/context.py. You can configure different models in three ways:
- Runtime Context (recommended for programmatic usage)
- Environment Variables
- LangGraph Studio Assistant Configuration
SILICONFLOW_API_KEY=your-siliconflow-api-keyGet your API key: SiliconFlow Console - Supports Qwen, GLM, DeepSeek and other open-source models
OPENAI_API_KEY=your-openai-api-keyGet your API key: OpenAI Platform
ANTHROPIC_API_KEY=your-anthropic-api-keyGet your API key: Anthropic Console
DASHSCOPE_API_KEY=your-dashscope-api-key
REGION=international # or 'cn' for China mainlandGet your API key: DashScope Console
OPENAI_API_KEY=your-provider-api-key
OPENAI_API_BASE=https://your-provider-api-base-url/v1Supports SiliconFlow, Together AI, Groq, and other OpenAI-compatible APIs.
Extend the agent's capabilities by adding tools in src/common/tools.py:
async def my_custom_tool(input: str) -> str:
"""Your custom tool implementation."""
return "Tool result"
# Add to the tools list in get_tools()Integrate external MCP servers for additional capabilities:
- Configure MCP Server in
src/common/mcp.py:
MCP_SERVERS = {
"deepwiki": {
"url": "https://mcp.deepwiki.com/mcp",
"transport": "streamable_http",
},
# Example: Context7 for library documentation
"context7": {
"url": "https://mcp.context7.com/sse",
"transport": "sse",
},
}- Add Server Function:
async def get_context7_tools() -> List[Callable[..., Any]]:
"""Get Context7 documentation tools."""
return await get_mcp_tools("context7")- Enable in Context - Add context flag and load tools in
get_tools()function:
# In src/common/tools.py
if context.enable_context7:
tools.extend(await get_context7_tools())Tip
Context7 Example: The MCP configuration already includes a commented Context7 server setup. Context7 provides up-to-date library documentation and examples - simply uncomment the configuration and add the context flag to enable it.
Use the new LangGraph v0.6 context parameter to configure models at runtime:
from common.context import Context
from react_agent import graph
# Configure model via context
result = await graph.ainvoke(
{"messages": [("user", "Your question here")]},
context=Context(model="openai:gpt-4o-mini")
)Set the MODEL environment variable in your .env file:
MODEL=anthropic:claude-3.5-haikuIn LangGraph Studio, configure models through Assistant management. Create or update assistants with different model configurations for easy switching between setups.
Model String Format: provider:model-name (follows LangChain init_chat_model naming convention)
# OpenAI models
"openai:gpt-4o-mini"
"openai:gpt-4o"
# SiliconFlow models (Chinese MaaS platform)
"siliconflow:Qwen/Qwen3-8B" # Qwen series efficient model
"siliconflow:THUDM/GLM-4-9B-0414" # GLM series chat model
"siliconflow:THUDM/GLM-Z1-9B-0414" # GLM reasoning-enhanced model
# Qwen models (with regional support)
"qwen:qwen-flash" # Default model
"qwen:qwen-plus" # Balanced performance
"qwen:qwq-32b-preview" # Reasoning model
"qwen:qvq-72b-preview" # Multimodal reasoning
# Anthropic models
"anthropic:claude-4-sonnet"
"anthropic:claude-3.5-haiku"Update the system prompt in src/common/prompts.py or via the LangGraph Studio interface.
Adjust the ReAct loop in src/react_agent/graph.py:
- Add new graph nodes
- Modify conditional routing logic
- Add interrupts or human-in-the-loop interactions
Runtime configuration is managed in src/common/context.py:
- Model selection
- Search result limits
- Tool toggles
make dev # Start LangGraph development server (uv run langgraph dev --no-browser)
make dev_ui # Start with LangGraph Studio Web UI in browsermake test # Run unit and integration tests (default)
make test_unit # Run unit tests only
make test_integration # Run integration tests
make test_e2e # Run end-to-end tests (requires running server)
make test_all # Run all test suitesmake lint # Run linters (ruff + mypy)
make format # Auto-format code
make lint_tests # Lint test files only- Hot Reload: Local changes automatically applied
- State Editing: Edit past state and rerun from specific points
- Thread Management: Create new threads or continue existing conversations
- LangSmith Integration: Detailed tracing and collaboration
The template uses a modular architecture:
src/react_agent/: Core agent graph and state managementsrc/common/: Shared components (context, models, tools, prompts, MCP integration)tests/: Comprehensive test suite with fixtures and MCP integration coveragelanggraph.json: LangGraph Agent basic configuration settings
Key components:
src/common/mcp.py: MCP client management for external documentation sources- Dynamic tool loading: Runtime tool selection based on context configuration
- Context system: Centralized configuration with environment variable support
This structure supports multiple agents and easy component reuse across different implementations.
Agent evaluation is crucial for production-grade AI applications because it:
- 🎯 Validates Performance: Ensures agents work correctly across different scenarios and use tools appropriately
- 🛡️ Identifies Security Issues: Discovers potential vulnerabilities through adversarial testing
- 📊 Enables Benchmarking: Provides objective metrics to compare different models and configurations
- 🔄 Drives Improvement: Offers concrete performance metrics to guide agent optimization
The template provides a comprehensive evaluation system using a dual-methodology approach:
Tests agent reasoning patterns and tool usage decisions:
# Run comprehensive graph trajectory evaluation
make eval_graph
# Test specific models
make eval_graph_qwen # Qwen/Qwen3-8B model
make eval_graph_glm # GLM-4-9B-0414 modelEvaluation Scenarios:
- Simple Question: "What is the capital of France?" - Tests efficiency for basic facts
- Search Required: "What's the latest news about artificial intelligence?" - Tests tool usage and information synthesis
- Multi-step Reasoning: "What are the pros and cons of renewable energy, and what are the latest developments?" - Tests complex analytical tasks
Tests conversational capabilities through role-persona interactions:
# Start development server (required for multi-turn evaluation)
make dev
# Run multi-turn evaluation in another terminal
make eval_multiturn
# Test specific user personas
make eval_multiturn_polite # Polite user persona
make eval_multiturn_hacker # Adversarial user personaRole Scenarios:
- Writing Assistant × User Personas: Professional email collaboration
- Customer Service × User Personas: Account troubleshooting support
- Interviewer × User Personas: Technical interview management
The evaluation system supports testing across different model providers:
- 🌍 International Models: OpenAI GPT-4o, Anthropic Claude, etc.
- 🇨🇳 Chinese Models: SiliconFlow platform (Qwen, GLM, DeepSeek models)
- 🔄 Comparative Analysis: Side-by-side performance comparison across providers
- 💡 Cost Optimization: Identify the most cost-effective models for your use cases
The evaluation system provides a comprehensive agent performance analysis framework with detailed test scenarios, evaluation methodology, and results analysis.
For specific evaluation results, test scenarios, and usage instructions, please refer to the detailed evaluation system documentation.
# Set up required environment variables
export SILICONFLOW_API_KEY="your_siliconflow_api_key" # For model testing
export TAVILY_API_KEY="your_tavily_api_key" # For search functionality
export LANGSMITH_API_KEY="your_langsmith_api_key" # For evaluation tracking
# Run comprehensive evaluation suite
make evals
# Or run evaluations separately
make eval_graph # Graph trajectory evaluation (runs independently)
make eval_multiturn # Multi-turn chat evaluation (requires server)
# View release notes and version information
# Visit GitHub Releases page for all version release notes: https://github.com/webup/langgraph-up-react/releases- 🎯 LLM-as-Judge Methodology: Scenario-specific custom evaluation criteria
- 📊 Professional Reporting: Detailed score extraction and ranking systems
- 🔍 Trajectory Normalization: JSON serialization-compatible trajectory processing
- 📈 LangSmith Integration: Complete tracking and historical analysis
- ⚙️ Centralized Configuration: Unified evaluation settings in
config.py
For detailed evaluation documentation, see: tests/evaluations/README.md
- 📋 ROADMAP.md - Current milestones and future plans
- 🐛 Issues & PRs Welcome - Help us improve by raising issues or submitting pull requests
- 🤖 Built with Claude Code - This template is actively developed using Claude Code
We encourage community contributions! Whether it's:
- Reporting bugs or suggesting features
- Adding new tools or model integrations
- Improving documentation
- Sharing your use cases and templates
Check out our roadmap to see what we're working on next and how you can contribute.
- LangGraph Documentation - Framework guides and examples
- LangSmith - Tracing and collaboration platform
- ReAct Paper - Original research on reasoning and acting
- Claude Code - AI-powered development environment
This project is built on the shoulders of amazing open-source projects and service platforms:
- LangGraph - Powerful agent graph construction framework
- LangChain - Core library for building LLM applications
- AgentEvals - Agent evaluation framework providing LLM-as-Judge methodology
- OpenEvals - Open evaluation tools and methods
- LangSmith - LLM application tracing and debugging platform
- langchain-siliconflow - SiliconFlow model integration for open-source model support
- langchain-qwq - Alibaba Cloud Bailian platform model integration for Qwen series
- SiliconFlow - Chinese MaaS platform providing open-source models
- Alibaba Cloud Bailian (DashScope) - Qwen series model service platform
View all version updates: 📋 GitHub Releases
Thank you to all contributors and the open-source community! 🙏