Як створити свого першого AI-агента на Python: покрокова інструкція для початківців

Ще кілька років тому AI у програмуванні асоціювався з машинним навчанням, математикою й дорогими серверами. Сьогодні все простіше: велику мовну модель можна викликати через API кількома рядками коду, а найцікавіше починається тоді, коли модель не лише відповідає текстом, а й виконує дії. Саме це і є AI-агент.

У цій статті ви покроково створите свого першого AI-агента на Python — консольного помічника, який розуміє запити звичайною мовою («Додай задачу підготувати домашнє завдання з Python на завтра»), сам вирішує, який інструмент викликати, і веде список задач у файлі. Без фреймворків і «магії»: близько двохсот рядків зрозумілого коду, офіційна бібліотека anthropic і стандартні модулі Python.

Чому саме Python? Це найпоширеніша мова для роботи зі штучним інтелектом: для неї першими виходять SDK провайдерів моделей, на ній пишуть більшість AI-бібліотек, а синтаксис достатньо простий, щоб новачок читав код як текст. Щоб пройти туторіал, вистачить базових навичок: запускати команди в терміналі, розуміти змінні, функції та словники. Якщо цих знань поки немає, не страшно — код можна просто повторити, а в кінці ми розберемо, які теми варто вивчити, щоб писати таких агентів самостійно. Системно пройти цей шлях від основ мови до власних проєктів можна на курсі Python Developer + AI від Prog Academy.

Що таке AI-агент?

AI-агент — це програма, у якій велика мовна модель (LLM) отримує задачу, сама вирішує, які дії виконати, викликає для цього інструменти і використовує їхні результати, щоб дійти до відповіді. Інструментом може бути будь-яка функція у вашому коді: створити задачу, знайти запис у базі, надіслати запит до зовнішнього API.

AI-агент і звичайний чат-бот

Звичайний чат-бот працює за схемою «питання → відповідь»: ви пишете повідомлення, модель відповідає текстом, і на цьому все. Вона може порадити, як додати задачу до списку, але сама її не додасть. Агент відрізняється трьома речами:

• Інструменти. Програміст описує функції, які модель може «попросити» викликати, — з назвою, описом і параметрами.
• Рішення. Модель сама визначає, чи потрібен інструмент, який саме і з якими аргументами.
• Цикл виконання. Результат інструменту повертається моделі, і вона вирішує, що робити далі: викликати ще один інструмент чи відповісти користувачу.

LLM, інструменти й цикл виконання

Важливий момент, який часто плутають новачки: модель сама нічого не виконує. Вона повертає структуровану відповідь на кшталт «виклич функцію add_task з параметрами title і due_date». Виконує функцію ваш Python-код, і саме він вирішує, чи дозволена ця дія. Цей механізм називають function calling, або tool use.

Як агент вирішує, який інструмент використати

Модель не «знає» ваш код. Вона бачить лише три речі: системну інструкцію (хто вона і які правила), опис інструментів (назва, пояснення, JSON Schema параметрів) та історію діалогу. На цій основі вона обирає дію. Тому якість агента напряму залежить від того, наскільки зрозуміло ви описали інструменти: розмитий опис — випадкові рішення, чіткий опис — передбачувана поведінка. Докладно механізм описано в документації Anthropic про tool use.

Де застосовують AI-агентів

• Особисті помічники — задачі, нотатки, календар, нагадування.
• Підтримка клієнтів — відповіді за базою знань і перевірка статусу замовлення через API.
• Робота з даними — запити до бази, звіти, пошук аномалій.
• Розробка — асистенти, які читають код, запускають тести й пропонують виправлення.
• Автоматизація бізнес-процесів — обробка заявок, листів і документів. Як обрати такий процес і порахувати окупність, ми розібрали в статті «AI-агенти для бізнесу: впровадження та окупність».

Чому Python для AI-агентів?

Python для штучного інтелекту — фактичний стандарт, і для агентів це особливо помітно. Ось що робить його зручним саме для такої задачі:

• Читабельний синтаксис. Логіка агента — це умови, цикли й виклики функцій. На Python вона читається майже як опис алгоритму, тож легше помітити помилку.
• Інтеграція з API. Офіційні SDK Anthropic, OpenAI, Google та інших провайдерів з'являються для Python серед перших. Для будь-якого іншого сервісу є httpx або requests.
• AI-бібліотеки. Фреймворки для агентів (LangGraph, LlamaIndex, Pydantic AI), інструменти для роботи з векторними базами та машинного навчання здебільшого орієнтовані на Python.
• Обробка даних. Модулі json і csv, бібліотеки pandas і NumPy — усе, щоб підготувати дані для агента й обробити його результати. Детальніше — у статті «Python для аналізу даних».
• Автоматизація. Робота з файлами, розклад запусків, скрипти для рутинних задач — на Python це кілька рядків.

Для новачка це означає плавну траєкторію: ті самі знання, з якими ви пишете перший скрипт для перейменування файлів, згодом стають основою для програм, що викликають мовні моделі й діють від імені користувача. Між «Hello, world» і AI-агентом немає прірви — є послідовність навичок, яку можна пройти крок за кроком.

Що ми створимо: AI Task Assistant

Наш проєкт — AI Task Assistant, консольний помічник для списку задач. Він працює так:

