README

Author: AgentPatterns

README.md

@@ -1,36 +1,88 @@
-# AgentPatterns Examples
+# AgentPatterns Examples: Runnable AI Agent Patterns in Python
 
-Runnable code examples that accompany articles on [agentpatterns.tech](https://www.agentpatterns.tech).
+Production-style and beginner-friendly **AI agent examples** that map directly to the guides on [agentpatterns.tech](https://agentpatterns.tech).
 
-This repository is a practical companion to the main project: each article can include a small, focused example you can run locally and adapt for your own use cases.
+If you want to learn how to build agents with real execution loops, tool boundaries, routing, and safety checks, this repo is the fastest way to run and inspect working code.
 
-## What lives here
+## Why this repository
 
-- `examples/` contains article-aligned examples.
-- Each example is grouped by topic, then by language/runtime.
-- Examples are intentionally minimal: clear logic, fast setup, easy to remix.
+- Learn by running real code, not pseudo-code.
+- Move from simple loops to advanced multi-step agent patterns.
+- Reuse minimal, clean implementations in your own projects.
+- Follow examples that are aligned with concrete docs and architecture explanations.
 
-## Current structure
+## Available examples
+
+### Agent Patterns (Core Block)
+
+The most important block of the site and the main architecture layer for production agents.
+
+| Example | Focus | Local path | Article |
+| --- | --- | --- | --- |
+| ReAct Agent | `Think -> Act -> Observe` with budgets | `examples/react-agent/python` | https://agentpatterns.tech/en/agent-patterns/react-agent |
+| Routing Agent | Delegate to best specialist route | `examples/routing-agent/python` | https://agentpatterns.tech/en/agent-patterns/routing-agent |
+| Task Decomposition Agent | `Plan -> Execute -> Combine` workflow | `examples/task-decomposition-agent/python` | https://agentpatterns.tech/en/agent-patterns/task-decomposition-agent |
+
+### Foundations
+
+| Example | Focus | Local path | Article |
+| --- | --- | --- | --- |
+| Write Your First Agent | First loop (`Act -> Check -> Retry`) | `examples/write-your-first-agent/python` | https://agentpatterns.tech/en/start-here/write-your-first-agent |
+| Tool Calling Basics | Basic tool execution loop | `examples/tool-calling-basics/python` | https://agentpatterns.tech/en/foundations/tool-calling-basics |
+| Tool Calling | Tool + action restrictions (policy boundary) | `examples/tool-calling/python` | https://agentpatterns.tech/en/foundations/tool-calling |
+| LLM Limits in Agents | Validation, citations, confidence, handoff | `examples/llm-limits-agents/python` | https://agentpatterns.tech/en/foundations/llm-limits-agents |
+
+## Project structure
 
 ```text
 examples/
   write-your-first-agent/
     python/
+  tool-calling-basics/
+    python/
+  tool-calling/
+    python/
+  llm-limits-agents/
+    python/
+  react-agent/
+    python/
+  routing-agent/
+    python/
+  task-decomposition-agent/
+    python/
+```
+
+## Quick start
+
+### 1) Choose an example
+
+```bash
+EXAMPLE=react-agent
+cd examples/$EXAMPLE/python
 ```
 
-## Quick start (Python example)
+### 2) Install and run
 
 ```bash
-cd examples/write-your-first-agent/python
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 export OPENAI_API_KEY="sk-..."
 python main.py
 ```
 
-## Relation to agentpatterns.tech
+## Prerequisites
+
+- Python 3.10+ (3.11+ recommended)
+- `OPENAI_API_KEY` environment variable
+- macOS/Linux shell commands above (adapt activation/export commands on Windows)
+
+## How this maps to agentpatterns.tech
+
+- **Docs** explain when and why to use each agent pattern.
+- **This repo** shows runnable implementations of those exact patterns.
+- Each example folder includes its own README with direct links to related concepts.
+
+## License
 
-- Articles explain concepts and patterns.
-- This repo provides runnable implementations for those materials.
-- As new articles are published, matching examples are added here.
+MIT