Что такое ИИ-агент
Чат-бот отвечает. Агент действует. Вы даёте ему не вопрос, а цель, и он сам решает, какие шаги сделать.
Любой агент состоит из одних и тех же четырёх частей:
- Модель, которая принимает решения: 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 добавляют сверху память, несколько агентов и повторные попытки, но внутри каждого из них тот же самый цикл.
Как сделать агента, который работает
Демо выше работает с первой попытки. Настоящий агент должен работать и с сотой. Вот правила, которых я держусь:
- Начинайте с задачи, а не с модели. Прежде чем писать код, запишите цель, входные данные и критерий готовности. Если вы не можете этого сделать, агент тоже не угадает.
- Давайте ему только нужные инструменты. Белый список функций, а не полный доступ к командной строке. Агент в моём видеогенераторе может запускать скрипты самого проекта, ffmpeg и несколько команд только для чтения. Больше ничего.
- Пусть код делает то, что у него получается лучше. Загрузка, подсчёт, объединение данных и рендер уходят в инструменты на Python. Модель решает, инструменты исполняют.
- Проверяйте результат схемой. Пусть агент возвращает JSON, а вы проверяете его до того, как запустится что-то медленное или дорогое. В моём видеогенераторе раскадровка, которая не прошла проверку по JSON-схеме, до рендера не доходит.
- Добавьте проверку, которая может сказать «нет». В моём исследовательском процессе валидатор блокирует отчёт, если у какого-то утверждения нет источника или какая-то ссылка не работает. Правила агенту сообщают, а соблюдать их заставляет код.
- Заранее задайте точки, где решает человек. Тот же процесс останавливается в четырёх контрольных точках, например чтобы человек утвердил список конкурентов до запуска девяти исследовательских агентов.
- Ограничьте число повторов. Агент-ревьюер в видеогенераторе возвращает SHIP или список правок, и у него максимум два круга.
- Логируйте каждый шаг. Сохраняйте каждый вызов инструмента и его результат. Когда агент ошибается, по логу видно, на каком шаге, и чинить нужно именно там.
Почему 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 делает работу и проверяет её.
Когда агент не нужен
Если шаги всегда одни и те же, напишите скрипт. Это дешевле, быстрее, и результат каждый раз один и тот же. Если нужны только ответы по вашим собственным материалам, хватит чат-бота. Агент нужен, когда следующий шаг действительно зависит от того, что нашёл предыдущий. И тогда вокруг него нужны проверки, чтобы ошибочный шаг не прошёл незамеченным.
Как это выглядит в реальных проектах
- ИИ-генератор видео и изображений: агенты-стратег, сценарист и ревьюер, инструменты на Python, проверка схемой и этап QA.
- Исследовательский процесс с валидатором: девять исследовательских агентов работают параллельно, а проверка блокирует утверждения без источников.
- Аудит сайта для Google и ИИ-поиска: краулер на Python и проверки по правилам, а анализ делают пять агентов Claude Code.
- WAT-фреймворк: как я делю работу между агентом и инструментами.