SDK

runTask и client tools

runTask создаёт задачу и сам доводит её до терминального статуса, обрабатывая interrupt-цикл клиентских инструментов: вызвал обработчик, отправил результат, продолжил.

Схема и обработчик в одном месте

Каждый элемент tools задаёт и определение инструмента, и его handler. SDK сам соберёт client_tools запроса.

ts
const task = await client.runTask(
  {
    assistant_id: 1,
    input: [textInput('Какая погода в Москве?')],
  },
  {
    tools: [
      {
        name: 'get_weather',
        description: 'Текущая погода в городе.',
        input_schema: {
          type: 'object',
          properties: { city: { type: 'string' } },
          required: ['city'],
        },
        // вернуть строку, { content } или { error, reason }
        handler: async (args) =>
          JSON.stringify({ city: args.city, temperature_c: 21 }),
      },
    ],
    onStatus: (t) => console.log(t.status),
  },
);

Карта обработчиков

Альтернативно tools принимает карту { имя: обработчик } — тогда определения инструментов берутся из input.client_tools (форма для случаев, когда схемы приходят из другого источника).

ts
await client.runTask(
  { assistant_id: 1, input: [], client_tools: [/* определения */] },
  { tools: { get_weather: async (args) => '…' } },
);

Результат обработчика

Возвращаемое значениеСмысл
stringУспех, тело результата.
{ content: string }Успех, явная форма.
{ error: string, reason?: string }Ошибка инструмента.

Опции runTask

ОпцияНазначение
toolsClientTool[] или карта { имя: обработчик }.
pollIntervalMsИнтервал опроса статуса. Дефолт 1500.
timeoutMsОбщий таймаут на весь прогон.
maxRoundsЗащита от бесконечного interrupt-цикла. Дефолт 10.
onStatusКолбэк на каждом опросе.
onMissingToolФолбэк, если для вызванного инструмента нет обработчика.
signalAbortSignal для отмены прогона.
Нет обработчика?
Если для вызванного инструмента нет обработчика в tools, бросается MissingToolHandlerError — либо вызывается onMissingTool, если он задан.
Под капотом это тот же цикл, что описан в разделе Клиентские инструменты — только SDK проходит его за вас.