Блог · 8 минут чтения

ИИ-агенты: что это такое, как их делать и почему на Python

ИИ-агент — это языковая модель, которая умеет действовать: выбирает инструмент, запускает его, читает результат и решает, что делать дальше. Ниже — что это значит простыми словами, работающий агент примерно в 40 строк на Python и правила, которые не дают ему сбиться. Каждое правило взято из агента, которого я довёл до релиза.

Цель уходит в модель, модель вызывает инструменты на Python, а перед результатом стоит проверкаЦель уходит в модель, модель вызывает инструменты на Python, а перед результатом стоит проверка

Что такое ИИ-агент

Чат-бот отвечает. Агент действует. Вы даёте ему не вопрос, а цель, и он сам решает, какие шаги сделать.

Любой агент состоит из одних и тех же четырёх частей:

  • Модель, которая принимает решения: Claude, GPT, Gemini или локальная модель.
  • Инструменты, которыми ей разрешено пользоваться: поиск в интернете, чтение файла, запрос к базе данных, отправка письма. Каждый инструмент — обычная функция в вашем коде.
  • Цикл. Модель просит вызвать инструмент, ваш код его запускает, результат возвращается модели, и она выбирает следующий шаг.
  • Условие остановки. Задача выполнена, проверка не прошла или агент исчерпал лимит шагов.

Сама модель ничего не запускает. Она только говорит: «вызови этот инструмент с такими входными данными». Делать это или нет, решает ваш код. Это самое важное, что нужно знать об агентах, и именно поэтому их можно делать безопасными.

Чат-бот, workflow или агент?

Не каждой ИИ-функции нужен агент. Выбирайте самый простой вариант, который справится с задачей.

ТипКто решает, какие шаги делатьКогда использовать
Чат-ботНикто: один вопрос, один ответОтветы на вопросы по вашим собственным материалам
WorkflowВы, в коде, в заданном порядкеШаги каждый раз одни и те же, например еженедельный отчёт
АгентМодель, шаг за шагомСледующий шаг зависит от того, что нашёл предыдущий, например исследование

В большинстве моих проектов есть и то и другое. Фиксированные шаги выполняет код, а агент принимает решения только там, где нужно суждение. Об этом разделении я писал в статье про WAT-фреймворк.

Агент примерно в 40 строк на Python

Этот агент получает список веб-адресов и сообщает, какие из них не работают. У него один инструмент — check_url, обычная функция на Python. Модель решает, какие адреса проверить, и пишет итог.

import json
import urllib.request

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment


def check_url(url: str) -> str:
    """The tool: a normal function. The model never runs it, we do."""
    if not url.startswith("https://"):
        return json.dumps({"url": url, "error": "only https addresses are allowed"})
    try:
        with urllib.request.urlopen(url, timeout=10) as r:
            return json.dumps({"url": url, "status": r.status})
    except Exception as e:
        return json.dumps({"url": url, "error": str(e)})


TOOLS = [{
    "name": "check_url",
    "description": "Fetch one https address and return its HTTP status, or the error.",
    "input_schema": {
        "type": "object",
        "properties": {"url": {"type": "string"}},
        "required": ["url"],
    },
}]

messages = [{"role": "user", "content":
             "Check these pages and tell me which are broken: "
             "https://example.com, https://example.com/missing-page"}]

for step in range(10):  # a hard cap: an agent that can loop forever will
    reply = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024,
                                   tools=TOOLS, messages=messages)
    messages.append({"role": "assistant", "content": reply.content})
    if reply.stop_reason != "tool_use":
        print("".join(b.text for b in reply.content if b.type == "text"))
        break
    results = [{"type": "tool_result", "tool_use_id": b.id, "content": check_url(**b.input)}
               for b in reply.content if b.type == "tool_use"]
    messages.append({"role": "user", "content": results})

Установите библиотеку командой pip install anthropic, задайте API-ключ и запустите. В этом коде три вещи важнее, чем выбор модели:

  • Инструмент сам проверяет входные данные. Он отклоняет всё, что не https. Никогда не рассчитывайте, что модель удержится в рамках правил, которые вы написали в промпте.
  • Описание — это документация. По нему модель решает, когда вызывать инструмент. Если описание расплывчатое, агент путается.
  • У цикла есть предел. Десять шагов, и он останавливается, что бы ни случилось.

