ИИ-агенты это модель плюс инструменты: архитектура на 20 строках кода

Слово «агент» сегодня встречается в каждом втором ТЗ. Проблема в том, что один заказчик подразумевает FAQ-бот на две кнопки, а другой хочет автономную систему с доступом на запись в рабочую базу. Цена и риск отличаются на порядок. Источник этого разбора, практический гайд по архитектуре LLM-агентов (Large Language Model, большая языковая модель), который обобщает типичные ошибки команд за год экспериментов. Ниже я прохожу весь путь: от определения до кода и граблей.

Что понадобится

• Доступ к API языковой модели. В примерах используется OpenAI (модель gpt-4.1), но цикл агента одинаков у всех провайдеров. Из российских альтернатив подойдут YandexGPT или GigaChat, если адаптировать формат вызовов
• Python 3.10+ и библиотека openai (ставится через pip install openai)
• Ключ API, прописанный в переменной окружения OPENAI_API_KEY
• Базовое понимание, что такое промпт (текстовая инструкция для модели) и JSON (формат обмена данными)
• Время: разобраться в цикле агента и запустить первый пример можно за 1,5-2 часа

Три ступени: промпт, чат-бот, агент

Прежде чем писать код, нужно понять, где именно проходит граница. ИИ-агенты это языковая модель, которой дали инструменты и запустили в цикле. Вот три ступени, от простого к сложному.

Промпт. Один заход: вопрос на входе, текст на выходе. «Перепиши это письмо вежливее.» Никакой памяти, никаких действий.

Чат-бот. Цепочка промптов с памятью диалога. Помнит контекст беседы, но по-прежнему только говорит, ничего не делает во внешнем мире.

Агент. Модель плюс инструменты плюс право самой выбирать шаги. Получив цель «разберись, почему упал ночной отчёт», агент читает логи, ходит в базу, проверяет гипотезы и возвращает ответ, а не совет «проверьте логи».

Граница проходит по двум признакам: появились ли у модели инструменты (возможность что-то сделать) и есть ли автономия в выборе действий. Чат-бот отвечает. Агент действует.

Пошаговая инструкция: собираем агента на 20 строках

Сердце агента называется петлёй «подумал, сделал, посмотрел».

1. Опишите инструмент как обычную Python-функцию. Модель не видит ваш код напрямую. Она видит JSON-схему инструмента (название, описание, параметры) и вызывает его по имени. Один инструмент, одна функция
2. Соберите реестр инструментов и их схем. Реестр, это словарь, где ключ совпадает с name в схеме. Модель возвращает имя инструмента и аргументы в поле tool_calls, а ваш код находит нужную функцию в словаре и вызывает её
3. Напишите функцию run_agent. Она принимает цель (строку) и лимит шагов. Внутри запускается цикл: на каждой итерации модель получает всю историю сообщений, решает, какой инструмент вызвать (или что задача закрыта), а результат вызова добавляется обратно в историю как сообщение с ролью tool
4. Обработайте ошибки внутри цикла, а не снаружи. Если инструмент упал с исключением, не роняйте агента. Передайте текст ошибки модели как наблюдение: она часто сама скорректирует следующий шаг
5. Установите жёсткий лимит шагов (max_steps). Без лимита агент может зациклиться и сжечь бюджет токенов (минимальных единиц текста, которые модель обрабатывает и за которые вы платите). В примере стоит 12 шагов, для первых экспериментов этого достаточно
6. Запустите агента с простой целью и прочитайте весь лог сообщений. Именно лог покажет, как модель рассуждала, какие инструменты выбирала и где ошибалась. Это и есть наблюдаемость, без неё отладка невозможна

Вот полный код агента:

import json
from openai import OpenAI

client = OpenAI()  # ключ из переменной OPENAI_API_KEY

# Шаг 1: инструмент — обычная функция
def read_file(path: str) -> str:
    with open(path, encoding="utf-8") as f:
        return f.read()

