Agent Patterns

Перший AI-агент — Python (повна реалізація)

Повний runnable приклад агента з циклом "Act → Check → Retry" та лімітом кроків.
На цій сторінці
  1. Що цей приклад демонструє
  2. Структура проєкту
  3. Як запустити
  4. Що ми будуємо в коді
  5. Код
  6. main.py — агентний цикл
  7. llm.py — виклик моделі
  8. evaluator.py — перевірка результату
  9. requirements.txt
  10. Приклад виводу
  11. Чому це "агент", а не просто функція
  12. Де далі копати
  13. 💻 Повний код на GitHub

Це повна реалізація прикладу зі статті Створюємо свого першого AI-агента.

Якщо ти ще не читав її — почни там. Тут ми фокусуємось на коді.

Що цей приклад демонструє

  • Ціль агента: отримати від моделі число більше 10
  • Цикл: Act → Check → Retry (максимум MAX_STEPS разів)
  • Валідація: модель може повернути текст, порожній рядок або нечислове значення — агент це обробляє
  • Stop condition: агент зупиняється або при успіху, або при вичерпанні кроків

Структура проєкту

TEXT
examples/
└── start-here/
    └── write-your-first-agent/
        └── python/
            ├── main.py           # агентний цикл
            ├── llm.py            # виклик LLM (ізоляція інтеграції)
            ├── evaluator.py      # перевірка результату
            └── requirements.txt

Чому три файли, а не один? Бо в реальному агенті генерація і оцінка майже завжди розділені. Якщо ти захочеш змінити модель або логіку перевірки — зміниш один файл, не чіпаючи решту.

Як запустити

1. Клонуй репозиторій і перейди в папку:

BASH
git clone https://github.com/AgentPatterns-tech/agentpatterns.git
cd examples/start-here/write-your-first-agent/python

2. Встанови залежності:

BASH
pip install -r requirements.txt

3. Вкажи API-ключ:

BASH
export OPENAI_API_KEY="sk-..."

4. Запусти:

BASH
python main.py

Що ми будуємо в коді

Ми робимо маленького робота, який хоче отримати число більше 10.

  • робот просить AI дати число
  • перевіряє: це справжнє число чи ні
  • якщо число замале, пробує ще раз

Просто: спробував → перевірив → або зупинився, або пробує далі.

Код

main.py — агентний цикл

PYTHON
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()

main.py не знає про OpenAI. Він не знає, як парсити числа. Він тільки керує циклом — це і є роль агента.

llm.py — виклик моделі

PYTHON
import os
from openai import OpenAI

api_key = os.environ.get("OPENAI_API_KEY")

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()

Модель отримує задачу і повертає текст. Вона не знає, що є агент, що є ціль, що є ліміт кроків. Вона просто генерує.

evaluator.py — перевірка результату

PYTHON
def parse_int(text: str) -> int | None:
    """Повертає int або None, якщо текст не є цілим числом."""
    try:
        return int(text.strip())
    except (ValueError, AttributeError):
        return None

def is_goal_reached(number: int, goal: int) -> bool:
    """Повертає True, якщо число задовольняє умову."""
    return number > goal

Два маленькі питання з чіткими відповідями: "це число?" і "мета досягнута?". Все просто.

requirements.txt

TEXT
openai>=1.0.0

Приклад виводу

TEXT
🤖 Step 1: Agent is trying...
💬 Model generated: 7
❌ Not enough. 7 ≤ 10. Trying again...

🤖 Step 2: Agent is trying...
💬 Model generated: 3
❌ Not enough. 3 ≤ 10. Trying again...

🤖 Step 3: Agent is trying...
💬 Model generated: 14
✅ Goal reached! 14 > 10

Чому це "агент", а не просто функція

ФункціяАгент
Кількість спроб1до MAX_STEPS
Перевіряє результат❌✅
Вирішує продовжувати чи зупинитись❌✅
Потребує участі людини між кроками—❌

Один виклик моделі — не агент.
Цикл з перевіркою і рішенням "пробувати ще чи зупинитись" — агент.

Де далі копати

Спробуй модифікувати приклад самостійно:

  • Зміни GOAL = 10 на GOAL = 19 — як часто агент досягатиме мети в межах MAX_STEPS?
  • Прибери MAX_STEPS і постав while True — що станеться?
  • Зміни промпт так, щоб модель генерувала числа від 1 до 100 — як це вплине на поведінку агента?
  • Додай лічильник загальних API-викликів і виведи його в кінці

💻 Повний код на GitHub

→ Дивись на GitHub

Читати далі
Як агент використовує інструменти (Основи) — Python (повна реалізація)
⏱️ 4 хв читання • Оновлено Бер, 2026Складність: ★☆☆
Інтегровано: продакшен-контрольOnceOnly
Додай guardrails до агентів з tool-calling
Зашип цей патерн з governance:
  • Бюджетами (кроки / ліміти витрат)
  • Дозволами на інструменти (allowlist / blocklist)
  • Kill switch та аварійна зупинка
  • Ідемпотентність і dedupe
  • Audit logs та трасування
Спробувати OnceOnlyДокументація та приклади
Інтегрована згадка: OnceOnly — контрольний шар для продакшен агент-систем.
Автор

Цю документацію курують і підтримують інженери, які запускають AI-агентів у продакшені.

Контент створено з допомогою AI, із людською редакторською відповідальністю за точність, ясність і продакшн-релевантність.

Патерни та рекомендації базуються на постмортемах, режимах відмов і операційних інцидентах у розгорнутих системах, зокрема під час розробки та експлуатації governance-інфраструктури для агентів у OnceOnly.