1. Отримує запит звичайною мовою — українською, російською чи англійською.
2. Визначає намір користувача: додати задачу, показати список або позначити задачу виконаною.
3. Обирає відповідний інструмент — одну з трьох Python-функцій.
4. Виконує дозволену дію: наш код перевіряє дані й записує зміни у файл tasks.json.
5. Повертає результат коротким повідомленням.

Наприклад, на запит «Додай задачу підготувати домашнє завдання з Python на завтра» агент викличе інструмент add_task, сам перетворить «завтра» на конкретну дату у форматі YYYY-MM-DD і підтвердить, що задачу створено.

Свідомі обмеження проєкту: агент не видаляє задачі, не має доступу до інших файлів і не може запускати команди операційної системи. Це не недолік, а приклад правильного підходу — давати агенту рівно ті права, які потрібні для його задачі.

Що потрібно перед початком

1. Python 3.10 або новіший

Поточна версія бібліотеки anthropic (гілка 1.x) потребує Python 3.10+. Приклад у статті перевірено на Python 3.12 з anthropic 1.6.0. Радимо ставити актуальну стабільну версію з python.org; статус підтримки кожної версії — на сторінці версій Python.

• Windows: завантажте інсталятор з python.org і під час встановлення позначте пункт Add python.exe to PATH. Перевірка: py --version.
• macOS: інсталятор з python.org або brew install python, якщо у вас є Homebrew. Перевірка: python3 --version.
• Linux (Ubuntu/Debian): sudo apt install python3 python3-venv python3-pip. Перевірка: python3 --version.

2. Папка проєкту та віртуальне середовище

Віртуальне середовище ізолює бібліотеки проєкту від системного Python, щоб різні проєкти не конфліктували між собою.

macOS і Linux:

mkdir ai-task-agent
cd ai-task-agent
python3 -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

mkdir ai-task-agent
cd ai-task-agent
py -m venv .venv
.venv\Scripts\Activate.ps1

Якщо PowerShell не дає запустити скрипт активації, відкрийте звичайний «Командний рядок» (cmd) і виконайте .venv\Scripts\activate.bat. Після активації на початку рядка терміналу з'явиться (.venv).

3. Встановлення залежностей

Нам потрібна лише одна зовнішня бібліотека — офіційний Python SDK Anthropic. Решта (json, datetime, pathlib) входить у стандартну бібліотеку Python.

python -m pip install "anthropic>=1.6,<2"

Обмеження версії <2 захищає від несумісних змін у майбутній мажорній версії SDK. Команда однакова для всіх систем, якщо віртуальне середовище активоване.

4. API-ключ

Створіть акаунт у Claude Console і згенеруйте ключ у розділі API Keys. Ключ — це пароль до вашого платного акаунта: кожен, хто його знає, може витрачати ваші кошти.

5. Змінна середовища

Задайте ключ у тому самому вікні терміналу, де запускатимете агента:

# macOS і Linux
export ANTHROPIC_API_KEY="ваш-ключ"

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "ваш-ключ"

:: Windows cmd
set ANTHROPIC_API_KEY=ваш-ключ

Так змінна діє лише в поточній сесії терміналу: після перезапуску її треба задати знову. Це незручно, але безпечно для першого проєкту.

Покрокова інструкція: пишемо AI-агента на Python

Увесь код агента розміщується в одному файлі agent.py. Нижче він розбитий на п'ять частин з поясненнями: вставляйте їх у файл по черзі, одну за одною. Повний файл цілком — наприкінці розділу.

Крок 1. Створіть проєкт

Якщо ви виконали підготовку, у вас уже є папка ai-task-agent з активованим середовищем .venv. Відкрийте її в редакторі коду (наприклад, VS Code) і створіть порожній файл agent.py. Файл tasks.json створювати не потрібно: агент створить його сам під час першого запису.

Крок 2. Встановіть залежності

Перевірте, що SDK встановлено саме у віртуальне середовище:

python -c "import anthropic; print(anthropic.__version__)"

Команда має вивести номер версії, наприклад 1.6.0. Якщо бачите ModuleNotFoundError, середовище не активоване або бібліотека встановлена в інший Python — дивіться розділ «Типові помилки».

Крок 3. Налаштуйте API

Переконайтеся, що змінна ANTHROPIC_API_KEY задана в поточному терміналі. SDK автоматично читає ключ саме з неї, тож у коді достатньо написати anthropic.Anthropic() — без жодних паролів у тексті програми. Додатково наш main() перевіряє змінну перед стартом і зрозуміло повідомляє, якщо її немає.

Крок 4. Підключіть мовну модель

Перша частина файлу — імпорти та налаштування. MODEL — назва моделі, MAX_TOKENS — максимальна довжина однієї відповіді, MAX_STEPS — запобіжник, який не дасть агенту нескінченно викликати інструменти.

"""AI Task Assistant — перший AI-агент на Python.

Агент отримує запит природною мовою, сам вирішує, який інструмент викликати,
виконує дозволену дію зі списком задач і повертає результат.
"""

import json
import os
import sys
from datetime import date
from pathlib import Path

import anthropic

MODEL = "claude-opus-5"
MAX_TOKENS = 16000
MAX_STEPS = 5  # скільки разів поспіль агент може викликати інструменти за один запит
TASKS_FILE = Path(__file__).with_name("tasks.json")

Крок 5. Визначте інструмент для керування задачами

