В простейшем агентном цикле модель предлагает следующий шаг, приложение выполняет разрешённый инструмент и возвращает результат для продолжения. Это ещё не означает автономного сотрудника с неограниченными правами. Полезный учебный старт - один инструмент, строгие аргументы и понятное условие остановки.
Учебный агентный цикл ограничивает инструменты и проверяет итог по фактическому вычислению.
Наш пример считает сумму целых денежных величин. Он не обращается к платной модели и не меняет внешние данные. Функция, изображающая решение модели, специально детерминирована: так можно проверить устройство исполнителя без ключа API, расходов и случайных ответов. Подключение реального провайдера будет отдельным транспортным слоем.
Разделите решение и исполнение
Модель не должна напрямую выбирать произвольную функцию Python. Она возвращает структурированное предложение: имя инструмента и объект аргументов либо финальный ответ. Приложение проверяет тип сообщения, допустимое имя, ограничения входа и полномочия текущей задачи.
Нельзя подставлять текст модели в eval, командную строку или SQL как готовую программу. Даже если предыдущие ответы выглядели разумно, новый ответ остаётся входными данными для исполнителя. Результат инструмента тоже нужно передавать с ясной структурой, чтобы он не потерялся среди свободного текста.
В учебной схеме разрешён только sum_cents. Величины неотрицательные, целые, список ограничен ста элементами. Это выбранный контракт примера, а не универсальное ограничение денег или возможностей Python.
Проверьте инструмент отдельно
def sum_cents(prices):
if not isinstance(prices, list) or len(prices) > 100:
raise ValueError("invalid prices")
if any(isinstance(x, bool) or not isinstance(x, int)
or x < 0 or x > 1_000_000 for x in prices):
raise ValueError("invalid price")
return sum(prices)
assert sum_cents([120, 80]) == 200
Проверка логического типа нужна отдельно: в Python значения True и False связаны с целым типом. Если контракт допускает только денежные величины, их нельзя молча считать единицей и нулём. Ограничение длины и максимального значения не заменяет бизнес-права, но делает объём вычисления обозримым.
Для пустого списка функция возвращает ноль. Это намеренное правило. Если по задаче пустая корзина недопустима, проверку нужно изменить и добавить соответствующий тест. Даже простая функция содержит решения, которые нельзя оставлять на догадку модели.
Соберите ограниченный цикл
Следующий фрагмент использует sum_cents из предыдущего блока. Учебная функция decide сначала запрашивает сумму, потом возвращает её как ответ. Она не является языковой моделью; её роль - воспроизводимый испытатель протокола.
def decide(state):
if "tool_result" not in state:
return {"tool": "sum_cents", "args": {"prices": [120, 80]}}
return {"final_cents": state["tool_result"]}
def run(decider, max_steps=3):
state = {}
for _ in range(max_steps):
message = decider(dict(state))
if not isinstance(message, dict):
raise ValueError("object expected")
if "final_cents" in message:
if type(message["final_cents"]) is not int:
raise ValueError("integer final answer required")
if message != {"final_cents": state.get("tool_result")}:
raise ValueError("unverified final answer")
if "tool_result" not in state:
raise ValueError("no evidence")
return message["final_cents"]
if set(message) != {"tool", "args"}:
raise ValueError("invalid tool message")
if message["tool"] != "sum_cents":
raise PermissionError("unknown tool")
args = message["args"]
if not isinstance(args, dict) or set(args) != {"prices"}:
raise ValueError("invalid args")
state["tool_result"] = sum_cents(args["prices"])
raise RuntimeError("step limit reached")
assert run(decide) == 200
В ответе проверяется соответствие фактическому результату инструмента. Пример ограничен одной задачей, поэтому такая проверка проста. В более сложном агенте потребуется определить, какие свидетельства подтверждают выполнение: удалённый ID, прочитанная запись, успешная проверка файла или другой наблюдаемый результат.
Что произойдёт при ошибочном предложении
Если функция решения назовёт delete_all, исполнитель отклонит неизвестный инструмент. Если передаст строку вместо списка, сработает валидация. Если будет бесконечно просить вычисление и не завершать, сработает предел шагов. Если назовёт произвольную финальную сумму без результата инструмента, ответ не пройдёт проверку.
Предел шагов не равен таймауту. Один инструмент может работать очень долго, поэтому ему нужен собственный предел времени и ресурсов. Синхронный пример не реализует принудительную остановку зависшего процесса; для реального тяжёлого действия выберите подходящую изоляцию и механизм отмены.
Не ловите любую ошибку с бесконечным «попробуй ещё». Часть ошибок требует исправить вход, часть связана с отсутствием прав, часть оставляет неизвестный исход внешнего действия. У этих состояний разные правила продолжения.
Что добавить при подключении настоящей модели
Определите её текущий формат структурированных сообщений по официальной документации. Разберите JSON или используйте поддерживаемую схему, затем всё равно проверьте значения. Храните ключ на сервере и не помещайте его в контекст модели или браузерный код.
Добавьте учёт входных и выходных токенов, расходов, числа инструментальных вызовов и общего времени. Перед внешней записью проверяйте, входит ли действие в поручение пользователя. Чужой документ, прочитанный агентом, не должен расширять список доступных операций.
Для инструментов с последствиями нужен устойчивый ID операции. Если ответ потерян после создания записи, повтор может создать дубль. Начинайте со сверки, а не с нового безусловного вызова. Наш инструмент чистый и локальный, поэтому эту часть он намеренно не демонстрирует.
Упражнения и ответы
- Подставьте
lambda state: {"tool": "delete_all", "args": {}}. Ожидается PermissionError, вызова удаления не существует. - Подставьте функцию, всегда возвращающую корректный запрос суммы. После трёх шагов ожидается RuntimeError: агент не завершил задачу.
- Верните финальный ответ до инструмента. Ожидается ValueError: отсутствует проверяемое свидетельство вычисления.
Частые вопросы
Это уже полноценный ИИ-агент? Это учебный исполнитель агентного протокола с имитацией решения. Реальная модель, транспорт и права подключаются отдельно.
Можно ли добавить много инструментов сразу? Лучше добавлять по одному с контрактом и тестами, иначе трудно понять, где возникла ошибка.
Схема JSON гарантирует правильный ответ? Она ограничивает форму, но не подтверждает смысл и полномочия действия. Нужны независимые проверки.
Откройте Кодик, чтобы посмотреть доступные учебные направления и выбрать подходящий маршрут. Сначала добейтесь предсказуемого поведения маленького исполнителя, затем подключайте модель и расширяйте задачу.