Вот и вся идея. Фреймворки вроде LangGraph или CrewAI добавляют сверху память, несколько агентов и повторные попытки, но внутри каждого из них тот же самый цикл.

Как сделать агента, который работает

Демо выше работает с первой попытки. Настоящий агент должен работать и с сотой. Вот правила, которых я держусь:

  1. Начинайте с задачи, а не с модели. Прежде чем писать код, запишите цель, входные данные и критерий готовности. Если вы не можете этого сделать, агент тоже не угадает.
  2. Давайте ему только нужные инструменты. Белый список функций, а не полный доступ к командной строке. Агент в моём видеогенераторе может запускать скрипты самого проекта, ffmpeg и несколько команд только для чтения. Больше ничего.
  3. Пусть код делает то, что у него получается лучше. Загрузка, подсчёт, объединение данных и рендер уходят в инструменты на Python. Модель решает, инструменты исполняют.
  4. Проверяйте результат схемой. Пусть агент возвращает JSON, а вы проверяете его до того, как запустится что-то медленное или дорогое. В моём видеогенераторе раскадровка, которая не прошла проверку по JSON-схеме, до рендера не доходит.
  5. Добавьте проверку, которая может сказать «нет». В моём исследовательском процессе валидатор блокирует отчёт, если у какого-то утверждения нет источника или какая-то ссылка не работает. Правила агенту сообщают, а соблюдать их заставляет код.
  6. Заранее задайте точки, где решает человек. Тот же процесс останавливается в четырёх контрольных точках, например чтобы человек утвердил список конкурентов до запуска девяти исследовательских агентов.
  7. Ограничьте число повторов. Агент-ревьюер в видеогенераторе возвращает SHIP или список правок, и у него максимум два круга.
  8. Логируйте каждый шаг. Сохраняйте каждый вызов инструмента и его результат. Когда агент ошибается, по логу видно, на каком шаге, и чинить нужно именно там.

Почему Python

Агента можно написать на любом языке. Но большая часть этой работы ведётся на Python, и причины тут практические:

  • ИИ-библиотеки сначала выходят для Python. И Anthropic, и OpenAI выпускают официальные библиотеки для Python, а LangGraph, CrewAI, LlamaIndex и Pydantic AI начинались как проекты на Python.
  • Инструмент — это просто функция. Как видно из примера, инструментом может стать любая функция на Python. Всё, что умеет Python, умеет и ваш агент.
  • Библиотеки для инструментов уже есть. Playwright для браузеров, pandas для данных, requests для API, WeasyPrint для PDF, Whisper для речи. Большинство нужных инструментов — это несколько строк связующего кода.
  • Проверять результат просто. Pydantic и jsonschema превращают требование «модель должна вернуть данные вот такой структуры» в одну строку кода, которая сразу падает с ошибкой, если что-то не так.
  • Тот же код становится продуктом. FastAPI превращает агента в веб-API, а Docker доставляет его на сервер. Второй язык не нужен.

Вот как выглядит проверка схемой на Pydantic. Если модель не указала источник, запуск останавливается, и утверждение дальше не уходит:

from pydantic import BaseModel, HttpUrl


class Claim(BaseModel):
    text: str
    source_url: HttpUrl  # no source, no claim


claim = Claim.model_validate_json(model_output)  # raises an error if anything is missing

Все три моих проекта с агентами устроены именно так: Claude решает, а Python делает работу и проверяет её.

Когда агент не нужен

Если шаги всегда одни и те же, напишите скрипт. Это дешевле, быстрее, и результат каждый раз один и тот же. Если нужны только ответы по вашим собственным материалам, хватит чат-бота. Агент нужен, когда следующий шаг действительно зависит от того, что нашёл предыдущий. И тогда вокруг него нужны проверки, чтобы ошибочный шаг не прошёл незамеченным.

Как это выглядит в реальных проектах

← Все статьи