Agent Patterns

Getting Started

  • Installation Guide
    • Quick Install
      • From PyPI (Recommended)
      • Upgrade to Latest Version
    • Installation from Source
      • Standard Installation
      • Development Installation
    • Requirements
      • System Requirements
      • Core Dependencies
    • Environment Setup
      • 1. Create Configuration File
      • 2. Add API Keys
      • 3. Verify Installation
    • Installation Options
      • Minimal Installation (Core Only)
      • Specific Version
      • From GitHub Branch
    • Virtual Environment Setup
      • Using venv (Recommended)
      • Using conda
      • Using poetry
    • Verification and Testing
      • Quick Verification
      • Run Unit Tests
    • Troubleshooting Installation
      • Common Issues
        • Issue: pip: command not found
        • Issue: Permission denied
        • Issue: SSL certificate verification failed
        • Issue: Incompatible Python version
        • Issue: Dependency conflicts
        • Issue: LangChain/LangGraph version conflicts
      • Getting Help
    • IDE Setup
      • VS Code
      • PyCharm
    • Next Steps
    • Upgrading from v0.1.x
  • Quick Start Guide
    • Prerequisites
    • Installation
    • Basic Setup
      • 1. Set Up Your API Key
      • 2. Your First Agent (30 seconds)
    • 5-Minute Tutorial
      • Example 1: ReAct Pattern (Reason + Act)
      • Example 2: Reflection Pattern
      • Example 3: Plan & Solve Pattern
    • Basic Concepts
      • 1. LLM Configuration
      • 2. Common LLM Roles
      • 3. Tool Functions
      • 4. Pattern Selection
    • Common Patterns
      • Environment Variables
      • Multiple Providers
      • Error Handling
      • Lifecycle Hooks
    • Project Structure
    • Next Steps
    • Complete Example: Task Manager Bot
    • Tips for Success
    • Getting Help
    • What’s Next?
  • What Are Agent Patterns?
    • The Problem with Ad-Hoc Agents
      • Example: Ad-Hoc Approach
    • What Are Patterns?
      • Example: Pattern-Based Approach
    • Why Patterns Matter
      • 1. Reliability
      • 2. Debuggability
      • 3. Reusability
      • 4. Best Practices
    • Pattern vs Non-Pattern Approaches
      • Comparison Table
      • Real-World Example
    • Common Pattern Categories
      • 1. Tool-Using Patterns
      • 2. Refinement Patterns
      • 3. Planning Patterns
      • 4. Multi-Perspective Patterns
    • When to Use Patterns
      • Use Patterns When:
      • Use Simple Prompts When:
      • Example Decision:
    • The Agent Patterns Library
    • Design Philosophy
      • 1. Synchronous by Design
      • 2. Externalized Configuration
      • 3. Explicit State
      • 4. Composable Tools
    • Next Steps
    • Key Takeaways
  • Library Architecture
    • Overview
    • Core Architecture
      • Component Hierarchy
      • BaseAgent Class
    • State Graph Architecture
      • Graph Components
      • Example: ReAct Pattern Graph
    • State Management
      • State Dictionary
      • State Flow
    • LLM Integration
      • LLM Configuration
      • LLM Initialization and Caching
      • LLM Invocation
    • Prompt Management
      • Three-Layer Prompt System
      • File-Based Prompts
      • Custom Instructions
      • Prompt Overrides
    • Pattern Execution Flow
      • Complete Execution Lifecycle
      • Example: ReAct Execution
    • Tool Integration
      • Tool Definition
      • Tool Registration
      • Tool Execution
    • Lifecycle Hooks
      • Custom Hook Implementation
    • Extending Patterns
      • Creating Custom Patterns
      • Extending Existing Patterns
    • Design Principles
      • 1. Synchronous Execution
      • 2. Immutable by Default
      • 3. Explicit Over Implicit
      • 4. Composition Over Inheritance
    • Performance Considerations
      • LLM Caching
      • State Graph Compilation
      • Prompt Loading
    • Next Steps

