AI / LLM
Tool calls: чтение кода и схем
Суть Читай реальные сниппеты tool calling — JSON schema tool, диспетчер parallel-вызовов, цикл с timeout/обработкой ошибок и валидатор аргументов — и выбирай фикс с наибольшим рычагом.
Высота — путь к senior
НольJuniorMiddleSenior
Ты на senior-высоте — в орбитеБаги tool calling живут в схеме, диспетчере и цикле — не в модели. Читай каждый сниппет так, как читал бы на ревью, и выбирай фикс, который senior сделал бы первым.
Цель
Отработай петлю диагностики, которую ты запускаешь на каждом агенте: читай tool schema и код цикла, предскажи, как поведут себя модель и твой handler, и тянись к фиксу, который закрывает границу доверия или останавливает runaway.
Сниппет 1 — JSON schema tool
{
"name": "cancel_order",
"description": "Cancel an order.",
"input_schema": {
"type": "object",
"properties": {
"order_id": { "type": "string" },
"reason": { "type": "string" }
}
}
} Викторина
Completed
Мутирующий tool cancel_order выходит с этой схемой. В чём главная слабость и фикс с наибольшим рычагом?
Heads-up Добавление tools не чинит этот. Дефект в том, что схема разрешает свободный, необязательный, неописанный order_id, так что у модели нет ограничения, а у тебя нет ничего строгого для валидации.
Heads-up Один лишь тип не останавливает галлюцинацию — модель так же легко выдумает правдоподобный integer, как и строку. Фикс — required-поля, enum где применимо, реальный description плюс рантайм-проверки существования/авторизации.
Heads-up input_schema — это то, что направляет модель к корректным вызовам и даёт тебе контракт для валидации. Убрать её — значит убрать и подсказку, и цель валидации, что есть противоположность фикса.
Сниппет 2 — диспетчер parallel-вызовов
results = []
for block in response.tool_use_blocks: # их может быть несколько за ход
output = TOOLS[block.name](**block.input) # исполняем последовательно
results.append(tool_result(block.id, output))
send(messages + results) Викторина
Completed
Когда модель эмитит три независимых tool_use-блока за один ход, что этот диспетчер делает верно и что оставляет на столе?
Heads-up Все tool_result-блоки для tool_use-блоков одного хода уходят обратно в одном последующем запросе; это ровно то, что делает код. Улучшение — конкурентность исполнения, а не разбиение ответа.
Heads-up Каждый tool_result ссылается на свой block.id, так что сопоставление по id, а не по порядку. Модель намеренно эмитнула параллельные блоки; фикс — исполнять их конкурентно, а не отключать параллелизм.
Heads-up Разворачивать вход от модели прямо в функцию — это недостающая граница доверия: аргументы могут быть галлюцинированными или кривыми. Валидируй по input_schema до вызова, независимо от вопроса параллелизма.
Сниппет 3 — цикл без защиты
while True:
resp = model.create(messages=messages, tools=TOOLS)
if resp.stop_reason != "tool_use":
break
for b in resp.tool_use_blocks:
out = run_tool(b.name, b.input) # может бросить / зависнуть
messages.append(tool_result(b.id, out))
messages.append(resp.message) Викторина
Completed
Этот цикл работает в проде против client tools. Какие два дефекта укусят первыми при сбое и как их чинить?
Heads-up Порядок сообщений — реальная забота, но не то, что кусает первым при сбое. Опасные дыры — отсутствующий cap итераций (runaway-стоимость) и отсутствующий per-tool timeout (зависший tool стопорит ход).
Heads-up break при stop_reason, отличном от tool_use, уже выходит на end_turn, max_tokens и т.д. Уязвимость — безграничный while True на пути tool_use и отсутствие timeout у tool.
Heads-up Этот цикл и так гоняет tools последовательно, так что параллельная безопасность тут ни при чём. Дыры режима сбоя — защита от runaway и per-tool timeout.
Сниппет 4 — валидатор
def handle(block):
args = block.input
try:
validated = ToolArgs.model_validate(args) # pydantic: форма + типы
except ValidationError as e:
return tool_result(block.id, f"invalid arguments: {e}", is_error=True)
return tool_result(block.id, run(validated)) Викторина
Completed
Этот handler валидирует по схеме через Pydantic и возвращает ошибки как tool_result. Для мутирующего tool против multi-tenant БД чего всё ещё не хватает?
Heads-up Валидация по схеме лишь доказывает, что аргументы правильной формы, а не то, что сущность реальна или принадлежит вызывающему. Провалидированный, но выдуманный id всё равно мутирует не ту запись без проверки авторизации/существования.
Heads-up Возврат ошибки как tool_result верен — он даёт модели прочитать ошибку и само-исправиться на следующем ходе. Бросок из цикла завершает ход и убирает этот путь восстановления.
Heads-up Слепые ретраи мутирующего вызова рискуют повторить деструктивное действие и сжечь токены. Недостающий слой — проверка авторизации/существования до исполнения, а не retry-on-failure.
Итог
Каждый баг tool calling читается в схеме, диспетчере, цикле или валидаторе. Слабая схема (нет required, нет enum, пустой description) даёт модели угадывать и не даёт тебе что валидировать. Последовательный диспетчер корректен, но теряет выигрыш по латентности от parallel-вызовов для независимых tools. while True без per-tool timeout — это runaway и зависание, ждущие случиться: ограничь итерации и тайм-боксь каждый tool. А валидация формы через Pydantic необходима, но недостаточна для мутирующего вызова: добавь проверку авторизации и существования и возвращай каждый отказ как tool_result, чтобы модель само-исправлялась.