Інструменти — це звичайні Python-функції. Зверніть увагу: кожна функція сама перевіряє вхідні дані. Модель може помилитися з форматом дати або передати порожню назву, тому довіряти її аргументам без перевірки не можна. Функції кидають ValueError з людським поясненням — пізніше цей текст повернеться моделі, і вона зможе виправитися.

# ---------- 1. Сховище: звичайний JSON-файл поруч зі скриптом ----------

def load_tasks() -> list[dict]:
    if not TASKS_FILE.exists():
        return []
    return json.loads(TASKS_FILE.read_text(encoding="utf-8"))


def save_tasks(tasks: list[dict]) -> None:
    TASKS_FILE.write_text(
        json.dumps(tasks, ensure_ascii=False, indent=2), encoding="utf-8"
    )


# ---------- 2. Інструменти: звичайні Python-функції з перевіркою даних ----------

def add_task(title: str, due_date: str | None = None) -> dict:
    """Створює задачу. due_date — рядок YYYY-MM-DD або None."""
    if not isinstance(title, str) or not title.strip():
        raise ValueError("Назва задачі не може бути порожньою.")
    title = title.strip()
    if len(title) > 200:
        raise ValueError("Назва задачі задовга: максимум 200 символів.")
    if due_date is not None:
        try:
            due_date = date.fromisoformat(due_date).isoformat()
        except (TypeError, ValueError):
            raise ValueError("Дата має бути у форматі YYYY-MM-DD.") from None

    tasks = load_tasks()
    task = {
        "id": max((t["id"] for t in tasks), default=0) + 1,
        "title": title,
        "due_date": due_date,
        "done": False,
    }
    tasks.append(task)
    save_tasks(tasks)
    return task


def list_tasks() -> list[dict]:
    """Повертає всі задачі."""
    return load_tasks()


def complete_task(task_id: int) -> dict:
    """Позначає задачу виконаною."""
    if not isinstance(task_id, int) or isinstance(task_id, bool):
        raise ValueError("task_id має бути цілим числом.")
    tasks = load_tasks()
    for task in tasks:
        if task["id"] == task_id:
            task["done"] = True
            save_tasks(tasks)
            return task
    raise ValueError(f"Задачу з id={task_id} не знайдено.")


# Білий список: агент може викликати ТІЛЬКИ ці функції, і нічого іншого.
TOOL_FUNCTIONS = {
    "add_task": add_task,
    "list_tasks": list_tasks,
    "complete_task": complete_task,
}

Словник TOOL_FUNCTIONS — це білий список: агент може викликати лише ці три функції. Навіть якщо модель «вигадає» інструмент на кшталт run_shell, код його не знайде й нічого не виконає.

Далі описуємо інструменти для моделі: назва, пояснення, коли їх використовувати, і JSON Schema параметрів. Параметр "strict": True вмикає суворий режим, у якому аргументи моделі гарантовано відповідають схемі. Там само — системна інструкція: у ній ми повідомляємо моделі сьогоднішню дату (інакше вона не зможе порахувати «завтра») і пояснюємо, як поводитися з незрозумілими та непідтримуваними запитами.

# ---------- 3. Опис інструментів для моделі (JSON Schema) ----------

TOOLS = [
    {
        "name": "add_task",
        "description": (
            "Додає нову задачу до списку користувача. Використовуй, коли "
            "користувач просить щось додати, запам'ятати або нагадати."
        ),
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "Коротка назва задачі, до 200 символів.",
                },
                "due_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Дедлайн у форматі YYYY-MM-DD, якщо користувач його назвав.",
                },
            },
            "required": ["title"],
            "additionalProperties": False,
        },
    },
    {
        "name": "list_tasks",
        "description": "Повертає всі задачі користувача з id, дедлайном і статусом.",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {},
            "additionalProperties": False,
        },
    },
    {
        "name": "complete_task",
        "description": (
            "Позначає задачу виконаною за її id. Якщо id невідомий, "
            "спочатку виклич list_tasks."
        ),
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "task_id": {"type": "integer", "description": "id задачі."},
            },
            "required": ["task_id"],
            "additionalProperties": False,
        },
    },
]


def system_prompt() -> str:
    today = date.today()
    return (
        "Ти — помічник, який керує списком задач користувача. "
        f"Сьогодні {today.isoformat()} ({today.strftime('%A')}). "
        "Для роботи із задачами використовуй лише надані інструменти. "
        "Відносні дати («завтра», «у п'ятницю») переводь у формат YYYY-MM-DD. "
        "Якщо з запиту незрозуміло, яку саме задачу створити, постав одне "
        "уточнювальне питання і нічого не створюй. Якщо користувач просить "
        "про те, чого твої інструменти не вміють, чесно скажи про це. "
        "Відповідай коротко, мовою користувача."
    )

Крок 6. Реалізуйте цикл агента

Це серце програми. Функція run_tool безпечно виконує інструмент, який обрала модель, і перетворює результат або помилку на текст. Функція run_agent реалізує цикл зі схеми вище:

1. Надсилаємо моделі історію діалогу, системну інструкцію та опис інструментів.
2. Якщо модель відмовилася відповідати (refusal) або відповідь обірвалася через ліміт (max_tokens), зупиняємося з помилкою.
3. Якщо модель хоче викликати інструменти (stop_reason == "tool_use"), виконуємо кожен і повертаємо усі результати одним повідомленням з тими самими tool_use_id.
4. Якщо інструменти більше не потрібні, повертаємо текстову відповідь користувачу.

# ---------- 4. Виконання інструменту, який обрала модель ----------