Agent Patterns

  • Choosing a Pattern
    • Quick Decision Tree
    • Detailed Pattern Guide
      • ReAct Pattern
      • Reflection Pattern
      • Plan & Solve Pattern
      • Reflexion Pattern
      • LLM Compiler Pattern
      • REWOO Pattern
      • LATS Pattern
      • Self-Discovery Pattern
      • STORM Pattern
    • Pattern Comparison Matrix
    • Use Case Mapping
      • By Domain
      • By Task Complexity
      • By Budget
    • Decision Checklist
    • Common Mistakes
      • Using LATS for Simple Tasks
      • Using ReAct When REWOO Would Work
      • Not Using Reflection for Quality Content
      • Using Plan & Solve Without Clear Steps
      • Underestimating STORM Costs
    • Still Unsure?
    • Further Reading
  • Pattern Comparison Matrix
    • Quick Decision Matrix
    • Detailed Use Case Analysis
      • Content Creation & Writing
        • Blog Posts & Articles
        • Technical Documentation
        • Research Papers/Reports
        • Creative Fiction
      • Problem Solving
        • Mathematical Proofs
        • Logic Puzzles
        • Code Debugging
        • Optimization Problems
        • Algorithm Design
      • Task Automation
        • API Orchestration
        • Web Scraping & Data Collection
        • ETL Pipelines
        • Workflow Automation
        • Database Queries
      • Research & Analysis
        • Market Research
        • Competitive Analysis
        • Literature Review
        • Data Analysis & Insights
        • Trend Analysis
      • Software Development
        • Code Generation
        • Code Review
        • Test Generation
        • Refactoring
        • Architecture Design
      • Decision Making
        • Strategic Planning
        • Risk Assessment
        • Resource Allocation
        • Scenario Planning
      • Customer Support
        • Troubleshooting
        • FAQ Generation
        • Knowledge Base Search
    • Pattern Characteristics Comparison
      • Computational Cost
      • Complexity & Learning Curve
      • Output Quality vs Speed
      • Recommended Learning Path
    • Decision Flowchart
    • Pattern Combination Strategies
      • Sequential Combinations
      • Parallel Combinations
    • Next Steps
  • ReAct Agent Pattern
    • Overview
    • When to Use ReAct
      • Ideal Use Cases
      • When NOT to Use ReAct
    • How ReAct Works
      • The Reasoning-Action Cycle
      • Theoretical Foundation
      • Algorithm
    • API Reference
      • Class: ReActAgent
        • Parameters
        • LLM Roles
        • Methods
    • Complete Example
      • Basic Usage
      • With Custom Instructions
      • With Prompt Overrides
    • Tool Definition Guidelines
      • Tool Function Signature
      • Tool Best Practices
      • Example Tools
    • Customizing Prompts
      • Understanding the System Prompt Structure
        • The 9-Section Comprehensive Structure
        • Benefits of Comprehensive Prompts
      • Understanding ReAct Prompts
      • Method 1: Custom Instructions
      • Method 2: Prompt Overrides
      • Method 3: Custom Prompt Directory
    • Setting Agent Goals
      • Via Task Description
      • Via Custom Instructions
      • Via System Prompt Override
    • Advanced Usage
      • Limiting Iterations
      • Tool Access Control
      • Error Handling
    • Performance Considerations
      • Cost Optimization
      • Speed Optimization
    • Comparison with Other Patterns
    • Common Pitfalls
      • 1. Unclear Tool Descriptions
      • 2. Too Many Tools
      • 3. Insufficient Iterations
      • 4. Non-Deterministic Tools
    • Troubleshooting
      • Agent Doesn’t Use Tools
      • Agent Loops Infinitely
      • Poor Quality Answers
    • Next Steps
    • References
  • Reflection Agent Pattern
    • Overview
    • When to Use Reflection
      • Ideal Use Cases
      • When NOT to Use Reflection
    • How Reflection Works
      • The Generate-Reflect-Refine Cycle
      • Theoretical Foundation
      • Algorithm
    • API Reference
      • Class: ReflectionAgent
        • Parameters
        • LLM Roles
        • Methods
    • Complete Examples
      • Basic Usage
      • With Custom Instructions
      • With Prompt Overrides
    • Customizing Prompts
      • Understanding the System Prompt Structure
        • The 9-Section Comprehensive Structure
      • Understanding Reflection Prompts
      • Method 1: Custom Instructions
      • Method 2: Prompt Overrides
      • Method 3: Custom Prompt Directory
    • Setting Agent Goals
      • Via Task Description
      • Via Custom Instructions
      • Via System Prompt Override
    • Advanced Usage
      • Multiple Reflection Cycles
      • Role-Specific LLM Configurations
      • Combining with External Validation
    • Performance Considerations
      • Cost Optimization
      • Quality vs Cost Tradeoff
      • When to Skip Reflection
    • Comparison with Other Patterns
    • Common Pitfalls
      • 1. Insufficient Reflection Cycles
      • 2. Vague Reflection Criteria
      • 3. Over-Refinement
      • 4. Same Temperature for All Roles
    • Troubleshooting
      • Refinement Not Triggered
      • Poor Quality Refinements
      • Infinite Refinement Loop
    • Next Steps
    • References
  • Plan & Solve Agent Pattern
    • Overview
    • When to Use Plan & Solve
      • Ideal Use Cases
      • When NOT to Use Plan & Solve
    • How Plan & Solve Works
      • The Two-Phase Workflow
      • Theoretical Foundation
      • Algorithm
    • API Reference
      • Class: PlanAndSolveAgent
        • Parameters
        • LLM Roles
        • Methods
    • Complete Examples
      • Basic Usage
      • With Custom Instructions
      • With Prompt Overrides
    • Customizing Prompts
      • Understanding the System Prompt Structure
      • Understanding Plan & Solve Prompts
      • Method 1: Custom Instructions
      • Method 2: Prompt Overrides
      • Method 3: Custom Prompt Directory
    • Setting Agent Goals
      • Via Task Description
      • Via Custom Instructions
    • Advanced Usage
      • Role-Specific Models
      • Custom Step Execution Logic
      • Plan Validation
    • Performance Considerations
      • Cost Optimization
      • Speed Optimization
    • Comparison with Other Patterns
    • Common Pitfalls
      • 1. Too Granular Plans
      • 2. Steps Without Dependencies
      • 3. Vague Step Descriptions
      • 4. Ignoring Previous Results
    • Troubleshooting
      • Plans Are Too Short
      • Steps Don’t Build on Each Other
      • Poor Final Synthesis
    • Next Steps
    • References
  • Self-Discovery Agent Pattern
    • Overview
    • When to Use Self-Discovery
      • Ideal Use Cases
      • When NOT to Use Self-Discovery
    • How Self-Discovery Works
      • The Discovery-Adaptation-Execution Cycle
      • Theoretical Foundation
      • Algorithm
    • API Reference
      • Class: SelfDiscoveryAgent
        • Parameters
        • Default Reasoning Modules
        • LLM Roles
        • Methods
    • Complete Examples
      • Basic Usage
      • With Custom Reasoning Modules
      • With Custom Instructions
      • With Prompt Overrides
    • Customizing Reasoning Modules
      • Understanding the System Prompt Structure
      • Creating Domain-Specific Modules
      • Module Structure
    • Setting Agent Goals
      • Via Task Description
      • Via Custom Instructions
      • Via System Prompt Override
    • Advanced Usage
      • Adjusting Module Selection
      • Combining Default and Custom Modules
      • Role-Specific LLM Configurations
    • Performance Considerations
      • Cost Optimization
      • When to Use vs Other Patterns
    • Comparison with Other Patterns
    • Common Pitfalls
      • 1. Too Many Modules
      • 2. Generic Module Descriptions
      • 3. Using for Simple Tasks
      • 4. Ignoring Module Adaptation
    • Troubleshooting
      • Poor Module Selection
      • Weak Reasoning Steps
      • Synthesis Doesn’t Integrate Well
    • Next Steps
    • References
  • Reflexion Agent Pattern
    • Overview
    • When to Use Reflexion
      • Ideal Use Cases
      • When NOT to Use Reflexion
    • How Reflexion Works
      • The Multi-Trial Learning Cycle
      • Theoretical Foundation
      • Algorithm
    • API Reference
      • Class: ReflexionAgent
        • Parameters
        • LLM Roles
        • Methods
    • Complete Examples
      • Basic Usage
      • With Custom Instructions
      • With Prompt Overrides
    • Customizing Prompts
      • Understanding the System Prompt Structure
      • Understanding Reflexion Prompts
      • Method 1: Custom Instructions
      • Method 2: Prompt Overrides
      • Method 3: Custom Prompt Directory
    • Setting Agent Goals
      • Via Task Description
      • Via Custom Instructions
    • Advanced Usage
      • Adjusting Trial Budget
      • Custom Evaluation Logic
      • Memory Analysis
    • Performance Considerations
      • Cost Analysis
      • When to Use Reflexion vs Other Patterns
    • Comparison with Other Patterns
    • Common Pitfalls
      • 1. Insufficient Trials
      • 2. Vague Evaluation Criteria
      • 3. Weak Reflections
      • 4. Repeating Mistakes
    • Troubleshooting
      • All Trials Failing
      • Weak Learning Between Trials
      • Premature Success Evaluation
    • Next Steps
    • References
  • REWOO Agent Pattern
    • Overview
    • When to Use REWOO
      • Ideal Use Cases
      • When NOT to Use REWOO
    • How REWOO Works
      • The Plan-Execute-Integrate Workflow
      • Theoretical Foundation
      • Algorithm
    • API Reference
      • Class: REWOOAgent
        • Parameters
        • LLM Roles
        • Methods
    • Complete Examples
      • Basic Usage
      • With Custom Instructions
      • With Prompt Overrides
    • Tool Definition Guidelines
      • Tool Function Signature
      • Placeholder Resolution
    • Customizing Prompts
      • Understanding the System Prompt Structure
      • Understanding REWOO Prompts
      • Method 1: Custom Instructions
      • Method 2: Prompt Overrides
      • Method 3: Custom Prompt Directory
    • Setting Agent Goals
      • Via Task Description
      • Via Custom Instructions
    • Advanced Usage
      • Parallel Tool Execution
      • Custom Solver Logic
      • Fallback to Solver LLM
    • Performance Considerations
      • Cost Optimization
      • When REWOO Saves Money
      • When ReAct is Better
    • Comparison with Other Patterns
    • Common Pitfalls
      • 1. Unpredictable Dependencies
      • 2. Poor Placeholder Naming
      • 3. Missing Dependencies
      • 4. Over-Planning
    • Troubleshooting
      • Plan Doesn’t Parse Correctly
      • Results Not Integrating Well
      • Tool Execution Failures
    • Next Steps
    • References
  • LATS Agent Pattern
    • Overview
    • When to Use LATS
      • Ideal Use Cases
      • When NOT to Use LATS
    • How LATS Works
      • The Tree Search Process
      • Key Concepts
      • Theoretical Foundation
      • Algorithm
    • API Reference
      • Class: LATSAgent
        • Parameters
        • LLM Roles
        • Methods
    • Complete Examples
      • Basic Usage
      • With Custom Instructions
      • With Prompt Overrides
    • Customizing Search Parameters
      • Understanding the System Prompt Structure
      • Exploration vs Exploitation
      • Search Breadth and Depth
      • Iteration Budget
    • Advanced Usage
      • Custom Tree Node Logic
      • Pruning Unpromising Branches
    • Performance Considerations
      • Cost Analysis
      • When to Use LATS
    • Comparison with Other Patterns
    • Common Pitfalls
      • 1. Insufficient Iteration Budget
      • 2. Poor Evaluation Scoring
      • 3. Non-Diverse Expansions
      • 4. Wrong Exploration Weight
    • Troubleshooting
      • Search Not Exploring Diverse Paths
      • Low-Quality Final Solution
      • Search Takes Too Long
    • Next Steps
    • References
  • LLM Compiler Agent Pattern
    • Overview
    • When to Use LLM Compiler
      • Ideal Use Cases
      • When NOT to Use LLM Compiler
    • How LLM Compiler Works
      • The DAG Construction and Execution
      • Key Concepts
      • Theoretical Foundation
      • Algorithm
    • API Reference
      • Class: LLMCompilerAgent
        • Parameters
        • LLM Roles
        • Methods
    • Complete Examples
      • Basic Usage
      • With Custom Instructions
      • With Prompt Overrides
    • Tool Definition Guidelines
      • Tool Function Signature
      • Dependency References
    • Customizing Prompts
      • Understanding the System Prompt Structure
      • Understanding LLM Compiler Prompts
      • Method 1: Custom Instructions
      • Method 2: Prompt Overrides
      • Method 3: Custom Prompt Directory
    • Setting Agent Goals
      • Via Task Description
      • Via Custom Instructions
    • Advanced Usage
      • Parallel Execution Simulation
      • DAG Visualization
    • Performance Considerations
      • Cost Analysis
      • When LLM Compiler Excels
      • When to Use Other Patterns
    • Comparison with Other Patterns
    • Common Pitfalls
      • 1. Circular Dependencies
      • 2. Missing Dependencies
      • 3. Over-Sequencing
      • 4. Incorrect Reference Syntax
    • Troubleshooting
      • DAG Parsing Failures
      • Execution Hangs
      • Poor Parallelism
    • Next Steps
    • References
  • STORM Agent Pattern
    • Overview
    • When to Use STORM
      • Ideal Use Cases
      • When NOT to Use STORM
    • How STORM Works
      • The Multi-Stage Research Workflow
      • Theoretical Foundation
      • Algorithm
    • API Reference
      • Class: STORMAgent
        • Parameters
        • Default Perspectives
        • LLM Roles
        • Methods
    • Complete Examples
      • Basic Usage
      • With Custom Perspectives
      • With Multiple Retrieval Tools
      • With Custom Instructions
    • Retrieval Tool Guidelines
      • Tool Function Signature
      • Tool Best Practices
      • Example Retrieval Tools
    • Customizing Prompts
      • Understanding the System Prompt Structure
      • Understanding STORM Prompts
      • Method 1: Custom Instructions
      • Method 2: Prompt Overrides
      • Method 3: Custom Prompt Directory
    • Setting Agent Goals
      • Via Topic Description
      • Via Custom Instructions
    • Advanced Usage
      • Custom Perspective Selection
      • Caching Retrieval Results
    • Performance Considerations
      • Cost Analysis
      • When to Use STORM
    • Comparison with Other Patterns
    • Common Pitfalls
      • 1. Insufficient Retrieval
      • 2. Too Many Perspectives
      • 3. Vague Topics
      • 4. Poor Question Generation
    • Troubleshooting
      • Shallow or Generic Content
      • Disjointed Sections
      • Retrieval Failures
    • Next Steps
    • References

