feat(examples/python): add write-your-first-agent runnable example

Author: AgentPatterns

.github/workflows/python.yml

@@ -0,0 +1,44 @@
+name: Python Examples CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check-python-examples:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Find and check all Python examples
+        run: |
+          set -e
+
+          if [ ! -d "examples" ]; then
+            echo "No examples/ directory. Skipping."
+            exit 0
+          fi
+
+          echo "Searching for Python examples..."
+
+          for dir in $(find examples -type f -name "main.py" -exec dirname {} \;); do
+            echo "=============================="
+            echo "Checking example in: $dir"
+            cd $dir
+
+            if [ -f "requirements.txt" ]; then
+              pip install -r requirements.txt
+            fi
+
+            echo "Compiling Python files..."
+            python -m compileall .
+
+            cd - > /dev/null
+          done
+

.gitignore

@@ -0,0 +1,55 @@
+# -------------------------
+# Python
+# -------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyd
+*.pyo
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Logs
+*.log
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# Pytest / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.cache/
+
+# IDEs
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+
+# MyPy / Ruff
+.mypy_cache/
+.ruff_cache/
+
+# Local runtime files
+*.sqlite3
+*.db
+

README.md

@@ -1,2 +1,36 @@
-# Agentpatterns Examples
-Runnable examples for AgentPatterns.tech articles (safe agent loops, budgeting, tool calling demos).
+# AgentPatterns Examples
+
+Runnable code examples that accompany articles on [agentpatterns.tech](https://www.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.
+
+## What lives here
+
+- `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.
+
+## Current structure
+
+```text
+examples/
+  write-your-first-agent/
+    python/
+```
+
+## Quick start (Python example)
+
+```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
+
+- Articles explain concepts and patterns.
+- This repo provides runnable implementations for those materials.
+- As new articles are published, matching examples are added here.

examples/write-your-first-agent/python/README.md

@@ -0,0 +1,16 @@
+📖 Based on article:
+
+EN:
+https://agentpatterns.tech/en/start-here/write-your-first-agent
+
+DE:
+https://agentpatterns.tech/de/start-here/write-your-first-agent
+
+FR:
+https://agentpatterns.tech/fr/start-here/write-your-first-agent
+
+ES:
+https://agentpatterns.tech/es/start-here/write-your-first-agent
+
+UK:
+https://agentpatterns.tech/uk/start-here/write-your-first-agent

examples/write-your-first-agent/python/evaluator.py

@@ -0,0 +1,10 @@
+def parse_int(text: str) -> int | None:
+    """Returns int or None if the text is not a valid integer."""
+    try:
+        return int(text.strip())
+    except (ValueError, AttributeError):
+        return None
+
+def is_goal_reached(number: int, goal: int) -> bool:
+    """Returns True if the number satisfies the goal condition."""
+    return number > goal

examples/write-your-first-agent/python/llm.py

@@ -0,0 +1,21 @@
+import os
+from openai import OpenAI
+
+api_key = os.environ.get("OPENAI_API_KEY")
+
+if not api_key:
+    raise EnvironmentError(
+        "OPENAI_API_KEY is not set.\n"
+        "Run: export OPENAI_API_KEY='sk-...'"
+    )
+
+client = OpenAI(api_key=api_key)
+
+PROMPT = "Write ONLY a random number between 1 and 20. No text, no explanation."
+
+def generate_number() -> str:
+    resp = client.responses.create(
+        model="gpt-4.1-mini",
+        input=PROMPT,
+    )
+    return resp.output_text.strip()

examples/write-your-first-agent/python/main.py

@@ -0,0 +1,28 @@
+from llm import generate_number
+from evaluator import parse_int, is_goal_reached
+
+GOAL = 10
+MAX_STEPS = 5
+
+def run():
+    for step in range(1, MAX_STEPS + 1):
+        print(f"\n🤖 Step {step}: Agent is trying...")
+
+        output = generate_number()
+        print(f"💬 Model generated: {output}")
+
+        number = parse_int(output)
+        if number is None:
+            print("❌ Not a number. Trying again...")
+            continue
+
+        if is_goal_reached(number, GOAL):
+            print(f"✅ Goal reached! {number} > {GOAL}")
+            return
+
+        print(f"❌ Not enough. {number} ≤ {GOAL}. Trying again...")
+
+    print("\n⚠️ Max steps reached without success")
+
+if __name__ == "__main__":
+    run()

examples/write-your-first-agent/python/requirements.txt

@@ -0,0 +1 @@
+openai>=1.0.0