def run_tool(name: str, tool_input: dict) -> tuple[str, bool]:
    """Повертає (результат у вигляді тексту, чи сталася помилка)."""
    func = TOOL_FUNCTIONS.get(name)
    if func is None:
        return f"Невідомий інструмент: {name}", True
    try:
        result = func(**tool_input)
    except (TypeError, ValueError) as error:
        return f"Помилка: {error}", True
    return json.dumps(result, ensure_ascii=False), False


class AgentError(Exception):
    """Агент не зміг завершити запит."""


# ---------- 5. Цикл агента: модель -> інструмент -> модель -> ... ----------

def run_agent(client: anthropic.Anthropic, messages: list) -> str:
    for _ in range(MAX_STEPS):
        response = client.messages.create(
            model=MODEL,
            max_tokens=MAX_TOKENS,
            system=system_prompt(),
            tools=TOOLS,
            messages=messages,
        )

        if response.stop_reason == "refusal":
            raise AgentError("Модель відмовилася виконувати цей запит.")
        if response.stop_reason == "max_tokens":
            raise AgentError("Відповідь обірвалася: збільште MAX_TOKENS.")

        # Зберігаємо відповідь моделі повністю — разом з блоками tool_use.
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            return "".join(b.text for b in response.content if b.type == "text")

        tool_results = []
        for block in response.content:
            if block.type != "tool_use":
                continue
            print(f"  [інструмент] {block.name} {json.dumps(block.input, ensure_ascii=False)}")
            content, is_error = run_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": content,
                "is_error": is_error,
            })
        # Усі результати інструментів повертаємо одним повідомленням.
        messages.append({"role": "user", "content": tool_results})

    raise AgentError(f"Агент не впорався за {MAX_STEPS} кроків.")

Помилки інструментів не зупиняють програму: вони повертаються моделі з позначкою is_error: True. Отримавши повідомлення «Дата має бути у форматі YYYY-MM-DD», модель може повторити виклик з правильною датою або уточнити дату в користувача.

Крок 7. Запустіть застосунок

Остання частина — діалог у терміналі. Історія повідомлень зберігається в списку messages, тому агент пам'ятає контекст у межах сесії. Помилки API обробляються окремо: неправильний ключ і неіснуюча модель завершують програму з поясненням, а тимчасові збої лише прибирають невдалий крок з історії, щоб діалог можна було продовжити.

# ---------- 6. Діалог у терміналі ----------

def main() -> None:
    if not os.environ.get("ANTHROPIC_API_KEY"):
        sys.exit("Не знайдено ANTHROPIC_API_KEY. Задайте змінну середовища і запустіть знову.")

    client = anthropic.Anthropic()  # ключ береться зі змінної середовища
    messages: list = []
    print("AI Task Assistant. Напишіть запит або «вихід», щоб завершити.")

    while True:
        try:
            user_input = input("\nВи: ").strip()
        except (EOFError, KeyboardInterrupt):
            break
        if user_input.lower() in {"вихід", "exit", "quit"}:
            break
        if not user_input:
            continue

        start = len(messages)
        messages.append({"role": "user", "content": user_input})
        try:
            answer = run_agent(client, messages)
        except anthropic.AuthenticationError:
            sys.exit("Неправильний API-ключ. Перевірте ANTHROPIC_API_KEY.")
        except anthropic.NotFoundError:
            sys.exit(f"Модель {MODEL} не знайдено. Перевірте значення MODEL.")
        except (AgentError, anthropic.APIError) as error:
            # Невдалий крок прибираємо з історії, щоб діалог можна було продовжити.
            del messages[start:]
            answer = f"Не вдалося виконати запит: {error}"
        print(f"Агент: {answer}")


if __name__ == "__main__":
    main()

Збережіть файл і запустіть агента:

python agent.py

"""AI Task Assistant — перший AI-агент на Python.

Агент отримує запит природною мовою, сам вирішує, який інструмент викликати,
виконує дозволену дію зі списком задач і повертає результат.
"""

import json
import os
import sys
from datetime import date
from pathlib import Path

import anthropic

MODEL = "claude-opus-5"
MAX_TOKENS = 16000
MAX_STEPS = 5  # скільки разів поспіль агент може викликати інструменти за один запит
TASKS_FILE = Path(__file__).with_name("tasks.json")


# ---------- 1. Сховище: звичайний JSON-файл поруч зі скриптом ----------

def load_tasks() -> list[dict]:
    if not TASKS_FILE.exists():
        return []
    return json.loads(TASKS_FILE.read_text(encoding="utf-8"))


def save_tasks(tasks: list[dict]) -> None:
    TASKS_FILE.write_text(
        json.dumps(tasks, ensure_ascii=False, indent=2), encoding="utf-8"
    )


# ---------- 2. Інструменти: звичайні Python-функції з перевіркою даних ----------

def add_task(title: str, due_date: str | None = None) -> dict:
    """Створює задачу. due_date — рядок YYYY-MM-DD або None."""
    if not isinstance(title, str) or not title.strip():
        raise ValueError("Назва задачі не може бути порожньою.")
    title = title.strip()
    if len(title) > 200:
        raise ValueError("Назва задачі задовга: максимум 200 символів.")
    if due_date is not None:
        try:
            due_date = date.fromisoformat(due_date).isoformat()
        except (TypeError, ValueError):
            raise ValueError("Дата має бути у форматі YYYY-MM-DD.") from None

    tasks = load_tasks()
    task = {
        "id": max((t["id"] for t in tasks), default=0) + 1,
        "title": title,
        "due_date": due_date,
        "done": False,
    }
    tasks.append(task)
    save_tasks(tasks)
    return task