Customization Guides

  • Prompt Customization Guide
    • Overview
    • New in v0.2.0: Enterprise-Grade Prompts
      • Comprehensive Prompt Architecture
      • Before and After: The Improvement
    • Priority System
    • Method 1: File-Based Prompts
      • Structure
      • Creating Custom Prompt Directory
      • Template Variables
      • Example: Custom ReAct Prompts
    • Method 2: Custom Instructions
      • What Are Custom Instructions?
      • When to Use Custom Instructions
      • Basic Usage
      • Domain-Specific Examples
        • Legal Domain
        • Financial Compliance
        • Educational Content
        • Cultural Sensitivity
      • Best Practices for Custom Instructions
      • Complete Example from examples/custom_instructions_example.py
    • Method 3: Prompt Overrides
      • What Are Prompt Overrides?
      • When to Use Prompt Overrides
      • Basic Usage
      • Multiple Overrides
      • Style Customization
      • Dynamic Overrides
      • Complete Example from examples/prompt_overrides_example.py
    • Combining All Three Methods
      • Resolution Order
    • Pattern-Specific Examples
      • ReAct Pattern
      • Self-Discovery Pattern
      • STORM Pattern
    • Testing Your Customizations
      • Unit Testing Prompts
      • A/B Testing Prompts
    • Common Pitfalls
      • 1. Missing Template Variables
      • 2. Too Many Instructions
      • 3. Conflicting Instructions
      • 4. Forgetting to Test
    • Next Steps
    • Reference
      • Customization Methods Summary
      • All Template Variables by Pattern
  • Custom Instructions Deep Dive
    • Overview
      • Key Characteristics
    • How Custom Instructions Work
      • Under the Hood
      • Example Flow
    • Domain-Specific Examples
      • Medical Domain
      • Legal Domain
      • Financial Compliance
      • Educational Content
      • Technical Documentation
      • Cultural Sensitivity
      • Accessibility Guidelines
      • Scientific Research
      • Customer Service
    • Advanced Patterns
      • Multi-Concern Instructions
      • Dynamic Instructions
      • Context-Aware Instructions
      • Composable Instructions
    • Best Practices
      • 1. Be Specific and Actionable
      • 2. Use Structured Formatting
      • 3. Prioritize Key Guidelines
      • 4. Set Clear Boundaries
      • 5. Keep It Concise
      • 6. Test Thoroughly
      • 7. Version Your Instructions
      • 8. Document Your Instructions
    • Combining with Other Customization Methods
      • With Prompt Overrides
      • With Custom Prompt Directory
    • Common Pitfalls
      • 1. Instructions Too Generic
      • 2. Conflicting Instructions
      • 3. Instructions Lost in Noise
    • Troubleshooting
      • Instructions Not Being Followed
      • Instructions Conflict with Pattern Behavior
      • Too Many Instructions
    • Next Steps
    • Reference
      • Key Takeaways
      • Complete Example from Repository
  • Prompt Overrides Deep Dive
    • Overview
      • Key Characteristics
    • How Prompt Overrides Work
      • Structure
      • Important Note About v0.2.0 Comprehensive Prompts
      • Example: Simple Override
      • Example: Comprehensive Override (Recommended)
      • What Gets Replaced
    • Use Cases
      • 1. A/B Testing Prompts
      • 2. Dynamic Prompt Generation
      • 3. Style Customization
        • Concise Style
        • Socratic Method
        • Expert vs Beginner Level
      • 4. Debugging and Development
      • 5. Specialized Variants
    • Pattern-Specific Examples
      • ReAct Pattern
      • Self-Discovery Pattern
      • Reflection Pattern
      • Reflexion Pattern
    • Advanced Techniques
      • Conditional Overrides
      • Template-Based Overrides
      • Inheritance and Composition
    • Best Practices
      • 1. Preserve Template Variables
      • 2. Override Only What You Need
      • 3. Test Overrides Thoroughly
      • 4. Document Your Overrides
      • 5. Version Control Overrides
      • 6. Combine with Custom Instructions
    • Finding Step Names
      • Method 1: Check Pattern Source Code
      • Method 2: Check Prompt Directory
      • Method 3: Pattern Documentation
      • Common Step Names by Pattern
    • Common Pitfalls
      • 1. Typos in Step Names
      • 2. Missing Required Variables
      • 3. Overriding Both System and User When Only One Needed
      • 4. Forgetting About Custom Instructions
    • Troubleshooting
      • Override Not Applied
      • Template Variable Error
      • Conflicts with Custom Instructions
    • Next Steps
    • Reference
      • Complete Example from Repository
      • Key Takeaways
  • Setting Agent Goals
    • Overview
    • Goal-Setting Methods
      • 1. Via Task Description (Primary Method)
        • Explicit Goals
        • Goal Clarity Spectrum
        • Success Criteria in Task Description
      • 2. Via Custom Instructions (Persistent Goals)
        • Persistent Quality Goals
        • Domain-Specific Goals
        • Performance Goals
      • 3. Via Prompt Overrides (Step-Specific Goals)
        • Goal-Oriented Overrides
        • Outcome-Focused Overrides
      • 4. Via Configuration Parameters
    • Goal Types and Examples
      • Informational Goals
      • Analytical Goals
      • Creative Goals
      • Decision Support Goals
      • Problem-Solving Goals
    • Combining Goal-Setting Methods
      • Example 1: Research Agent
      • Example 2: Customer Service Agent
      • Example 3: Code Review Agent
    • Goal Measurement and Validation
      • Defining Measurable Goals
      • Validating Goal Achievement
      • Iterative Goal Refinement
    • Advanced Goal Patterns
      • Hierarchical Goals
      • Conditional Goals
      • Competing Goals and Trade-offs
    • Common Pitfalls
      • 1. Vague Goals
      • 2. Conflicting Goals
      • 3. Unmeasurable Goals
      • 4. Too Many Goals
    • Best Practices
      • 1. Start with Clear Task Goals
      • 2. Use Hierarchical Goal Structure
      • 3. Make Goals Measurable
      • 4. Provide Context
      • 5. Test Goal Achievement
    • Next Steps
    • Reference
      • Goal-Setting Method Comparison
      • Example Goal Templates
  • Configuration Guide
    • Overview
    • LLM Configuration Structure
      • Basic Structure
      • Multi-Role Configuration
    • Provider Configuration
      • OpenAI
      • Anthropic
      • Mixed Providers
    • Model Parameters
      • Temperature
      • Max Tokens
    • Role-Based Configuration
      • Role Purposes by Pattern
    • Pattern-Specific Parameters
      • ReAct
      • Reflection
      • Self-Discovery
      • REWOO
      • Reflexion
    • Environment Variables
      • Setup
      • Loading Environment
    • Cost Optimization
      • Strategy 1: Use Cheaper Models for Simple Steps
      • Strategy 2: Reduce Max Tokens
      • Strategy 3: Limit Iterations/Cycles
      • Strategy 4: Use REWOO for Tool-Heavy Tasks
    • Performance Optimization
      • Faster Models
      • Parallel Execution
    • Quality Optimization
      • Use Best Models
      • Increase Iterations/Cycles
    • Configuration Profiles
      • Development Profile
      • Production Profile
      • Testing Profile
    • Configuration Best Practices
      • 1. Use Environment Variables for Secrets
      • 2. Match Model Capability to Task Complexity
      • 3. Adjust Temperature by Use Case
      • 4. Set Appropriate Token Limits
      • 5. Version Your Configurations
    • Troubleshooting
      • Issue: Rate Limiting
      • Issue: High Costs
      • Issue: Poor Quality
      • Issue: Slow Performance
    • Next Steps
    • Reference
      • Model Comparison
      • Configuration Parameters Reference