# Шаг 2: реестр и схема
TOOLS = {"read_file": read_file}
tools_schema = [{
    "type": "function",
    "function": {
        "name": "read_file",
        "description": "Прочитать файл по пути",
        "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
}]

# Шаг 3–5: цикл агента
def run_agent(goal: str, max_steps: int = 12) -> str:
    messages = [{"role": "user", "content": goal}]
    for _ in range(max_steps):
        reply = client.chat.completions.create(
            model="gpt-4.1",
            messages=messages,
            tools=tools_schema,
        ).choices[0].message
        messages.append(reply)
        if not reply.tool_calls:
            return reply.content
        for call in reply.tool_calls:
            try:
                args = json.loads(call.function.arguments)
                result = TOOLS[call.function.name](**args)
                content = result if isinstance(result, str) else json.dumps(
                    result, ensure_ascii=False, default=str
                )
            except Exception as e:
                content = f"Ошибка инструмента: {e!r}"
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": content,
            })
    return "Достигнут лимит шагов: задача не закрыта"

Раньше выбор инструмента выбивали из модели текстом в формате Thought / Action / Observation (паттерн ReAct) и разбирали ответ вручную. Сегодня модели отдают вызовы через поле tool_calls, и парсить ничего не нужно. А когда от модели нужен строгий JSON под схему (вытащить поля, заполнить форму), используют structured outputs: ответ гарантированно валиден по схеме, без «почти валидного» текста, который потом падает на парсинге.

Из каких кирпичиков состоит агент?

• Модель (мозг). Рассуждает и принимает решения. На длинной цепочке действий слабая модель накапливает ошибки быстрее, чем успевает их исправлять, поэтому для агентных задач берут модели посильнее
• Инструменты (руки). Поиск, чтение файлов, запросы к API, выполнение кода. Чтобы не писать интеграцию под каждый сервис заново, инструменты подключают через MCP (Model Context Protocol, стандартный протокол подключения инструментов и источников данных к модели)
• Память (знания). Контекстное окно (объём текста, который модель «видит» за один раз) держит короткую память сессии. Когда данных больше, чем влезает в контекст, подключают RAG (Retrieval-Augmented Generation, получение нужных фрагментов из базы знаний ровно тогда, когда они нужны)
• Цикл (скелет). Без петли всё перечисленное осталось бы умным автодополнением

Один агент или несколько?

Не каждой задаче нужен автономный агент. Полезно видеть шкалу и брать минимально достаточный уровень.

Жёсткий сценарий (workflow). Шаги известны заранее и зашиты в код: достать данные, суммировать, разложить по полям. Модель вызывается в фиксированных точках. Предсказуемо, дёшево, легко отлаживать. Большая часть «агентных» задач на деле решается именно здесь.

Один агент с инструментами. Маршрут заранее неизвестен, модель сама выбирает шаги. Для большинства реальных задач этого достаточно.

Мультиагентная система. Оркестратор раздаёт подзадачи агентам-специалистам и собирает результат. Цена и сложность отладки растут нелинейно: ошибку приходится искать не в одном цикле, а в переписке между несколькими.

Практический вывод: начинайте с жёсткого сценария, переходите к агенту только когда сценарий перестаёт справляться, и не трогайте мультиагентность, пока один агент не отлажен.

Что делать с этим прямо сейчас, по ролям

Автору Дзена. Попробуйте собрать агента для подготовки материалов: один инструмент на чтение файла с фактурой, другой на поиск. Вы быстро увидите, где модель справляется сама, а где нужен ваш контроль. Это даст понимание границ ИИ-агента из первых рук, а не из чужих обзоров.

Маркетологу. Когда в следующий раз подрядчик предложит «сделать агента», спросите: это жёсткий сценарий, один агент или мультиагентная система? Ответ определяет бюджет и сроки. Если шаги известны заранее, хватит workflow, и это в разы дешевле.

Предпринимателю. Код из этого разбора работает с OpenAI API. В России прямой доступ ограничен, но цикл агента переносится на YandexGPT и GigaChat с минимальными правками формата вызовов. Главное: не автономия модели решает успех, а то, как выстроены права, лимиты и логирование вокруг неё.

Если вы дочитали до этого места, у вас теперь есть рабочий код агента и понимание, где именно ломаются первые версии. Запустите петлю на двадцати строках, прочитайте лог вызовов и только потом решайте, нужен ли вам фреймворк. Это сэкономит и бюджет, и нервы.