ИИ-агент — не чат-бот с function calling. Это система, которая воспринимает, рассуждает, действует и учится — автономно, через несколько шагов, с состоянием, сохраняющимся между действиями. Руководство Anthropic по созданию эффективных агентов — лучшая отправная точка для понимания паттернов агентной архитектуры. Чат-бот отвечает на ваш вопрос. Агент бронирует ваш рейс, переносит ваши встречи и обновляет Slack вашей команды, пока вы в воздухе.
Все строят агентов в 2026 году. Многие ломаются в продакшне — зацикливаются навсегда, вызывают не те инструменты, забывают, что делали три шага назад. Это руководство охватывает архитектуру, предотвращающую эти сбои. От цикла вызова инструментов до систем памяти и мультиагентной оркестрации — каждый раздел содержит рабочий код. К концу у вас будет работающий агент-исследователь, который можно форкнуть и расширить.
Что делает ИИ-агента — и что не делает
Определение. У ИИ-агента три слоя: ядро рассуждения (LLM), слой инструментов (API, базы данных, выполнение кода) и слой памяти (краткосрочный разговор, долгосрочные знания, рабочее состояние). Ключевое отличие от простого вызова LLM: агент принимает автономные решения в цикле. Он не просто отвечает. Он планирует, действует, наблюдает результат и решает, что делать дальше.
Три слоя:
User Query → Reasoning Core (LLM) → Decision → Tool Execution → Observation → Memory Update → Next Decision → ... → Final ResponseКогда нужен агент, а когда простой вызов LLM. Агент: многошаговые задачи, где модели нужно собирать информацию, выполнять действия и адаптироваться по результатам. «Исследуй эту тему и напиши отчёт» — агент. «Суммаризируй эту статью» — простой вызов. «Отладь эту ошибку, проверь логи и открой PR с исправлением» — агент. «Объясни это сообщение об ошибке» — простой вызов.
Если задача выполняется одним вызовом API без внешних инструментов, агент не нужен. Если задача требует сбора информации из нескольких источников, выполнения действий и принятия решений на основе промежуточных результатов — нужен агент. Дерево решений: один шаг? — простой вызов. Несколько шагов с инструментами? — агент.
Цикл вызова инструментов: руки вашего агента
Ядро агентного цикла. Каждый фреймворк агентов — LangChain, CrewAI, AutoGen, сырой код — реализует какую-то версию этого.
import json
from openai import OpenAI
client = OpenAI(
base_url="https://api.tokspan.com/v1",
api_key="ts-your-key-here"
)
class Agent:
def __init__(self, model: str, tools: list, max_iterations: int = 10):
self.model = model
self.tools = {t["function"]["name"]: t for t in tools}
self.max_iterations = max_iterations
self.memory = [] # Working memory —the agent's scratchpad
def run(self, user_query: str) -> str:
messages = [
{"role": "system", "content": "You are a research assistant. Use tools to gather information, then synthesize a report."},
{"role": "user", "content": user_query}
]
for iteration in range(self.max_iterations):
response = client.chat.completions.create(
model=self.model,
messages=messages,
tools=list(self.tools.values()),
tool_choice="auto"
)
msg = response.choices[0].message
# Agent decided to respond with text —done
if msg.content and not msg.tool_calls:
return msg.content
# Agent decided to call tools —execute and continue
if msg.tool_calls:
messages.append(msg)
for tool_call in msg.tool_calls:
tool_name = tool_call.function.name
tool_args = json.loads(tool_call.function.arguments)
result = self._execute_tool(tool_name, tool_args)
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": str(result)
})
return "Agent reached maximum iterations without completing the task."
def _execute_tool(self, name: str, args: dict):
# In production: dispatch to actual functions
print(f"Calling tool: {name}({args})")
return f"Result from {name}"Лучшие практики определений инструментов. Описание инструмента — это промпт: пишите его ясно. Включайте примеры того, когда использовать каждый инструмент. Жёстко ограничивайте параметры — перечисления вместо строк свободного текста. Делайте инструменты идемпотентными — повторный вызов того же инструмента с теми же параметрами должен давать тот же результат. Когда выполнение инструмента терпит неудачу, отправьте сообщение об ошибке модели — она часто может восстановиться, попробовав другие параметры.
Полное межпровайдерское сравнение function calling — включая реализации OpenAI, Anthropic, Google и DeepSeek — смотрите в нашем межпровайдерском руководстве по function calling.
Обработка ошибок в цикле. Выполнение инструмента терпит неудачу — отправьте ошибку модели — модель решает: повторить с другими параметрами, попробовать другой инструмент или сообщить пользователю. Модель удивительно хороша в восстановлении после ошибок инструментов — но только если вы отправляете ошибку обратно. Молчаливое проглатывание сбоев инструментов даёт агентов, которые таинственно проваливаются.
Системы памяти: учим агента запоминать
Агент без памяти — золотая рыбка: он забывает всё между шагами. Три типа памяти, у каждого своя цель.
Краткосрочная память — история разговора. Массив messages. Что сказал пользователь, что сделал агент, что вернули инструменты. Управляется как скользящее окно — когда история приближается к лимиту контекста модели, обрезайте самые старые сообщения или суммаризируйте их. Триггер суммаризации: когда общее число токенов превышает 80% окна контекста, суммаризируйте самые старые 50% разговора в одно системное сообщение.
Долгосрочная память — векторное хранилище. Прошлые взаимодействия, предпочтения пользователя, изученные факты — хранятся как эмбеддинги в векторной БД, извлекаются по сходству с текущим запросом. Реализация: встраивайте каждое значимое взаимодействие — храните в ChromaDB или Pinecone — на каждый новый запрос извлекайте top-3–5 самых похожих прошлых взаимодействий — включайте в системный промпт как контекст. Это разница между «агент знает, о чём мы говорили на прошлой неделе» и «агент начинает каждый разговор с чистого листа».
Рабочая память — черновик. Текущий план агента, промежуточные результаты и гипотезы — хранятся как JSON-объект, обновляемый на каждой итерации цикла. Что агент пытается достичь прямо сейчас? Что он пробовал? Что он узнал? Черновик — это «поток мыслей» агента — экстернализованный, чтобы переживать вызовы инструментов и быть доступным для отладки.
Архитектура памяти. Все три памяти питают агента на каждой итерации цикла: история разговора (что произошло) + извлечённые долгосрочные воспоминания (что релевантно из прошлого) + рабочая память (что мы делаем сейчас). LLM синтезирует их в следующее решение.
Мультиагентные системы: когда одного агента недостаточно
Один агент с 15 инструментами принимает плохие решения — слишком много вариантов, слишком много контекста, сниженная точность выбора. Решение: специализированные агенты, у каждого сфокусированный набор инструментов и чёткая ответственность.
Паттерны оркестрации:
- Супервизор/работник. Один агент-оркестратор назначает задачи специализированным агентам-работникам. Супервизор не делает работу — он координирует. «Исследуй эту тему» — супервизор отправляет задачу агенту-исследователю, агенту-аналитику и агенту-писателю — супервизор собирает результаты.
- Дебаты «равный-равному». Два агента спорят за противоположные стороны решения, затем сходятся. «Одобрить ли этот кредит?» — агент A утверждает, агент B возражает — оба рецензируют аргументы друг друга — вырабатывают совместную рекомендацию.
- Последовательный конвейер. Выход агента A — вход агента B. «Проанализируй эту кодовую базу» — анализатор кода выводит отчёт — искатель багов использует отчёт для выявления проблем — генератор исправлений предлагает решения.
Мультиагентная коммуникация. Используйте общую шину сообщений — каждый агент публикует свой вывод как структурированное сообщение вида {from: "researcher", to: "analyst", content: "...", type: "report"}. Это делает граф взаимодействия агентов наблюдаемым и отлаживаемым. Когда что-то идёт не так, вы можете проследить, какой агент какой вывод произвёл и почему.
Стоимость мультиагентности. Каждый агент совершает собственные вызовы LLM. Система из трёх агентов делает в 3 раза больше вызовов API, чем система с одним агентом. Смягчение: используйте дешёвые модели для агентов-работников (DeepSeek V4 Flash, $0.14/$0.28) и резервируйте фронтирные модели (Claude Opus, GPT-5.5) для оркестратора. Оркестратор принимает решения с высокими ставками. Работники выполняют.
Вот конкретный конвейер исследования из трёх агентов, который можно развернуть сегодня. Агент-исследователь использует Gemini 3.1 Pro ($2.00/M входных токенов) ровно с двумя инструментами — веб-поиском и извлечением документов — чтобы никогда не потеряться в параличе выбора инструментов. Его вывод — структурированный JSON-бриф: {sources: [...], key_facts: [...], gaps: [...]}.
Агент-писатель запускает GPT-5.5 ($5.00/M вход) для превращения брифа в черновик, используя только инструмент форматирования. Агент-рецензент использует Claude Opus 4.8 ($5.00/M вход) для проверки каждого утверждения по исходным источникам, выявления галлюцинаций и возврата оценённой рецензии: {score: 1-10, issues: [...], corrected_draft: "..."}. Стоимость за задачу — $0.12–0.35 — исследователь потребляет ~40% токенов, писатель ~35%, рецензент ~25%.
Шина сообщений — простой dict Python, передаваемый между агентами, — фреймворк не требуется. Логируйте {timestamp, from_agent, to_agent, payload_type, token_count} на каждом переходе, и вы сможете проследить каждую передачу, когда что-то ломается.
Отладка сбоев агентов
Агенты проваливаются предсказуемо. Три самых частых режима отказа: бесконечные циклы (агент вызывает инструменты, но никогда не сходится), неправильный выбор инструмента (модель выбирает нерелевантный инструмент с неверными параметрами) и переполнение контекста (история разговора превышает окно контекста модели, молча отбрасывая ранние сообщения). У каждого есть диагностический паттерн.
Для бесконечных циклов логируйте действия агента на повторяемость — если один и тот же инструмент вызывается с одними параметрами три раза подряд, агент застрял. Вмешательство: введите системное сообщение «Вы вызывали {tool} с {args} несколько раз. Результат не изменился. Попробуйте другой подход или сообщите, что у вас есть на данный момент».
Для неправильного выбора инструмента логируйте имя инструмента, параметры и результат на каждой итерации — вы заметите паттерны. Агент, вызывающий search_web, когда должен вызывать query_database, раскрывает описание инструмента, требующее переписывания, а не проблему модели.
Для переполнения контекста отслеживайте total_tokens на каждой итерации через поле usage API. Когда токены превышают 80% лимита контекста — 1M для GPT-5.5, 200K для Claude Opus — суммаризируйте самые старые 50% сообщений перед следующей итерацией. Самая частая ошибка разработчика: никогда не проверять response.usage.total_tokens, пока агент не начнёт выдавать бессвязный вывод, не осознавая, что контекст был молча усечён пять итераций назад.
Структурированное логирование — самый эффективный инструмент отладки из имеющихся. Минимум, логируйте на итерацию: {iteration, model, tool_calls, tokens_used, latency_ms, error}. После 20 прогонов агента у вас будет достаточно данных, чтобы определить, какой режим отказа кусает вас чаще всего.
Вы также сразу заметите регрессы производительности — вызов инструмента, обычно занимающий 200 мс, вдруг занимающий 2 секунды, — сигнал до того, как он станет инцидентом.
Какая модель для какой роли агента?
| Роль агента | Лучшая модель | Почему |
|---|---|---|
| Оркестратор | GPT-5.5 | Самое надёжное использование инструментов, лучший параллельный вызов инструментов |
| Кодовый агент | Claude Opus 4.8 | Лучший SWE-bench, лучшие архитектурные рассуждения |
| Агент-исследователь | Gemini 3.1 Pro | Контекст 2M для анализа документов, мультимодальность |
| Экономичный исполнитель | DeepSeek V4 Pro | 92% HumanEval при $0.44/M вывода |
| Агент-писатель | GPT-5.5 | Лучшее качество прозы и широкий стилистический диапазон |
Преимущество агрегационной платформы: доступ ко всем пяти моделям через один API-ключ. Маршрутизируйте каждую роль агента на её оптимальную модель. Меняйте модели без изменения кода агента. Оркестратор, кодовый агент, исследователь и работники используют один и тот же SDK OpenAI — просто разные параметры model.
Более глубокое архитектурное обсуждение маршрутизации разных задач на разные модели — паттерна, используемого каждой продакшн-агентной системой, — смотрите в нашем руководстве по использованию нескольких ИИ-моделей в одном приложении.
FAQ
Нужен ли мне фреймворк вроде LangChain для создания агентов?
Нет. Ядро агентного цикла — ~50 строк Python; код в этой статье — полностью рабочий агент. Фреймворки добавляют удобства (готовые инструменты, трассировка, бэкенды памяти) и сложность (слои абстракции, деревья зависимостей, ломающие изменения между версиями). Начните с сырого. Добавляйте фреймворк, только когда у вас есть конкретная проблема, которую он решает. Разработчики, сразу прыгающие на LangChain, часто об этом жалеют — они тратят больше времени на отладку фреймворка, чем на создание агента.
Какая модель лучше для агентов?
GPT-5.5 для надёжности использования инструментов — он наиболее последователен в вызове правильного инструмента с правильными параметрами. Claude Opus для сложного многошагового рассуждения, где глубина важнее надёжности. Gemini для длинноконтекстных задач. DeepSeek V4 Pro для экономичных агентов. Большинство продакшн-агентных систем используют 2–3 модели: надёжный оркестратор (GPT-5.5), специалист по глубокому рассуждению (Claude Opus) для сложных шагов и экономичный работник (DeepSeek) для высокообъёмных простых задач.
Как предотвратить бесконечное зацикливание агента?
Три предохранителя. Установите max_iterations (10–20 разумно для большинства задач). Отслеживайте завершение задачи — если последние 3 действия агента не дали новой информации, он застрял; завершите и верните частичный результат. Бюджетный потолок на сессию агента — лимит в $0.50 ловит бесконечные циклы до того, как они станут проблемой на $50 (см. наше руководство по управлению ключами и бюджетом для настройки лимитов расходов и запросов как предохранителей). Всегда имейте таймаут + изящный резервный ответ.
Сколько стоит запуск ИИ-агентов?
Простой агент (3–5 вызовов инструментов): $0.05–0.20 за задачу на DeepSeek V4 Pro. Сложный мультиагент (10–20 вызовов): $0.50–2.00 за задачу на смешанных моделях. Используйте маршрутизацию по затратам: простые задачи — дешёвые модели, сложные — фронтирные. Стоимость за задачу следует измерять и оптимизировать, как любую другую инфраструктурную стоимость.
Как протестировать надёжность агента перед деплоем в продакшн?
Постройте оценочный стенд из 20–50 размеченных вручную тестовых случаев, покрывающих ожидаемый диапазон задач агента. Запускайте каждый случай 5 раз — поведение агента недетерминировано, один прогон ничего не доказывает. Измеряйте две метрики: коэффициент завершения задач (произвёл ли агент валидный вывод?) и точность выбора инструментов (вызвал ли правильные инструменты в правильном порядке?).
Коэффициент завершения ниже 85% означает, что ваши промпты или описания инструментов требуют доработки. Для мультиагентных систем добавьте третью метрику: корректность передачи — получил ли каждый агент ожидаемый входной формат от вышестоящего агента? Одна плохая передача каскадируется в сбои ниже по течению.
Когда использовать одного агента против мультиагентной системы?
Начните с одного агента. Добавляйте второго только при достижении одного из трёх порогов: список инструментов превышает 8–20 функций (точность выбора инструментов ухудшается выше этого числа по бенчмаркам function calling OpenAI), у задачи есть чётко отделимые подзадачи с разными требованиями к экспертизе (исследование против написания против рецензирования), или вам нужна независимая проверка безопасности (агент-рецензент, проверяющий вывод основного агента).
Преждевременная мультиагентная архитектура — самая частая ошибка избыточного инжиниринга в разработке агентов — она добавляет задержку, стоимость и сложность отладки без пропорциональной выгоды для простых рабочих процессов.
Шаг первый: скопируйте 50-строчный агентный цикл из этой статьи, подставьте свои определения инструментов, установите max_iterations на 10 и разверните его против некритичной внутренней задачи — чего-то малозначимого, где сбой — возможность учиться, а не инцидент. Смотрите логи. Смотрите, где он застревает. Добавьте память, когда он забывает контекст. Добавьте мультиагентность, когда список инструментов становится громоздким. Единственный способ узнать, что ломается, — что-то выпустить и наблюдать.
50-строчный агентный цикл выше — рабочая отправная точка. Когда вы готовы назначить каждую роль агента на её оптимальную модель — таблица сопоставления в начале статьи — агрегационный endpoint позволяет менять модель на агента, редактируя строковый параметр. Никаких SDK на провайдера, никаких отдельных биллинг-отношений. Сначала разверните цикл против малозначимой внутренней задачи, смотрите логи и итерируйте оттуда.