Advanced Topics

  • Error Handling Best Practices
    • Overview
    • Common Error Types
      • 1. LLM API Errors
      • 2. Configuration Errors
      • 3. Tool Execution Errors
    • Error Handling Patterns
      • Try-Catch with Fallback
      • Retry with Exponential Backoff
      • Circuit Breaker Pattern
      • Graceful Degradation
    • Logging and Monitoring
      • Structured Logging
      • Metrics Collection
    • Validation and Safety
      • Input Validation
      • Output Validation
      • Safety Guardrails
    • Best Practices
      • 1. Always Use Try-Catch
      • 2. Log All Errors
      • 3. Implement Timeouts
      • 4. Graceful Degradation
      • 5. Monitor and Alert
    • Testing Error Handling
    • Recovery Strategies
      • Checkpoint and Resume
    • Next Steps
    • Reference
      • Common Exceptions
      • Error Handling Checklist
  • Testing Strategies for Agent Patterns
    • Overview
    • Testing Levels
      • Unit Tests
      • Integration Tests
      • End-to-End Tests
    • Mocking Strategies
      • Mocking LLM Responses
      • Mocking Tools
      • Mocking Prompts
    • Testing Custom Instructions
    • Testing Prompt Overrides
    • Testing Configuration
    • Testing Pattern-Specific Behavior
      • Testing ReAct
      • Testing Reflection
      • Testing Self-Discovery
    • Test Fixtures and Utilities
      • Shared Fixtures
      • Test Helpers
    • Performance Testing
    • Test Organization
      • Test Structure
      • Running Tests
    • Best Practices
      • 1. Mock Expensive Operations
      • 2. Use Deterministic Settings for Tests
      • 3. Test Error Cases
      • 4. Use Fixtures for Common Setup
      • 5. Mark Expensive Tests
    • CI/CD Integration
      • GitHub Actions Example
    • Next Steps
    • Reference
      • Pytest Markers
      • Test Coverage Goals
  • Production Deployment Guide
    • Overview
    • API Wrapping
      • FastAPI Wrapper
      • Flask Wrapper
    • Containerization
      • Dockerfile
      • Docker Compose
    • Scaling Strategies
      • Horizontal Scaling
      • Async Processing with Celery
      • Caching
    • Monitoring and Observability
      • Prometheus Metrics
      • Structured Logging
      • Distributed Tracing
    • Cost Optimization
      • Model Selection Strategy
      • Rate Limiting
      • Usage Tracking
    • Security
      • API Authentication
      • Input Sanitization
      • Rate Limiting per User
    • Deployment Environments
      • Development
      • Staging
      • Production
    • Best Practices
      • 1. Use Environment Variables
      • 2. Implement Health Checks
      • 3. Graceful Shutdown
      • 4. Use Circuit Breakers
      • 5. Monitor Costs
    • Next Steps
    • Reference
      • Deployment Checklist
  • Extending Agent Patterns
    • Overview
    • Understanding BaseAgent
      • Key Methods to Override
    • Creating a Simple Custom Pattern
      • Step 1: Define the Pattern Class
      • Step 2: Create Prompt Templates
      • Step 3: Use the Custom Pattern
    • Extending Existing Patterns
      • Adding Custom Behavior
      • Adding New Steps
    • Composing Multiple Patterns
      • Sequential Composition
      • Parallel Composition
      • Hierarchical Composition
    • Advanced Customization
      • Custom State Management
      • Adding Tools to Patterns
    • Testing Custom Patterns
    • Best Practices
      • 1. Follow BaseAgent Contract
      • 2. Use Lifecycle Hooks
      • 3. Make Patterns Configurable
      • 4. Document Your Pattern
      • 5. Reuse Existing Components
    • Next Steps
    • Reference
      • BaseAgent API
      • State Graph Components
  • Best Practices for Agent Patterns
    • Overview
    • Design Principles
      • 1. Choose the Right Pattern for the Task
      • 2. Start Simple, Then Optimize
      • 3. Separate Concerns
    • Prompt Engineering
      • 1. Be Specific and Clear
      • 2. Use Hierarchical Goals
      • 3. Provide Examples in Prompts
      • 4. Test Prompts Systematically
    • Configuration Management
      • 1. Use Environment-Based Configs
      • 2. Version Your Configurations
      • 3. Centralize Domain Instructions
    • Error Handling
      • 1. Always Use Try-Catch
      • 2. Implement Circuit Breakers
      • 3. Graceful Degradation
    • Performance Optimization
      • 1. Cache Aggressively
      • 2. Use Appropriate Models
      • 3. Limit Iterations Appropriately
      • 4. Parallel Processing When Possible
    • Cost Management
      • 1. Monitor and Track Costs
      • 2. Use Cost-Effective Patterns
      • 3. Implement Budgets
    • Testing
      • 1. Test at Multiple Levels
      • 2. Use Deterministic Settings for Tests
      • 3. Mock Expensive Operations
    • Security
      • 1. Validate All Inputs
      • 2. Sanitize Outputs
      • 3. Implement Rate Limiting
    • Monitoring and Observability
      • 1. Structured Logging
      • 2. Metrics Collection
      • 3. Distributed Tracing
    • Common Pitfalls
      • 1. Not Handling Rate Limits
      • 2. Ignoring Costs
      • 3. No Input Validation
      • 4. Poor Error Messages
      • 5. Not Testing with Real Scenarios
    • Production Checklist
    • Next Steps
    • Summary

