Акт 003: Агент/Действие

Этот документ описывает Протокол Действий, который объясняет, как Инструменты получают реальный, исполняемый код. Если Инструмент — это описание того, что можно сделать, то Действие — это инструкция, как это сделать.

Архитектура двух реестров

Система агента использует два отдельных списка (реестра), чтобы отделить описание способности от её реального воплощения:

• Реестр Инструментов: Хранит описание того, как выглядят и что принимают Инструменты (их «интерфейс»).
• Реестр Действий: Хранит сам код (Действия), который выполняет работу для Инструментов.

Такое разделение делает систему очень гибкой. Инструменты могут существовать просто как идея, позволяя нейросети самой придумать результат (скрытое исполнение). Также это позволяет легко менять код Действия (например, использовать один для тестирования, а другой — для настоящей работы), не меняя при этом описание самого Инструмента.

Регистрация Действия

Каждое Действие регистрируется под уникальным именем, которое связывает его с Инструментом.

// Регистрируем реализацию Действия.
// По соглашению, Действие можно связать
// с Инструментом с таким же именем.
// Типы данных автоматически берутся из Инструмента.
Activity.register('weatherCheck', async call => {
  const data = await weatherAPI.get(call.location);
  return { temperature: data.temp, conditions: data.desc };
});

Tool.register('weatherCheck', {
  type: 'object',
  description: 'Получает текущую погоду для указанного места.',
  properties: {
    _tool: { type: 'string', const: 'weatherCheck' },
    location: { type: 'string' },
    _output: {
      type: 'object',
      properties: {
        temperature: { type: 'number' },
        conditions: { type: 'string' },
      },
      required: ['temperature', 'conditions'],
    },
  },
  required: ['location'],
});

Режимы исполнения: Скрытый и Явный

Система поддерживает два разных способа выполнения Вызова Инструмента:

• • 104: Концепция/Скрытое
  Скрытое исполнение: Нейросеть использует свои способности к рассуждению. Агент «продумывает» задачу и сам генерирует результат за один шаг. Этот режим используется по умолчанию, если для Инструмента не найдено Действие.
• Явное исполнение: Вызов передаётся на выполнение конкретному коду. Вызывается функция Действия, которая и вычисляет результат. Это необходимо для взаимодействия с внешним миром (например, с сайтами, базами данных) или для задач, где нужна точность и предсказуемость.

Как система решает, какой режим использовать

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

1. Поле _activity задано вручную: Если в определении Инструмента поле _activity уже заполнено, система использует это имя для поиска Действия в реестре.
2. Совпадение по имени (рекомендуемый способ): Если поля _activity нет, система проверяет, зарегистрировано ли Действие с таким же именем, как у Инструмента. Если да, то поле _activity заполняется автоматически.
3. Переход в скрытый режим: Если по первым двум правилам Действие не найдено, поле _activity остаётся пустым. Это сигнал, что Вызов нужно выполнить в скрытом режиме (силами нейросети).

Такой подход, основанный на соглашениях, упрощает разработку:

• Чтобы всё работало без настроек, называйте Действие так же, как и ваш Инструмент.
• Инструменты без соответствующего Действия автоматически и безопасно будут выполняться в скрытом режиме.
• Если вы вручную укажете _activity в схеме Инструмента, это будет иметь приоритет. Так одно Действие сможет обслуживать несколько разных Инструментов.

Зачем вообще разделять Действия?

Если бы описание Инструмента и код Действия были одним целым, то определение способности было бы навсегда привязано к коду. Чтобы переключиться с ответа нейросети на получение данных с сайта, пришлось бы найти и изменить каждого агента, использующего этот Инструмент.

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

• Изменения в коде не ломают агентов: Можно переключиться со скрытого режима на явный, не трогая код агента.
• Можно тестировать разные подходы: Сравнивать, что работает лучше для одной и той же задачи — рассуждения нейросети или обращение к внешнему сайту.
• Можно внедрять изменения постепенно: Запустить новый код Действия для части агентов, пока остальные продолжают использовать старый или скрытый режим.

От описания к действию

Разделяя «что» (Инструмент) и «как» (Действие), система становится невероятно гибкой. Но это лишь часть истории. Когда у нас есть описания и их реализации, остаётся последний элемент — организация процесса: как управлять этими Вызовами, исполнять их и выстраивать в нужной последовательности.

Следующий документ, 004: Агент/Вызов, расскажет о протоколе, который управляет этим исполнением, превращая абстрактные описания в конкретные действия с состоянием.