def list_tasks() -> list[dict]:
    """Повертає всі задачі."""
    return load_tasks()


def complete_task(task_id: int) -> dict:
    """Позначає задачу виконаною."""
    if not isinstance(task_id, int) or isinstance(task_id, bool):
        raise ValueError("task_id має бути цілим числом.")
    tasks = load_tasks()
    for task in tasks:
        if task["id"] == task_id:
            task["done"] = True
            save_tasks(tasks)
            return task
    raise ValueError(f"Задачу з id={task_id} не знайдено.")


# Білий список: агент може викликати ТІЛЬКИ ці функції, і нічого іншого.
TOOL_FUNCTIONS = {
    "add_task": add_task,
    "list_tasks": list_tasks,
    "complete_task": complete_task,
}

# ---------- 3. Опис інструментів для моделі (JSON Schema) ----------

TOOLS = [
    {
        "name": "add_task",
        "description": (
            "Додає нову задачу до списку користувача. Використовуй, коли "
            "користувач просить щось додати, запам'ятати або нагадати."
        ),
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "Коротка назва задачі, до 200 символів.",
                },
                "due_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Дедлайн у форматі YYYY-MM-DD, якщо користувач його назвав.",
                },
            },
            "required": ["title"],
            "additionalProperties": False,
        },
    },
    {
        "name": "list_tasks",
        "description": "Повертає всі задачі користувача з id, дедлайном і статусом.",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {},
            "additionalProperties": False,
        },
    },
    {
        "name": "complete_task",
        "description": (
            "Позначає задачу виконаною за її id. Якщо id невідомий, "
            "спочатку виклич list_tasks."
        ),
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "task_id": {"type": "integer", "description": "id задачі."},
            },
            "required": ["task_id"],
            "additionalProperties": False,
        },
    },
]


def system_prompt() -> str:
    today = date.today()
    return (
        "Ти — помічник, який керує списком задач користувача. "
        f"Сьогодні {today.isoformat()} ({today.strftime('%A')}). "
        "Для роботи із задачами використовуй лише надані інструменти. "
        "Відносні дати («завтра», «у п'ятницю») переводь у формат YYYY-MM-DD. "
        "Якщо з запиту незрозуміло, яку саме задачу створити, постав одне "
        "уточнювальне питання і нічого не створюй. Якщо користувач просить "
        "про те, чого твої інструменти не вміють, чесно скажи про це. "
        "Відповідай коротко, мовою користувача."
    )


# ---------- 4. Виконання інструменту, який обрала модель ----------

def run_tool(name: str, tool_input: dict) -> tuple[str, bool]:
    """Повертає (результат у вигляді тексту, чи сталася помилка)."""
    func = TOOL_FUNCTIONS.get(name)
    if func is None:
        return f"Невідомий інструмент: {name}", True
    try:
        result = func(**tool_input)
    except (TypeError, ValueError) as error:
        return f"Помилка: {error}", True
    return json.dumps(result, ensure_ascii=False), False


class AgentError(Exception):
    """Агент не зміг завершити запит."""


# ---------- 5. Цикл агента: модель -> інструмент -> модель -> ... ----------

def run_agent(client: anthropic.Anthropic, messages: list) -> str:
    for _ in range(MAX_STEPS):
        response = client.messages.create(
            model=MODEL,
            max_tokens=MAX_TOKENS,
            system=system_prompt(),
            tools=TOOLS,
            messages=messages,
        )

        if response.stop_reason == "refusal":
            raise AgentError("Модель відмовилася виконувати цей запит.")
        if response.stop_reason == "max_tokens":
            raise AgentError("Відповідь обірвалася: збільште MAX_TOKENS.")

        # Зберігаємо відповідь моделі повністю — разом з блоками tool_use.
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            return "".join(b.text for b in response.content if b.type == "text")

        tool_results = []
        for block in response.content:
            if block.type != "tool_use":
                continue
            print(f"  [інструмент] {block.name} {json.dumps(block.input, ensure_ascii=False)}")
            content, is_error = run_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": content,
                "is_error": is_error,
            })
        # Усі результати інструментів повертаємо одним повідомленням.
        messages.append({"role": "user", "content": tool_results})

    raise AgentError(f"Агент не впорався за {MAX_STEPS} кроків.")


# ---------- 6. Діалог у терміналі ----------

def main() -> None:
    if not os.environ.get("ANTHROPIC_API_KEY"):
        sys.exit("Не знайдено ANTHROPIC_API_KEY. Задайте змінну середовища і запустіть знову.")

    client = anthropic.Anthropic()  # ключ береться зі змінної середовища
    messages: list = []
    print("AI Task Assistant. Напишіть запит або «вихід», щоб завершити.")

    while True:
        try:
            user_input = input("\nВи: ").strip()
        except (EOFError, KeyboardInterrupt):
            break
        if user_input.lower() in {"вихід", "exit", "quit"}:
            break
        if not user_input:
            continue

        start = len(messages)
        messages.append({"role": "user", "content": user_input})
        try:
            answer = run_agent(client, messages)
        except anthropic.AuthenticationError:
            sys.exit("Неправильний API-ключ. Перевірте ANTHROPIC_API_KEY.")
        except anthropic.NotFoundError:
            sys.exit(f"Модель {MODEL} не знайдено. Перевірте значення MODEL.")
        except (AgentError, anthropic.APIError) as error:
            # Невдалий крок прибираємо з історії, щоб діалог можна було продовжити.
            del messages[start:]
            answer = f"Не вдалося виконати запит: {error}"
        print(f"Агент: {answer}")