API Reference

  • API Reference
    • Overview
    • Quick Links
    • Import Structure
    • Common Patterns
      • Basic Usage
      • With Customization
    • Core Classes
      • BaseAgent
      • Pattern Classes
    • Type Definitions
      • LLM Configuration
      • Prompt Overrides
      • Tool Definition
    • Common Parameters
    • LLM Providers
      • OpenAI
      • Anthropic
    • Error Handling
    • Lifecycle Hooks
    • Advanced Usage
      • Custom Pattern Creation
      • Pattern Composition
    • Next Steps
  • BaseAgent API Reference
    • Overview
    • Class Definition
    • Constructor
      • __init__(llm_configs, prompt_dir='prompts', custom_instructions=None, prompt_overrides=None)
    • Abstract Methods
      • build_graph() -> None
      • run(input_data: Any) -> Any
    • Public Methods
      • stream(input_data: Any) -> Iterator[Any]
    • Protected Methods
      • _get_llm(role: str) -> BaseChatModel
      • _load_prompt(step_name: str) -> Dict[str, str]
    • Lifecycle Hooks
      • on_start(input_data: Any) -> None
      • on_finish(result: Any) -> None
      • on_error(error: Exception) -> None
    • Attributes
      • Public Attributes
      • Private Attributes
    • Complete Example
    • Best Practices
      • 1. Always Call Parent __init__()
      • 2. Handle Errors in run()
      • 3. Use Descriptive Step Names
      • 4. Cache LLMs
      • 5. Validate State
    • See Also
  • Pattern API Reference
    • Pattern Overview
    • ReAct Pattern
      • Constructor
      • State Schema
      • Methods
        • run(input_data: str) -> str
        • add_tool(name: str, func: Callable) -> None
        • remove_tool(name: str) -> None
        • list_tools() -> List[str]
      • Example
      • Workflow
    • Reflection Pattern
      • Constructor
      • State Schema
      • Example
      • Workflow
    • Plan & Solve Pattern
      • Constructor
      • State Schema
      • Example
      • Workflow
    • Reflexion Pattern
      • Constructor
      • State Schema
      • Example
      • Workflow
    • LLM Compiler Pattern
      • Constructor
      • State Schema
      • Example
      • Workflow
    • REWOO Pattern
      • Constructor
      • State Schema
      • Example
      • Workflow
    • LATS Pattern
      • Constructor
      • State Schema
      • Example
      • Workflow
    • Self-Discovery Pattern
      • Constructor
      • Default Reasoning Modules
      • State Schema
      • Example
      • Workflow
    • STORM Pattern
      • Constructor
      • Default Perspectives
      • State Schema
      • Example
      • Workflow
    • Common Parameters
      • LLM Roles
      • Prompt Customization
      • Lifecycle Hooks
    • Pattern Selection Guide
    • Further Reading
  • Type Reference
    • Core Types
      • LLM Configuration Types
        • LLMConfig
        • LLMConfigs
      • Prompt Types
        • PromptDict
        • PromptOverrides
      • Tool Types
        • ToolFunction
        • ToolDict
      • State Types
        • State
        • Pattern-Specific State Types
      • Action Types
        • Action
      • Result Types
        • AgentResult
    • Pattern-Specific Types
      • ReAct Pattern
      • Reflection Pattern
      • Self-Discovery Pattern
      • STORM Pattern
    • LangChain/LangGraph Types
      • LLM Types
      • Message Types
      • Graph Types
    • Utility Types
      • Optional and Union
      • Callable Types
      • Generic Types
    • Type Checking
      • Runtime Type Checking
      • Type Guards
    • Type Hints in Practice
      • Function Signatures
      • Class Type Hints
    • Type Aliases
    • mypy Configuration
    • Type Stubs
    • Best Practices
      • 1. Always Use Type Hints
      • 2. Use Optional for Nullable Values
      • 3. Use TypedDict for Structured Dicts
      • 4. Document Complex Types
    • See Also

