# Agent Patterns
A Python library of reusable AI agent workflow patterns implemented using LangGraph and LangChain. All patterns are synchronous and follow consistent architectural principles.
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://agent-patterns.readthedocs.io/en/latest/)
📚 **[Full Documentation on Read the Docs](https://agent-patterns.readthedocs.io/en/latest/)**
> **⚠️ Breaking Change in v0.2.0**: This version is a complete rewrite from the ground up. The previous 0.1.x version used asyncio extensively, which caused significant reliability issues and made debugging extremely difficult. Version 0.2.0+ eliminates async/await entirely in favor of a **synchronous-only architecture**. This makes the library more reliable, easier to use, and much simpler to debug. If you were using v0.1.x, please note this is a breaking change - all patterns now use standard synchronous Python.
## Features
- **9 Battle-Tested Patterns**: ReAct, Plan & Solve, Reflection, Reflexion, LLM Compiler, REWOO, LATS, Self-Discovery, and STORM
- **Enterprise-Grade Prompts**: 150-300+ line comprehensive system prompts with 9-section structure (Role, Capabilities, Process, Examples, Edge Cases, Quality Standards, etc.) following Anthropic/OpenAI prompt engineering best practices
- **Synchronous Design**: No async/await complexity - simple, debuggable code
- **Flexible Prompt Customization**: Three ways to customize prompts - file-based, custom instructions, and programmatic overrides
- **Multi-Provider Support**: Works with OpenAI, Anthropic, and other LangChain-supported providers
- **Type-Safe**: Full type hints for better IDE support and fewer bugs
- **Extensible**: Abstract base classes make it easy to create custom patterns
- **Well-Tested**: Comprehensive test suite with 156 passing tests covering 58% of the codebase (6 of 9 patterns have >80% coverage)
## Installation
### From PyPI (Recommended)
```bash
pip install agent-patterns
```
### From Source
```bash
# Clone the repository
git clone https://github.com/osok/agent-patterns.git
cd agent-patterns
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e .
# Or install with dev dependencies
pip install -e ".[dev]"
```
## Quick Start
### 1. Set Up Environment
Copy `.env.example` to `.env` and add your API keys:
```bash
cp .env.example .env
```
Edit `.env`:
```
OPENAI_API_KEY=your-key-here
THINKING_MODEL_PROVIDER=openai
THINKING_MODEL_NAME=gpt-4-turbo
```
### 2. Use a Pattern
#### ReAct Agent (Reason + Act)
```python
from agent_patterns.patterns import ReActAgent
import os
from dotenv import load_dotenv
load_dotenv()
# Configure LLMs
llm_configs = {
"thinking": {
"provider": "openai",
"model_name": "gpt-4-turbo",
"temperature": 0.7,
}
}
# Define tools
def search_tool(query):
# Your search implementation
return f"Results for: {query}"
tools = {"search": search_tool}
# Create and run agent
agent = ReActAgent(
llm_configs=llm_configs,
tools=tools,
max_iterations=5
)
result = agent.run("What is the weather in Paris?")
print(result)
```
#### Reflection Agent
```python
from agent_patterns.patterns import ReflectionAgent
llm_configs = {
"documentation": {
"provider": "openai",
"model_name": "gpt-3.5-turbo",
},
"reflection": {
"provider": "openai",
"model_name": "gpt-4-turbo",
},
}
agent = ReflectionAgent(
llm_configs=llm_configs,
max_reflection_cycles=1
)
result = agent.run("Write a short story about a robot dog")
print(result)
```
#### Plan & Solve Agent
```python
from agent_patterns.patterns import PlanAndSolveAgent
llm_configs = {
"planning": {
"provider": "openai",
"model_name": "gpt-4-turbo",
},
"execution": {
"provider": "openai",
"model_name": "gpt-3.5-turbo",
},
"documentation": {
"provider": "openai",
"model_name": "gpt-3.5-turbo",
},
}
agent = PlanAndSolveAgent(llm_configs=llm_configs)
result = agent.run("Write a research report on renewable energy")
print(result)
```
## Available Patterns
All 9 patterns are fully implemented and ready to use:
| Pattern | Description | Use Case |
|---------|-------------|----------|
| **ReAct** | Reason + Act with tool use | Question answering with external tools |
| **Plan & Solve** | Planning then execution | Tasks requiring structured decomposition |
| **Reflection** | Generate, critique, refine | High-quality content generation |
| **Reflexion** | Multi-trial learning with reflection memory | Learning from mistakes across multiple attempts |
| **LLM Compiler** | DAG-based parallel tool execution | Optimized parallel task execution |
| **REWOO** | Worker-Solver pattern for cost efficiency | Efficient reasoning with reduced LLM calls |
| **LATS** | Tree search over reasoning paths | Exploring multiple solution strategies |
| **Self-Discovery** | Dynamic reasoning module selection | Adaptive problem-solving approach |
| **STORM** | Multi-perspective research synthesis | Comprehensive research from multiple viewpoints |
## Advanced Topics
For detailed information on the following topics, please see the [complete documentation](https://agent-patterns.readthedocs.io/en/latest/):
- **[Running Examples](https://agent-patterns.readthedocs.io/en/latest/)** - Detailed example usage
- **[Creating Custom Patterns](https://agent-patterns.readthedocs.io/en/latest/)** - Extend BaseAgent to build your own patterns
- **[Customizing Prompts](https://agent-patterns.readthedocs.io/en/latest/)** - File-based, custom instructions, and programmatic overrides
- **[Configuration](https://agent-patterns.readthedocs.io/en/latest/)** - LLM roles, environment variables, and settings
- **[Testing](https://agent-patterns.readthedocs.io/en/latest/)** - Running tests and contributing
- **[API Reference](https://agent-patterns.readthedocs.io/en/latest/)** - Complete API documentation
## Requirements
- Python 3.10+
- LangGraph >= 0.2.0
- LangChain >= 0.3.0
- python-dotenv >= 1.0.0
## Contributing
Contributions are welcome! Please see our [contribution guide](https://agent-patterns.readthedocs.io/en/latest/) for details on:
- Setting up your development environment
- Running tests and code quality tools
- Submitting pull requests
- Code style and conventions
Quick start for contributors:
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format and lint
black agent_patterns tests examples
ruff check agent_patterns tests examples
mypy agent_patterns
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Documentation
📚 **[Complete documentation available on Read the Docs](https://agent-patterns.readthedocs.io/en/latest/)**
Additional resources in this repository:
- [Design Document](docs/Design.md) - Detailed architectural design
- [Task List](docs/task_list.md) - Development progress tracking
- [Implementation Notes](docs/notes.md) - Technical decisions and guidelines
## Support
- **Documentation**: [Read the Docs](https://agent-patterns.readthedocs.io/en/latest/)
- **Issues**: [GitHub Issues](https://github.com/osok/agent-patterns/issues)
- **Discussions**: [GitHub Discussions](https://github.com/osok/agent-patterns/discussions)
- **PyPI**: [agent-patterns on PyPI](https://pypi.org/project/agent-patterns/)
---
**Built with ❤️ for the AI agent community**
Raw data
{
"_id": null,
"home_page": null,
"name": "agent-patterns",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, agents, langgraph, langchain, llm, patterns, react, reflection, storm, self-discovery",
"author": null,
"author_email": "osok <osok@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/df/83/753bb4ebf768583305b329148d23180034770b57e4cebcfbae2970ec1eb9/agent_patterns-0.2.4.tar.gz",
"platform": null,
"description": "# Agent Patterns\n\nA Python library of reusable AI agent workflow patterns implemented using LangGraph and LangChain. All patterns are synchronous and follow consistent architectural principles.\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://agent-patterns.readthedocs.io/en/latest/)\n\n\ud83d\udcda **[Full Documentation on Read the Docs](https://agent-patterns.readthedocs.io/en/latest/)**\n\n> **\u26a0\ufe0f Breaking Change in v0.2.0**: This version is a complete rewrite from the ground up. The previous 0.1.x version used asyncio extensively, which caused significant reliability issues and made debugging extremely difficult. Version 0.2.0+ eliminates async/await entirely in favor of a **synchronous-only architecture**. This makes the library more reliable, easier to use, and much simpler to debug. If you were using v0.1.x, please note this is a breaking change - all patterns now use standard synchronous Python.\n\n## Features\n\n- **9 Battle-Tested Patterns**: ReAct, Plan & Solve, Reflection, Reflexion, LLM Compiler, REWOO, LATS, Self-Discovery, and STORM\n- **Enterprise-Grade Prompts**: 150-300+ line comprehensive system prompts with 9-section structure (Role, Capabilities, Process, Examples, Edge Cases, Quality Standards, etc.) following Anthropic/OpenAI prompt engineering best practices\n- **Synchronous Design**: No async/await complexity - simple, debuggable code\n- **Flexible Prompt Customization**: Three ways to customize prompts - file-based, custom instructions, and programmatic overrides\n- **Multi-Provider Support**: Works with OpenAI, Anthropic, and other LangChain-supported providers\n- **Type-Safe**: Full type hints for better IDE support and fewer bugs\n- **Extensible**: Abstract base classes make it easy to create custom patterns\n- **Well-Tested**: Comprehensive test suite with 156 passing tests covering 58% of the codebase (6 of 9 patterns have >80% coverage)\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install agent-patterns\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/osok/agent-patterns.git\ncd agent-patterns\n\n# Create and activate virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .\n\n# Or install with dev dependencies\npip install -e \".[dev]\"\n```\n\n## Quick Start\n\n### 1. Set Up Environment\n\nCopy `.env.example` to `.env` and add your API keys:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env`:\n```\nOPENAI_API_KEY=your-key-here\nTHINKING_MODEL_PROVIDER=openai\nTHINKING_MODEL_NAME=gpt-4-turbo\n```\n\n### 2. Use a Pattern\n\n#### ReAct Agent (Reason + Act)\n\n```python\nfrom agent_patterns.patterns import ReActAgent\nimport os\nfrom dotenv import load_dotenv\n\nload_dotenv()\n\n# Configure LLMs\nllm_configs = {\n \"thinking\": {\n \"provider\": \"openai\",\n \"model_name\": \"gpt-4-turbo\",\n \"temperature\": 0.7,\n }\n}\n\n# Define tools\ndef search_tool(query):\n # Your search implementation\n return f\"Results for: {query}\"\n\ntools = {\"search\": search_tool}\n\n# Create and run agent\nagent = ReActAgent(\n llm_configs=llm_configs,\n tools=tools,\n max_iterations=5\n)\n\nresult = agent.run(\"What is the weather in Paris?\")\nprint(result)\n```\n\n#### Reflection Agent\n\n```python\nfrom agent_patterns.patterns import ReflectionAgent\n\nllm_configs = {\n \"documentation\": {\n \"provider\": \"openai\",\n \"model_name\": \"gpt-3.5-turbo\",\n },\n \"reflection\": {\n \"provider\": \"openai\",\n \"model_name\": \"gpt-4-turbo\",\n },\n}\n\nagent = ReflectionAgent(\n llm_configs=llm_configs,\n max_reflection_cycles=1\n)\n\nresult = agent.run(\"Write a short story about a robot dog\")\nprint(result)\n```\n\n#### Plan & Solve Agent\n\n```python\nfrom agent_patterns.patterns import PlanAndSolveAgent\n\nllm_configs = {\n \"planning\": {\n \"provider\": \"openai\",\n \"model_name\": \"gpt-4-turbo\",\n },\n \"execution\": {\n \"provider\": \"openai\",\n \"model_name\": \"gpt-3.5-turbo\",\n },\n \"documentation\": {\n \"provider\": \"openai\",\n \"model_name\": \"gpt-3.5-turbo\",\n },\n}\n\nagent = PlanAndSolveAgent(llm_configs=llm_configs)\n\nresult = agent.run(\"Write a research report on renewable energy\")\nprint(result)\n```\n\n## Available Patterns\n\nAll 9 patterns are fully implemented and ready to use:\n\n| Pattern | Description | Use Case |\n|---------|-------------|----------|\n| **ReAct** | Reason + Act with tool use | Question answering with external tools |\n| **Plan & Solve** | Planning then execution | Tasks requiring structured decomposition |\n| **Reflection** | Generate, critique, refine | High-quality content generation |\n| **Reflexion** | Multi-trial learning with reflection memory | Learning from mistakes across multiple attempts |\n| **LLM Compiler** | DAG-based parallel tool execution | Optimized parallel task execution |\n| **REWOO** | Worker-Solver pattern for cost efficiency | Efficient reasoning with reduced LLM calls |\n| **LATS** | Tree search over reasoning paths | Exploring multiple solution strategies |\n| **Self-Discovery** | Dynamic reasoning module selection | Adaptive problem-solving approach |\n| **STORM** | Multi-perspective research synthesis | Comprehensive research from multiple viewpoints |\n\n## Advanced Topics\n\nFor detailed information on the following topics, please see the [complete documentation](https://agent-patterns.readthedocs.io/en/latest/):\n\n- **[Running Examples](https://agent-patterns.readthedocs.io/en/latest/)** - Detailed example usage\n- **[Creating Custom Patterns](https://agent-patterns.readthedocs.io/en/latest/)** - Extend BaseAgent to build your own patterns\n- **[Customizing Prompts](https://agent-patterns.readthedocs.io/en/latest/)** - File-based, custom instructions, and programmatic overrides\n- **[Configuration](https://agent-patterns.readthedocs.io/en/latest/)** - LLM roles, environment variables, and settings\n- **[Testing](https://agent-patterns.readthedocs.io/en/latest/)** - Running tests and contributing\n- **[API Reference](https://agent-patterns.readthedocs.io/en/latest/)** - Complete API documentation\n\n## Requirements\n\n- Python 3.10+\n- LangGraph >= 0.2.0\n- LangChain >= 0.3.0\n- python-dotenv >= 1.0.0\n\n## Contributing\n\nContributions are welcome! Please see our [contribution guide](https://agent-patterns.readthedocs.io/en/latest/) for details on:\n\n- Setting up your development environment\n- Running tests and code quality tools\n- Submitting pull requests\n- Code style and conventions\n\nQuick start for contributors:\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format and lint\nblack agent_patterns tests examples\nruff check agent_patterns tests examples\nmypy agent_patterns\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Documentation\n\n\ud83d\udcda **[Complete documentation available on Read the Docs](https://agent-patterns.readthedocs.io/en/latest/)**\n\nAdditional resources in this repository:\n- [Design Document](docs/Design.md) - Detailed architectural design\n- [Task List](docs/task_list.md) - Development progress tracking\n- [Implementation Notes](docs/notes.md) - Technical decisions and guidelines\n\n## Support\n\n- **Documentation**: [Read the Docs](https://agent-patterns.readthedocs.io/en/latest/)\n- **Issues**: [GitHub Issues](https://github.com/osok/agent-patterns/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/osok/agent-patterns/discussions)\n- **PyPI**: [agent-patterns on PyPI](https://pypi.org/project/agent-patterns/)\n\n---\n\n**Built with \u2764\ufe0f for the AI agent community**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Reusable AI agent workflow patterns using LangGraph and LangChain",
"version": "0.2.4",
"project_urls": {
"Documentation": "https://agent-patterns.readthedocs.io/en/latest/",
"Homepage": "https://github.com/osok/agent-patterns",
"Issues": "https://github.com/osok/agent-patterns/issues",
"Repository": "https://github.com/osok/agent-patterns"
},
"split_keywords": [
"ai",
" agents",
" langgraph",
" langchain",
" llm",
" patterns",
" react",
" reflection",
" storm",
" self-discovery"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3a7da71149bb742dbf5a767e7fa92c08c0816cdcff4f41dd556ff12b017aa800",
"md5": "24661b7850d39704b5aa6ff5d9325240",
"sha256": "d908d8e245b89846be2fa12b9313a036b264672ff4c927cb2be73b382f233892"
},
"downloads": -1,
"filename": "agent_patterns-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "24661b7850d39704b5aa6ff5d9325240",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 49752,
"upload_time": "2025-10-30T23:37:29",
"upload_time_iso_8601": "2025-10-30T23:37:29.305308Z",
"url": "https://files.pythonhosted.org/packages/3a/7d/a71149bb742dbf5a767e7fa92c08c0816cdcff4f41dd556ff12b017aa800/agent_patterns-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "df83753bb4ebf768583305b329148d23180034770b57e4cebcfbae2970ec1eb9",
"md5": "e879ed6b9baa09a06650e9fc1a22364b",
"sha256": "cb3ac7c905b4a3a749fba469fe6bdf85c4dc7663fd4c77f34bb5105d8e07253c"
},
"downloads": -1,
"filename": "agent_patterns-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "e879ed6b9baa09a06650e9fc1a22364b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 193361,
"upload_time": "2025-10-30T23:37:30",
"upload_time_iso_8601": "2025-10-30T23:37:30.751782Z",
"url": "https://files.pythonhosted.org/packages/df/83/753bb4ebf768583305b329148d23180034770b57e4cebcfbae2970ec1eb9/agent_patterns-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 23:37:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "osok",
"github_project": "agent-patterns",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "agent-patterns"
}
JSON
