Как собрать многошаговый agent loop с tools в Ollama

Сведения проверены 13 сентября 2026 года по официальной документации Ollama. Официальный пример agent loop повторяет chat, добавляет assistant message и результаты tools, пока модель не вернёт ход без tool_calls. Дополнительно структура базовых ответов сверена с Generate API, Chat API и Embed API.

Цены и тарифы не приводятся. Доступность конкретной модели, качество ответа и аппаратная производительность зависят от локальной установки, поэтому они не выдаются за универсальный факт. Метрики берутся только из фактического JSON-ответа вашего запуска.

Подготовка безопасного тестового стенда

1. Убедитесь, что Ollama запущена локально и endpoint доступен приложению.
2. Получите список установленных моделей через официальный endpoint tags и выберите модель, подходящую capability.
3. Не зашивайте имя модели в десятки файлов: храните его в переменной окружения или одном конфигурационном модуле.
4. Используйте искусственные значения DEMO, тестовые SKU и вымышленные тексты.
5. Задайте timeout и проверяйте HTTP status до разбора JSON.
6. Сохраняйте исходный request без секретов, версию приложения и имя модели для воспроизводимости.
7. Разделяйте сетевую ошибку, ошибку JSON, нарушение схемы и неверный бизнес-результат.

Ollama генерирует вероятностный результат. Даже при стабильном запросе текст может отличаться, поэтому тестируйте инварианты: наличие поля, роль сообщения, допустимое имя tool, формат аргумента, число векторов или ожидаемое вычисление. Не сравнивайте длинный ответ целиком со snapshot без необходимости.

Пошаговая реализация

1. Сформируйте payload только из документированных полей.
2. Укажите model и обязательный prompt, messages либо input.
3. Для примеров, которым нужен один JSON, явно задайте stream:false.
4. Отправьте POST с Content-Type: application/json.
5. При status вне диапазона 200–299 прочитайте текст ошибки и остановите обработку.
6. Разберите JSON и проверьте типы нужных полей до использования.
7. Проверьте связь ответа с входом: роли, индексы, tool_name или сохранённые фрагменты.
8. Не исполняйте tool по имени напрямую через eval или динамический import; используйте allowlist dispatcher.
9. Ограничьте число шагов agent loop и общий timeout.
10. Запишите технические счётчики отдельно от пользовательского результата.
11. Выполните негативный тест и убедитесь, что он действительно отклоняется.
12. Только после этого переносите код в основной сервис.

Готовый пример

const fns={add:({a,b})=>a+b,multiply:({a,b})=>a*b};
const messages=[{role:"user",content:"Вычисли (12+8)*3, используя tools"}];
const tools=Object.keys(fns).map(name=>({type:"function",function:{name,description:name,parameters:{type:"object",required:["a","b"],properties:{a:{type:"integer"},b:{type:"integer"}}}}}));
for(let turn=0;turn<5;turn++){const r=await fetch("http://localhost:11434/api/chat",{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({model:"qwen3",messages,tools,stream:false})});const d=await r.json();messages.push(d.message);const calls=d.message.tool_calls||[];if(!calls.length){if(!d.message.content.includes("60"))throw Error("неверный итог");console.log(d.message.content);break;}for(const c of calls){const fn=fns[c.function.name];if(!fn)throw Error("unknown tool");messages.push({role:"tool",tool_name:c.function.name,content:String(fn(c.function.arguments))});}if(turn===4)throw Error("max turns");}

Код рассчитан на Node.js с глобальным fetch. Его можно адаптировать к Python, сохранив ту же JSON-схему и последовательность проверок. Перед production добавьте AbortController, структурированный журнал без содержимого пользовательского prompt и retry только для безопасных транспортных сбоев.

Не повторяйте автоматически запрос, который уже мог вызвать внешний tool с побочным эффектом. Для инструментов записи используйте idempotency key на стороне приложения и сохраняйте состояние выполненного вызова. Модель предлагает аргументы, но доверять им без валидации нельзя.

Пример входа и ожидаемого результата

Вход: Выражение (12+8)*3, функции add и multiply, предел пять model turns.

Ожидаемый результат: Цикл сначала получает промежуточное 20, затем умножает на 3 и завершает content с числом 60 до достижения лимита.

Фактическая формулировка модели может отличаться. Критерием служат явно перечисленные свойства. Если критерий зависит от знания модели, используйте небольшой набор тест-кейсов и ручную выборочную проверку, но не выдумывайте процент точности без измерения.

Негативный тест

Смоделируйте модель, которая бесконечно вызывает add. На пятом ходе код обязан завершиться max turns, а не продолжать цикл.

Негативный тест запускайте автоматически рядом с позитивным. Он должен завершаться конкретной ошибкой и не оставлять частично записанное состояние. Для tools проверьте неизвестное имя, лишние аргументы, пропущенное обязательное поле и неверный тип. Для embeddings проверяйте количество, размерность и конечность каждого числа.

Production-обёртка

Создайте одну функцию client.request, которая добавляет endpoint, timeout, заголовок и обработку статусов. Поверх неё сделайте отдельные функции generate, chat и embed с собственными схемами валидации. Так изменение одного endpoint не разнесётся по всему приложению.