Additional Resources

  • Examples Index
    • Quick Links
    • Basic Examples
      • ReAct Pattern Example
      • Reflection Pattern Example
    • Advanced Examples
      • LLM Compiler Pattern Example
      • REWOO Pattern Example
      • Plan & Solve Pattern Example
      • Reflexion Pattern Example
      • LATS Pattern Example
      • Self-Discovery Pattern Example
      • STORM Pattern Example
    • Customization Examples
      • Custom Instructions Example
      • Prompt Overrides Example
    • Integration Examples
      • API Integration
      • Database Integration
      • File System Integration
    • Pattern Comparisons
      • Simple Task: Question Answering
      • Content Generation
      • Complex Problem Solving
    • Example Categories
      • By Complexity
      • By Use Case
    • Running Examples
      • Prerequisites
      • Run an Example
      • Modify for Your Use Case
    • Additional Resources
    • Contributing Examples
  • Frequently Asked Questions (FAQ)
    • General Questions
      • What is Agent Patterns?
      • Why use patterns instead of custom code?
      • Which pattern should I use?
      • Is Agent Patterns production-ready?
      • What’s the license?
    • Installation & Setup
      • How do I install Agent Patterns?
      • What Python version is required?
      • Do I need API keys?
      • Can I use local/open-source models?
      • How do I set up multiple API keys?
    • Usage Questions
      • How do I create a simple agent?
      • How do I add tools to an agent?
      • Can I use async functions?
      • How do I handle errors?
      • How do I log agent activity?
    • Customization Questions
      • How do I customize prompts?
      • What’s the difference between custom_instructions and prompt_overrides?
      • Can I use different models for different roles?
      • How do I adjust temperature and other parameters?
    • Pattern-Specific Questions
      • ReAct: How many iterations should I use?
      • Reflection: How many reflection cycles?
      • Plan & Solve: Can I provide an existing plan?
      • STORM: How do I add custom perspectives?
      • Self-Discovery: Can I add custom reasoning modules?
    • Technical Questions
      • How does state management work?
      • What is LangGraph?
      • Can I inspect intermediate steps?
      • Can I stream results?
      • How do I test my agent?
    • Performance & Cost Questions
      • How much do API calls cost?
      • How can I reduce costs?
      • How fast are the patterns?
      • Can I cache LLM responses?
    • Troubleshooting Questions
      • I get “Module not found” errors
      • I get “API key not found” errors
      • Agent gives nonsensical responses
      • Agent loops infinitely
      • Tools aren’t being called
    • Advanced Questions
      • Can I create my own pattern?
      • Can I combine multiple patterns?
      • How do I deploy to production?
      • Can I use Agent Patterns with LangChain Expression Language (LCEL)?
    • Migration Questions
      • How do I migrate from v0.1.x to v0.2.0?
      • Can I still use v0.1.x?
    • Community & Support
      • Where can I get help?
      • How can I contribute?
      • Is there a Discord/Slack?
      • Where can I find more examples?
    • Didn’t find your answer?
  • Troubleshooting Guide
    • Quick Diagnostic Checklist
    • Installation Issues
      • Problem: pip: command not found
      • Problem: Permission denied during installation
      • Problem: No module named 'agent_patterns'
      • Problem: Dependency conflicts
    • Configuration Issues
      • Problem: No API key found
      • Problem: Invalid API key
      • Problem: No configuration found for role 'X'
      • Problem: Unsupported provider 'X'
    • Runtime Issues
      • Problem: Agent gives nonsensical responses
      • Problem: Agent loops indefinitely
      • Problem: Tools not being called
      • Problem: KeyError: 'output' or similar
      • Problem: Graph has not been built
    • Performance Issues
      • Problem: Slow execution
      • Problem: High API costs
      • Problem: Memory usage high
    • Testing & Development Issues
      • Problem: Tests failing
      • Problem: Type checking errors with mypy
      • Problem: Import errors in development
    • Debugging Techniques
      • Enable Verbose Logging
      • Inspect State
      • Test Individual Nodes
      • Use Breakpoints
      • Check LLM Responses
    • Error Messages Reference
      • Common Errors and Meanings
    • Still Having Issues?
      • Before Asking for Help
      • When Creating an Issue
      • Get Help
    • Prevention Tips
  • Changelog
    • [0.2.0] - 2025-01-XX
      • Major Rewrite - Breaking Changes
      • Added
        • Core Features
        • Patterns Implemented
        • Documentation
        • Testing
        • Development Tools
      • Changed
        • Breaking Changes
        • Improvements
      • Removed
      • Fixed
      • Dependencies
      • Migration Guide
        • Step 1: Update Imports
        • Step 2: Remove Async/Await
        • Step 3: Update Configuration
        • Step 4: Update Tool Definitions
        • Step 5: Test Thoroughly
      • Known Issues
      • Contributors
    • [0.1.0] - 2024-XX-XX (Deprecated)
      • Added
      • Known Issues
    • Future Releases
      • Planned Features
        • v0.3.0 (Target: Q2 2025)
        • v0.4.0 (Target: Q3 2025)
        • Under Consideration
      • Backward Compatibility Promise
      • Version Support Policy
    • Contributing
    • Reporting Issues
    • Release Notes Distribution
  • Contributing to Agent Patterns
    • Table of Contents
    • Code of Conduct
      • Our Pledge
      • Our Standards
      • Enforcement
    • Getting Started
      • Prerequisites
      • Fork and Clone
    • Development Setup
      • 1. Create Virtual Environment
      • 2. Install Development Dependencies
      • 3. Set Up Environment
      • 4. Verify Setup
    • Making Changes
      • Branch Strategy
      • Making Code Changes
      • Commit Messages
    • Testing
      • Running Tests
      • Writing Tests
    • Code Style
      • Formatting
      • Linting
      • Type Checking
      • Documentation
    • Submitting Changes
      • Pre-Submission Checklist
      • Create Pull Request
      • Review Process
    • Types of Contributions
      • Bug Fixes
      • New Features
      • New Patterns
      • Documentation
      • Tests
    • Development Tips
      • Run Pre-commit Checks
      • Faster Testing
      • Debug Tests
      • Keep Fork Updated
    • Getting Help
    • Recognition
    • License
Agent Patterns
  • Search

© Copyright 2025, osok.

Built with Sphinx using a theme provided by Read the Docs.