if __name__ == "__main__":
    main()

Крок 8. Перевірте результат

Після запуску агент чекає на запит. Спробуйте, наприклад, «Додай задачу підготувати домашнє завдання з Python на завтра». У терміналі з'явиться рядок з інструментом, який обрала модель, — щось на кшталт [інструмент] add_task {"title": "Підготувати домашнє завдання з Python", "due_date": "…"} з завтрашньою датою, — а потім коротке підтвердження. Точне формулювання назви задачі й відповіді залежить від моделі та може відрізнятися. Відкрийте tasks.json: там має бути запис з "id": 1 і "done": false. Щоб завершити роботу, введіть «вихід» або натисніть Ctrl+C.

Як протестувати AI-агента

Відповіді мовної моделі не є повністю детермінованими: той самий запит може дати трохи інше формулювання. Тому агента тестують за поведінкою — який інструмент викликано, які дані записано, як оброблено помилку, — а не за точним текстом відповіді.

Перевірка інструментів без API

Інструменти — звичайні функції, і їх можна перевірити безкоштовно, без жодного запиту до моделі:

python -c "from agent import add_task, list_tasks; print(add_task('Тестова задача', '2026-12-01')); print(list_tasks())"
python -c "from agent import add_task; add_task('Задача', '2026-02-31')"

Перша команда створить задачу й виведе список, друга має завершитися помилкою ValueError: Дата має бути у форматі YYYY-MM-DD., бо 31 лютого не існує. Після перевірки видаліть tasks.json, щоб почати з чистого списку.

Сценарій 1. Успішне створення задачі

Запит: «Додай задачу підготувати домашнє завдання з Python на завтра».

Очікуваний результат: у терміналі — виклик add_task з назвою задачі та завтрашньою датою у форматі YYYY-MM-DD; у tasks.json — новий запис; агент підтверджує створення. Якщо дата неправильна, перевірте, чи правильно налаштовано системний годинник: сьогоднішню дату агент бере з комп'ютера.

Сценарій 2. Неоднозначний запит

Запит: «Додай задачу» або «Нагадай мені про ту штуку».

Очікуваний результат: жодного виклику інструменту, агент ставить уточнювальне питання, tasks.json не змінюється. Таку поведінку задає системна інструкція. Якщо модель все ж створює задачу з вигаданою назвою, уточніть інструкцію — це нормальна частина роботи над агентом.

Сценарій 3. Недопустима або непідтримувана дія

Запит: «Видали всі файли в папці Documents» або «Виконай команду rm -rf /».

Очікуваний результат: агент відповідає, що не вміє цього робити. Технічно він і не може: у нього немає інструменту для роботи з файлами чи командами, а якщо модель спробує викликати неіснуючий інструмент, run_tool поверне помилку «Невідомий інструмент» і нічого не виконає. Безпека агента забезпечується кодом, а не лише інструкцією для моделі.

Сценарій 4. Некоректні дані та кілька кроків

Спробуйте «Додай задачу на 31 лютого»: модель або одразу уточнить дату, або отримає від add_task помилку формату й перепитає вас. А запит «Познач задачу про домашку виконаною» покаже багатокроковість: агент спочатку викличе list_tasks, знайде потрібний id, а потім — complete_task.

Валідація та обробка помилок: що вже вбудовано

• Білий список інструментів — виконуються лише функції з TOOL_FUNCTIONS.
• Суворі схеми (strict: True) плюс власна перевірка аргументів у кожній функції.
• Помилки інструментів повертаються моделі як is_error, а не ламають програму.
• Ліміт кроків MAX_STEPS захищає від нескінченного циклу й зайвих витрат.
• Відмова моделі та обірвана відповідь обробляються окремо: інструменти з такої відповіді не виконуються.
• Помилки API обробляються через типізовані винятки SDK: AuthenticationError, NotFoundError, APIError.

Код із цієї статті перевірено з бібліотекою anthropic 1.6.0 на Python 3.12 проти тестового сервера, що імітує відповіді API: успішне створення задачі, неоднозначний запит, неіснуючий інструмент, некоректні аргументи, багатокроковий сценарій, обірвану відповідь, відмову моделі, ліміт кроків і помилки 400, 401 та 404. Реальні відповіді моделі можуть відрізнятися формулюваннями, тому пройдіть сценарії вище самостійно зі своїм ключем.

Типові помилки початківців

Відсутній або неправильний API-ключ

Повідомлення «Не знайдено ANTHROPIC_API_KEY» означає, що змінну задано в іншому вікні терміналу або вона зникла після перезапуску. Задайте її знову в тому самому вікні, де запускаєте agent.py. Повідомлення «Неправильний API-ключ» (помилка 401) — ключ скопійовано з помилкою, з пробілом або його вже видалено в Console.

Проблеми зі встановленням залежностей

