Troubleshooting Guide

Solutions to common problems and error messages when using Agent Patterns.

Quick Diagnostic Checklist

Before diving into specific issues, verify:

Python 3.10+ installed (python --version)
Agent Patterns installed (pip show agent-patterns)
API keys set (in .env or environment)
Dependencies installed (pip list | grep lang)
Code imports successfully

Installation Issues

Problem: `pip: command not found`

Cause: pip not installed or not in PATH

Solutions:

# Use Python's pip module
python -m pip install agent-patterns

# Or install pip
python -m ensurepip --default-pip

# macOS with brew
brew install python@3.10

Problem: `Permission denied` during installation

Cause: Trying to install system-wide without permissions

Solutions:

# Install to user directory
pip install --user agent-patterns

# Or use virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install agent-patterns

Problem: `No module named 'agent_patterns'`

Cause: Package not installed or wrong environment

Solutions:

# Verify installation
pip show agent-patterns

# Reinstall
pip install --force-reinstall agent-patterns

# Check you're in correct virtual environment
which python  # Should point to your venv

# If installed from source, use editable install
pip install -e .

Problem: Dependency conflicts

Cause: Incompatible versions of LangChain/LangGraph

Solutions:

# Create fresh virtual environment
python -m venv fresh_venv
source fresh_venv/bin/activate
pip install agent-patterns

# Or specify compatible versions
pip install langgraph==0.2.0 langchain==0.3.0 agent-patterns

Configuration Issues

Problem: `No API key found`

Error: openai.error.AuthenticationError: No API key provided

Cause: API key not set or not loaded

Solutions:

Create .env file:

cp .env.example .env
# Edit .env and add: OPENAI_API_KEY=your-key-here

Load environment variables:

from dotenv import load_dotenv
load_dotenv()  # Add this before creating agent

Set manually:

import os
os.environ["OPENAI_API_KEY"] = "your-key-here"

Verify key is loaded:

import os
print(os.getenv("OPENAI_API_KEY"))  # Should not be None

Problem: `Invalid API key`

Error: openai.error.AuthenticationError: Incorrect API key

Cause: Wrong API key or key for wrong provider

Solutions:

Verify key:
- OpenAI keys start with sk-
- Anthropic keys start with sk-ant-
Check provider matches key:

# If using OpenAI key, use openai provider
llm_configs = {
    "thinking": {
        "provider": "openai",  # Match your key
        "model_name": "gpt-4-turbo"
    }
}

Test key directly:

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-3.5-turbo")
llm.invoke("test")  # Should work if key is valid

Problem: `No configuration found for role 'X'`

Error: ValueError: No configuration found for role 'thinking'

Cause: Missing required LLM role in configuration

Solutions:

Check pattern requirements:

# ReAct requires "thinking"
agent = ReActAgent(
    llm_configs={
        "thinking": {"provider": "openai", "model_name": "gpt-4-turbo"}
    }
)

# Reflection requires "documentation" and "reflection"
agent = ReflectionAgent(
    llm_configs={
        "documentation": {...},
        "reflection": {...}
    }
)

See Pattern API Reference for each pattern’s required roles.

Problem: `Unsupported provider 'X'`

Error: ValueError: Unsupported provider 'claude'

Cause: Provider name incorrect

Solutions:

Use correct provider names:

# Correct
"provider": "openai"      # For GPT models
"provider": "anthropic"   # For Claude models

# Incorrect
"provider": "claude"      # Wrong! Use "anthropic"
"provider": "gpt"         # Wrong! Use "openai"

Runtime Issues

Problem: Agent gives nonsensical responses

Symptoms: Output doesn’t match input, hallucinations, incorrect answers

Causes & Solutions:

Temperature too high:

# Lower temperature for more deterministic output
llm_configs = {
    "thinking": {
        "provider": "openai",
        "model_name": "gpt-4-turbo",
        "temperature": 0.3  # Lower = more focused
    }
}

Wrong model:

# Use more capable model
"model_name": "gpt-4-turbo"  # Instead of gpt-3.5-turbo

Poor prompts:

# Add domain context
agent = ReActAgent(
    llm_configs={...},
    custom_instructions="""
    You are an expert in {domain}.
    Always provide accurate, well-reasoned answers.
    """
)

Insufficient iterations:

# Increase iterations for complex tasks
agent = ReActAgent(max_iterations=10)  # Default is 5

Problem: Agent loops indefinitely

Symptoms: Never reaches final answer, hits max iterations every time

Causes & Solutions:

Check termination logic:

# Ensure agent can detect completion
# For ReAct, tool should return "FINAL_ANSWER" when done

def my_tool(input: str) -> str:
    if condition_met:
        return "FINAL_ANSWER: Result here"
    return "Continue with more data"

Lower max iterations:

agent = ReActAgent(max_iterations=3)  # Force early termination

Improve tool responses:

# Tools should return clear, useful information
def search_tool(query: str) -> str:
    results = search(query)
    if not results:
        return "No results found. Try different query."
    return results

Problem: Tools not being called

Symptoms: Agent doesn’t use available tools, tries to answer without them

Causes & Solutions:

Tools not registered:

# Make sure tools are in the dict
agent = ReActAgent(
    llm_configs={...},
    tools={"search": search_func}  # Must be here!
)

Missing tool docstrings:

# Bad - no docstring
def search(query: str) -> str:
    return results

# Good - clear docstring
def search(query: str) -> str:
    """Search the web for information about the query."""
    return results

Prompt doesn’t mention tools:

# Check prompts mention available tools
# Custom prompt should reference tools:
prompt_overrides = {
    "ThoughtStep": {
        "user": "Available tools: {available_tools}\nUse tools when needed."
    }
}

Problem: `KeyError: 'output'` or similar

Cause: State key doesn’t exist

Solutions:

Check state initialization:

def run(self, input_data):
    initial_state = {
        "input": input_data,
        "output": None,  # Initialize all keys!
        "intermediate": []
    }
    final_state = self.graph.invoke(initial_state)

Check node returns:

def _my_node(self, state: Dict) -> Dict:
    state["new_key"] = "value"
    return state  # Must return state!

Problem: `Graph has not been built`

Error: ValueError: Graph has not been built

Cause: build_graph() not called or failed

Solutions:

# Ensure build_graph() is called
class MyAgent(BaseAgent):
    def __init__(self, ...):
        super().__init__(...)  # This calls build_graph()

# Check for errors in build_graph()
def build_graph(self):
    try:
        workflow = StateGraph(dict)
        # ... build graph ...
        self.graph = workflow.compile()
    except Exception as e:
        print(f"Graph build failed: {e}")
        raise

Performance Issues

Problem: Slow execution

Symptoms: Takes too long to complete

Causes & Solutions:

Too many iterations:

# Reduce iterations
agent = ReActAgent(max_iterations=3)

Using slow models:

# Use faster models for simple roles
llm_configs = {
    "thinking": {"model_name": "gpt-4-turbo"},
    "documentation": {"model_name": "gpt-3.5-turbo"}  # Faster
}

Large max_tokens:

# Reduce max tokens
llm_configs = {
    "thinking": {
        "model_name": "gpt-4-turbo",
        "max_tokens": 500  # Instead of 2000
    }
}

Enable caching:

from langchain.cache import InMemoryCache
from langchain.globals import set_llm_cache

set_llm_cache(InMemoryCache())

Problem: High API costs

Symptoms: Unexpectedly expensive

Solutions:

Use cheaper models:

# GPT-3.5 is ~10x cheaper than GPT-4
"model_name": "gpt-3.5-turbo"

Reduce iterations/cycles:

agent = ReActAgent(max_iterations=3)  # Instead of 10
agent = ReflectionAgent(max_reflection_cycles=1)  # Instead of 3

Use REWOO instead of ReAct:

# REWOO makes fewer LLM calls
agent = REWOOAgent(...)  # More efficient than ReActAgent

Cache common queries:

# Cache results in database/Redis
cached_result = cache.get(query)
if cached_result:
    return cached_result

result = agent.run(query)
cache.set(query, result)

Problem: Memory usage high

Causes & Solutions:

Large state history:

# Limit history size
def _my_node(self, state):
    # Keep only last N steps
    if len(state["history"]) > 10:
        state["history"] = state["history"][-10:]
    return state

LLM cache growing:

# Clear cache periodically
agent._llm_cache.clear()

Testing & Development Issues

Problem: Tests failing

Solutions:

Install test dependencies:

pip install -e ".[dev]"

Run specific test:

pytest tests/test_base_agent.py -v

Mock LLMs in tests:

from unittest.mock import Mock

def test_agent():
    mock_llm = Mock()
    mock_llm.invoke.return_value.content = "Test response"

    agent = ReActAgent(llm_configs={...})
    agent._llm_cache["thinking"] = mock_llm

    result = agent.run("test")
    assert "Test response" in result

Problem: Type checking errors with mypy

Solutions:

# Check mypy version
mypy --version

# Update mypy
pip install --upgrade mypy

# Run with less strict settings
mypy --ignore-missing-imports agent_patterns/

Problem: Import errors in development

Cause: Package not installed in editable mode

Solutions:

# Install in editable mode
pip install -e .

# Verify
python -c "import agent_patterns; print(agent_patterns.__file__)"

Debugging Techniques

Enable Verbose Logging

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("agent_patterns")
logger.setLevel(logging.DEBUG)

Inspect State

class DebugAgent(ReActAgent):
    def _generate_thought_and_action(self, state):
        print(f"State before thought: {state}")
        state = super()._generate_thought_and_action(state)
        print(f"State after thought: {state}")
        return state

Test Individual Nodes

# Test a single node in isolation
agent = ReActAgent(...)
test_state = {"input": "test", ...}

result_state = agent._generate_thought_and_action(test_state)
print(result_state)

Use Breakpoints

def _my_node(self, state):
    import pdb; pdb.set_trace()  # Debugger breakpoint
    # Step through code
    return state

Check LLM Responses

def _my_node(self, state):
    llm = self._get_llm("thinking")
    messages = [...]
    response = llm.invoke(messages)

    print(f"LLM Response: {response.content}")  # Debug output

    return state

Error Messages Reference

Common Errors and Meanings

Error	Meaning	Solution
`AuthenticationError`	Invalid/missing API key	Check `.env` file
`RateLimitError`	Too many API requests	Add delays, use rate limiting
`InvalidRequestError`	Bad request to API	Check model name, parameters
`ValueError: Graph not built`	build_graph() failed	Check build_graph() implementation
`KeyError`	Missing state key	Initialize all state keys
`TypeError: X is not callable`	Tool not a function	Ensure tools are functions
`ImportError`	Missing dependency	Run `pip install agent-patterns`

Still Having Issues?

Before Asking for Help

Check FAQ: FAQ
Search Issues: GitHub Issues
Read docs: Review relevant documentation pages
Try minimal example: Reproduce with simplest possible code

When Creating an Issue

Include:

Environment:
- Python version (python --version)
- Agent Patterns version (pip show agent-patterns)
- OS and version
Minimal reproducible example:

# Shortest code that demonstrates the issue
from agent_patterns.patterns import ReActAgent

agent = ReActAgent(llm_configs={...})
result = agent.run("test")  # Fails here

Full error message:

Traceback (most recent call last):
  File ...
  ...full traceback...

What you expected vs what happened

Get Help

GitHub Issues: Report bugs
GitHub Discussions: Ask questions
Documentation: Read the docs

Prevention Tips

Use virtual environments: Isolate dependencies
Pin versions: Specify exact versions in requirements.txt
Test changes: Run tests before deploying
Monitor logs: Watch for warnings and errors
Start simple: Begin with basic examples, add complexity gradually
Read error messages: They often explain the problem clearly
Check documentation: API reference has details on parameters
Use type hints: Catch errors during development

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

Problem: `pip: command not found`

Problem: `Permission denied` during installation

Problem: `No module named 'agent_patterns'`

Problem: `No API key found`

Problem: `Invalid API key`

Problem: `No configuration found for role 'X'`

Problem: `Unsupported provider 'X'`

Problem: `KeyError: 'output'` or similar

Problem: `Graph has not been built`