002: Агент/Инструмент

Инструмент — это интерфейс на основе схемы, который определяет структурированную способность, доступную агенту. Это как кубик, из которого строятся все действия агента, позволяя ИИ понимать и выбирать из списка возможных поведений.

Что такое Инструменты?

Инструменты — это основа систем действий агента. Они открывают новую возможность: выбор действия в зависимости от контекста, позволяя агентам выбирать и выполнять подходящие действия в зависимости от ситуации.

Инструменты предоставляют:

• Структурированные интерфейсы: Понятные инструкции, которые агенты могут найти и понять.
• Надёжность типов: Чёткие правила о том, какие данные нужны на входе и что будет на выходе.
• Компонуемость: Кубики, которые можно комбинировать для создания сложных поведений агента.
• Интеграция с ИИ: Схемы, которые языковые модели могут анализировать и выбирать.

Когда агент заполняет конкретные параметры для Инструмента, он создаёт Вызов — это как бы «заказ» на использование инструмента со всеми нужными данными, готовый к исполнению.

Когда использовать систему Инструментов

Используйте систему Инструментов, когда агентам нужно:

• Выбирать действия динамически в зависимости от контекста и ситуации.
• Выбирать между несколькими способностями для достижения цели.
• Выполнять разные реализации одной и той же способности (например, разные поисковые системы).
• Совмещать рассуждения ИИ с чёткой логикой в процессе принятия решений.

Схема как интерфейс

Система Инструментов построена на фундаментальном принципе: Инструменты — это просто схемы, которые описывают интерфейсы, не указывая, как именно их реализовывать. Это разделение «что делать» и «как делать» — ключ к гибкости и компонуемости системы.

Схема Инструмента — это стандартный объект JSON Schema. Любое поле без знака подчёркивания в начале считается параметром инструмента. Система использует специальные мета-поля (начинающиеся с _) для определения системных свойств, которые управляют идентификацией и выполнением инструмента.

Схема Инструмента полностью описывает его интерфейс:

• title: Понятное для человека название схемы (необязательно).
• description: Объясняет, что делает инструмент.
• properties: Любые поля без подчёркивания определяют входные данные, необходимые инструменту.
• _tool: Уникальное имя для идентификации инструмента.
• _output: Определяет ожидаемую структуру результата работы инструмента.
• _reasoningForCall: Поле, добавляемое системой, чтобы агент объяснил, почему он выбрал этот инструмент.

Протоколы более высокого уровня строят на основе этих примитивов организацию рабочих процессов, управление состоянием и правила выполнения.

Определение Инструмента

Инструменты определяются как JSON-схемы. В примере ниже показан Инструмент для анализа тональности текста. Этот Инструмент предназначен для скрытого выполнения, так как он полагается на встроенное понимание языка ИИ и не требует внешней функции.

Tool.register('sentimentAnalysis', {
  type: 'object',
  description: 'Анализирует тональность текста',
  properties: {
    _tool: { type: 'string', const: 'sentimentAnalysis' },
    text: { type: 'string', description: 'Текст для анализа' },
    _output: {
      type: 'object',
      properties: {
        sentiment: { type: 'string' },
        confidence: { type: 'number' },
      },
    },
  },
});

// Запрос: "Какая тональность у 'Это просто супер!'"
{
  "_tool": "sentimentAnalysis",
  "text": "Это просто супер!",
  "_output": {
    "sentiment": "positive",
    "confidence": 0.99
  }
}

Составление схем для ИИ

Агент не просто работает с инструментами; ему часто нужно выдать итоговый, структурированный результат после завершения задачи. Для этого среда выполнения агента объединяет схемы всех доступных Инструментов с определённой пользователем схемой выходных данных. Это создаёт единую, общую схему, которая предоставляется ИИ в Запросе.

Такое объединение даёт ИИ выбор, как ответить. В зависимости от задачи, он может:

• Сгенерировать только calls (вызовы): Если задача требует промежуточных шагов, ИИ вызовет один или несколько инструментов, оставив поле output пустым.
• Сгенерировать только output (вывод): Если на запрос можно ответить сразу без инструментов, ИИ предоставит конечный результат в поле output, оставив calls пустым.
• Сгенерировать и то, и другое: В некоторых случаях ИИ может выполнить действие и сразу же выдать конечный результат за один шаг.

Этот механизм позволяет одному гибкому интерфейсу обрабатывать как простые, одномоментные ответы, так и сложные задачи с несколькими инструментами. Разработчик предоставляет схемы Инструментов и схему вывода по отдельности, а система объединяет их в структуру, которую ИИ может использовать для выбора наилучшего пути.

Пример ниже показывает, как составляется схема Инструмента и схема вывода.

Agent.Request(
  config, // Конфигурация запроса (например, модель, температура)
  {
    // Схема вывода
    type: 'object',
    properties: {
      summary: { type: 'string' },
    },
    required: ['summary'],
  },
  [
    // Контекст
    {
      type: 'tool',
      tool: {
        greetUser: {
          type: 'object',
          properties: {
            userName: { type: 'string' },
          },
          required: ['userName'],
        },
      },
    },
    { type: 'text', text: 'здесь какой-то запрос' },
  ]
);

{
  "type": "object",
  "properties": {
    "output": {
      "type": ["object", "null"],
      "properties": {
        "summary": { "type": "string" }
      },
      "required": ["summary"],
      "additionalProperties": false
    },
    "calls": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "_tool": { "const": "greetUser" },
          "userName": { "type": "string" }
        },
        "required": ["_tool", "userName"]
      }
    }
  },
  "required": ["calls", "output"]
}

Расширение Инструментов с помощью мета-свойств

Кроме определения базовых параметров инструмента, его схему можно расширить в момент вызова. Это другая форма компоновки, когда к одному инструменту добавляются новые слои поведения.

Когда агент решает использовать инструмент, он создаёт Вызов — конкретный экземпляр этого инструмента. Вызов включает параметры инструмента, но его также можно дополнить специальными мета-свойствами (начинающимися с _), которые дают дополнительные инструкции для движка выполнения. Эти свойства управляют аспектами выполнения инструмента, которые выходят за рамки его базового определения.

Этот механизм позволяет использовать простую, базовую схему инструмента мощными и гибкими способами. Вызов становится богатой инструкцией, которая указывает, что делать (инструмент и его параметры) и как это делать (мета-свойства). Последняя часть головоломки — это понимание различных способов выполнения Вызова.

Скрытое и явное выполнение

Как только Вызов сгенерирован, система должна его выполнить. Схема Инструмента, будучи просто интерфейсом, сама по себе не содержит логики выполнения. Вместо этого его выполнение может происходить одним из двух способов. По умолчанию используется скрытое выполнение, когда ИИ использует свои внутренние рассуждения для генерации вывода, что идеально подходит для языковых или основанных на знаниях задач. Для действий, требующих взаимодействия с внешним миром — например, вызова API или доступа к базе данных — Инструмент должен быть связан с детерминированной функцией кода. Эта явная реализация называется Действием.

Разделение интерфейса Инструмента от реализации Действия является ключевым принципом дизайна. Это позволяет определять и рассуждать о способностях агента абстрактно, в то время как логику выполнения можно менять или обновлять независимо. Следующий документ, 003: Агент/Действие, описывает, как Действия предоставляют конкретную логику для Инструментов.