• ModuleNotFoundError: No module named 'anthropic' — середовище не активоване або бібліотека встановлена в інший інтерпретатор. Активуйте .venv і встановлюйте через python -m pip, а не просто pip: так пакет гарантовано потрапить у той Python, яким ви запускаєте скрипт.
• ERROR: No matching distribution found for anthropic… — застаріла версія Python. Поточна гілка SDK потребує Python 3.10+.
• На Linux python3 -m venv повідомляє про відсутність ensurepip — встановіть пакет python3-venv.

Неправильна конфігурація моделі

Помилка 404 з повідомленням «Модель … не знайдено» означає одрук у назві моделі або модель, яку вже вивели з обігу. Актуальні ідентифікатори — в огляді моделей. Помилка 400 зазвичай означає некоректний запит або проблему з акаунтом, наприклад недостатній баланс, — текст помилки підкаже причину.

Помилки під час виконання інструментів

Якщо ви додаєте власні інструменти, пам'ятайте: run_tool перехоплює лише TypeError і ValueError. Інші винятки, наприклад PermissionError під час запису файлу, зупинять програму. Це свідоме рішення: неочікувану помилку краще побачити одразу, ніж непомітно передати моделі. Коли зрозумієте причину, обробіть її явно.

Надмірні дозволи

Найнебезпечніша помилка — дати агенту «універсальний» інструмент: виконання команд терміналу, eval() для довільного коду чи доступ до всієї файлової системи. Модель може помилитися, а текст, який вона обробляє, може містити шкідливі інструкції (так звана prompt injection). Правило просте: кожен інструмент робить одну вузьку дію, перевіряє свої аргументи, а незворотні операції потребують підтвердження людини.

Витрати на API

Витрати ростуть непомітно: кожен крок циклу — окремий платний запит, а історія діалогу з кожним повідомленням стає довшою. Слідкуйте за витратами в Console, встановіть ліміт, не збільшуйте MAX_STEPS без потреби й перезапускайте агента, щоб почати діалог з чистою історією.

Як покращити агента

• Додаткові інструменти. Редагування задачі, пріоритети, фільтр за датою. Кожен новий інструмент — функція з перевіркою даних плюс опис у TOOLS. Знадобиться: функції, словники, робота з датами.
• Постійне сховище. Замість JSON-файлу — база SQLite через вбудований модуль sqlite3, щоб задачі не пошкоджувалися й швидко шукалися. Знадобиться: основи SQL і роботи з базами даних.
• Інтеграції з зовнішніми API. Календар, пошта, Telegram-бот, що надсилає нагадування. Знадобиться: API, HTTP-запити, JSON, автентифікація.
• Логування. Модуль logging замість print: записувати кожен виклик інструменту, аргументи й помилки, щоб розбирати, що саме зробив агент. Знадобиться: стандартна бібліотека, декоратори.
• Безпека. Мінімальні права, перевірка всіх аргументів, ліміти на кількість дій, окремі облікові записи з обмеженим доступом для інтеграцій. Знадобиться: обробка винятків, розуміння автентифікації.
• Підтвердження людиною для чутливих дій. Наприклад, інструмент delete_task, який перед видаленням питає «Видалити задачу 3? (y/n)» і виконується лише після «y». Цей підхід називають human-in-the-loop. Знадобиться: умови та керування потоком програми.

Коли інструментів стане більше, варто подивитися на готові рішення: tool runner в SDK Anthropic бере цикл агента на себе, а протокол MCP дозволяє підключати до агента готові інтеграції. Але саме цикл, написаний власноруч, дає розуміння того, що відбувається всередині будь-якого фреймворку. Ширший огляд AI-інструментів для розробників — у статті «AI-інструменти для програмістів».

Які навички Python потрібні, щоб створювати AI-агентів?

Подивіться на код ще раз: у ньому немає нічого «штучноінтелектуального», крім одного виклику client.messages.create. Усе інше — звичайне програмування на Python. Саме тому вміння програмувати на Python з нуля важливіше за знання конкретного AI-фреймворку: фреймворки змінюються щороку, а основи залишаються.

Як ці теми лягають на програму курсу Python у Prog Academy:

• Python Start — змінні та приведення типів, умовні й булеві оператори, цикли, списки, рядки, словники, функції та передача параметрів, читання й запис файлів. Це все, що потрібно, щоб читати код нашого агента.
• Python для Data Analytics — робота з JSON і CSV, *args і **kwargs, декоратори (зокрема для логування), вступ до ООП, обробка винятків (try…except, else, finally), бази даних і основи SQL.
• Python та Django (бонус) — ООП і спадкування, модулі, робота з винятковими ситуаціями, Django, запити й відповіді, бази даних, авторизація та безпека — фундамент для перетворення агента на вебсервіс.
• AI Start — практичне використання ChatGPT і Claude, промпти для розробників.

Асинхронного програмування в переліку тем курсу немає: його зазвичай вивчають пізніше, коли агент перетворюється на вебсервіс з багатьма користувачами.

Де вивчати Python з нуля?

Сьогодні AI-асистент згенерує подібний код за хвилину. Навіщо ж тоді вчити мову? Тому що скопіювати код і розуміти код — різні навички. Коли агент поводиться не так, як очікувалося, — записує не ту дату, зациклюється, падає з винятком, — потрібно прочитати трасування помилки, знайти місце, де дані змінилися, і зрозуміти, чи винна модель, чи ваш код. AI-згенерований код часто виглядає переконливо, але містить неочевидні помилки: пропущену перевірку аргументів, небезпечний eval(), неправильну обробку історії повідомлень. Помітити їх може лише той, хто знає основи.

Кілька порад, як навчання Python для початківців перетворити на реальні навички:

• Пишіть код руками. Навіть цей туторіал корисніше набрати, ніж скопіювати: помилки під час набору вчать більше, ніж правильний код.
• Робіть практичні завдання. Читання теорії дає відчуття розуміння, а задачі показують, чи воно справжнє. Особливо цінний зворотний зв'язок: хтось досвідчений побачить у вашому коді те, чого не помітите ви.
• Рухайтеся від вправ до проєктів. Спочатку окремі задачі на цикли й словники, потім маленькі скрипти для себе (перейменувати файли, порахувати витрати), потім програми з API, як наш агент, і нарешті — проєкт для портфоліо.
• Використовуйте AI як наставника, а не як заміну. Просіть пояснити помилку чи незнайому конструкцію, але рішення пишіть самі.

Щоб спробувати без зобов'язань, почніть з безкоштовного курсу Python або підбірки книжок з Python для початківців. Якщо потрібен системний шлях, курси Python з нуля в Prog Academy поєднують теорію, практику з викладачем, домашні завдання зі зворотним зв'язком і дипломний проєкт. Програма курсу Python Developer + AI акредитована в ЄС, розрахована на новачків без технічної освіти, триває 4,5 місяця й проходить онлайн — у групі або індивідуально. Окремий модуль AI Start вчить використовувати AI-інструменти в роботі розробника.

Переглянути програму курсу Python →

Часті запитання

Чи можна створити AI-агента без знання Python?

Простого агента можна зібрати без коду в no-code платформах на кшталт n8n: там модель підключається до інструментів візуально — про цей підхід ми писали в повному гайді з AI Automation. Але щойно потрібна власна логіка, перевірка даних, інтеграція з системою без готового конектора або контроль безпеки, знадобиться код. Скопіювати готовий приклад можна і без знань, проте виправити помилку або змінити поведінку агента без розуміння Python не вийде.

Чи складно вивчити Python новачку?

Python вважають однією з найзручніших мов для старту: синтаксис короткий і читабельний, а перші програми працюють уже в перший день. Складність зростає поступово — від змінних і циклів до функцій, роботи з файлами, обробки помилок і ООП. Головне — регулярна практика, а не кількість прочитаної теорії.

Скільки часу потрібно, щоб вивчити Python?

Залежить від мети та регулярності занять. Щоб розуміти код, як у цій статті, потрібні основи: змінні, умови, цикли, функції, словники, файли, JSON і обробка помилок. Для роботи розробником додаються ООП, бази даних, фреймворки та проєкти. Для орієнтиру: повна програма курсу Python у Prog Academy розрахована на 4,5 місяця.

Чи потрібно знати машинне навчання, щоб створювати AI-агентів?

Ні. Агент у цій статті використовує готову мовну модель через API — її не потрібно навчати. Потрібні навички звичайного програміста: викликати API, працювати з JSON, писати функції, перевіряти вхідні дані й обробляти помилки. Машинне навчання знадобиться, якщо ви захочете навчати або донавчати власні моделі.

Чи можна створити AI-агента безкоштовно?

Python, бібліотека anthropic і весь код із цієї статті безкоштовні. Платні запити до API мовної моделі — оплата йде за кількість токенів. Для навчальних експериментів це зазвичай невеликі суми, але варто встановити ліміт витрат в акаунті. Альтернатива — локальні відкриті моделі, але вони потребують потужного комп'ютера й іншого налаштування.

Чим AI-агент відрізняється від чат-бота?

Чат-бот відповідає текстом на повідомлення. AI-агент отримує мету, сам вирішує, який інструмент викликати, виконує дію (наприклад, створює задачу або робить запит до API), бачить результат і вирішує, що робити далі. Модель усередині може бути та сама — різниця в доступі до інструментів і циклі виконання.

Які бібліотеки Python використовують для AI-агентів?

Для простого агента достатньо офіційного SDK провайдера моделі — наприклад, anthropic, як у цій статті. Для складніших систем використовують фреймворки: LangChain і LangGraph, LlamaIndex, Pydantic AI, Claude Agent SDK або OpenAI Agents SDK. Поруч зазвичай працюють pydantic для перевірки даних, httpx чи requests для HTTP-запитів і стандартні модулі json, logging та sqlite3.

Де вивчити Python з нуля?

Почати можна з безкоштовного курсу Python від Prog Academy і книжок для початківців, а для системного навчання з викладачем, перевіркою домашніх завдань і проєктом для портфоліо — пройти курс Python Developer + AI, де програма веде від основ мови до ООП, баз даних і Django.

Висновок

Ви створили повноцінного, хоч і маленького AI-агента: він розуміє запити звичайною мовою, сам обирає один із трьох інструментів, виконує лише дозволені дії, перевіряє дані, обробляє помилки й не може вийти за межі свого білого списку. Головне, що варто винести з цього туторіалу: AI-агент — це звичайна Python-програма, у якій рішення «що зробити далі» ухвалює мовна модель, а контроль залишається за вашим кодом.

Наступні практичні кроки: додайте інструмент delete_task з підтвердженням людиною, перенесіть задачі в SQLite, замініть print на logging і збережіть проєкт у Git — як почати, розповідає стаття «Git для початківців». Кожне таке покращення впирається в основи мови: функції, винятки, роботу з даними, ООП.