801: Пакет/Агент

Библиотека @augceo/agent — это главная программа, которая воплощает в жизнь архитектуру агентов, описанную в Актах. В отличие от других систем, которые больше заботятся о том, как правильно составить запрос для ИИ, эта библиотека ставит на первое место строгое соблюдение правил (протоколов).

Она работает как очень точный механизм, где каждое действие чётко определено, следует заранее заданной схеме и отделено от других.

Акты (Правила)

Эта библиотека построена точно по чертежам, которые описаны в Актах. Каждая её возможность соответствует отдельному документу с правилами.

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

Основные элементы

• 001: Агент/Запрос: Самая маленькая частичка работы.
  • Превращает исходные данные (Контекст) и правила (Схему) в структурированный ответ (Решение).
  • Поддерживает мультиплексирование (умеет создавать несколько решений сразу).
  • Это основа, на которой строятся все более сложные действия агента.
• 002: Агент/Инструмент: Схема, описывающая какую-либо способность.
  • Определяет внешний вид действия отдельно от того, как оно работает внутри.
  • Позволяет ИИ выбирать нужные действия, читая их структурированные описания.
• 003: Агент/Действие: Это конкретный программный код, который выполняет то, что обещано в Инструменте.
  • Связывает абстрактные схемы Инструментов с настоящим кодом.
  • Поддерживает двойную регистрацию (отделяет описание от реализации).
• 004: Агент/Вызов: Команда на использование Инструмента с конкретными параметрами.
  • Это как заполненная заявка на выполнение действия.
  • Служит единым «языком» для передачи команд от ИИ к системе.

Данные и Состояние

• 005: Агент/Данные: Правила для структурированной информации в контексте.
  • Предоставляет единый «конверт» для всех сообщений, которые хранятся в памяти.
  • Позволяет правильно объединять информацию из разных источников.
• 006: Агент/Ввод: Превращает обычный Запрос в многоразовую функцию.
  • Определяет строгие входные параметры для Запроса.
  • Позволяет автоматически создавать интерфейсы и безопасно вызывать функции.
• 009: Агент/Состояние: Память, которая сохраняется между разными шагами работы.
  • Работает как общий черновик для всего процесса.
  • Позволяет продолжать работу с того же места и создавать процессы, которые помнят, что было раньше.
• 016: Агент/Мета: Отвечает за «личность» и происхождение агента.
  • Отслеживает версии, ветки и откуда что взялось.
  • Позволяет агентам самостоятельно развиваться и обновлять свои версии.

Связи и Потоки

• 007: Агент/Переменные: Динамические ссылки.
  • Использует специальный синтаксис †kind.path, чтобы связывать выходы одних операций со входами других.
  • Позволяет Инструментам читать данные из контекста, не копируя их.
• 008: Агент/Вывод: Механизм для записи результатов.
  • С помощью _outputPath указывает, куда сохранить результат работы Инструмента.
  • Позволяет выстраивать в цепочку разные операции, передавая результаты через общее состояние.
• 011: Агент/Выражения: Логика внутри потока данных.
  • Поддерживает ветвление (||) для выбора одного из путей или запасного варианта.
  • Поддерживает разветвление (&&) для параллельной отправки данных.

Оркестрация

• 010: Агент/Цикл: Движок выполнения.
  • Повторяет Запросы снова и снова, пока не достигнет цели.
  • Управляет циклом: даёт команду, выполняет её, обновляет информацию.
• 012: Агент/План: Стратегия, описанная в виде данных.
  • Представляет весь процесс работы в виде графа потоков данных из вызовов Инструментов.
  • Разделяет планирование (размышление) и исполнение (действие).
• 013: Агент/Экземпляры: Масштабирование через параллельное выполнение.
  • Группирует сообщения по ID _instance, чтобы запускать параллельные процессы.
  • Позволяет применить один План к неограниченному количеству данных.
• 014: Агент/Делегат: Модульная сборка.
  • Изолирует выполнение в «песочницах» — безопасных подзапросах.
  • Позволяет вкладывать агентов друг в друга (Агенты как Инструменты).
• 015: Агент/Области: Контроль контекста.
  • Использует _scopes, чтобы строго определить, какие данные может видеть Делегат или Действие.
  • Предотвращает утечку информации и повышает безопасность.
• 017: Агент/Советник: Структурированное обдумывание.
  • Добавляет специальные «личности» для размышления перед тем, как действовать.
  • Обеспечивает взвешенное голосование и даёт стратегические советы основному агенту.

Концепции

Если Акты выше описывают, как всё работает, то следующие концепции объясняют почему всё устроено именно так:

• 104: Концепция/Скрытое: Режим «Без Кода» по умолчанию.

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

• Единство Планирования и Исполнения:

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

• Человек в процессе (HITL):

  • Agent предоставляет специальную функцию confirm().
  • Это позволяет человеку или другой системе перехватывать, проверять и одобрять каждый вызов инструмента перед его выполнением.
  • Если человек отклоняет или изменяет вызов, эта информация возвращается агенту, чтобы он скорректировал свой план.

• Восстановление после ошибок:

  • Ошибки — это не конец света. Если Инструмент ломается, ошибка записывается как Сообщение об ошибке в контекст.
  • На следующем шаге Агент «видит» эту ошибку и использует свой интеллект, чтобы исправить ситуацию (например, попробовав ещё раз с другими параметрами или выбрав другой путь).

Агент и Запрос

Библиотека различает низкоуровневый Запрос и высокоуровневого Агента.

Запрос (низкий уровень)

Запрос — это одна-единственная, неделимая операция с ИИ. Он предполагает, что на один вход (контекст и схема) будет один выход (решение).

• Управление: Он не работает в цикле. Он выполняет ровно один шаг.
• Мультиплексирование: Он может создавать несколько вариантов решения из одного и того же контекста (с помощью параметра n).
• Потоковая передача: Он позволяет перехватывать и обрабатывать части ответа (например, вызовы инструментов) по мере их поступления, в реальном времени, пока ИИ ещё генерирует остальную часть.

Агент (высокий уровень)

Агент — это цикл выполнения, который управляет последовательностью Запросов.

• Цикличность: Он постоянно вызывает Запросы, выполняет полученные вызовы Инструментов и добавляет результат обратно в контекст.
• Завершение: Он продолжает работать, пока система не решит записать финальный output.
• Сходимость: По правилам, желаемый результат оборачивается в свойство output. Цикл считает свою работу завершённой, только когда это свойство заполнено.

Единая структура вывода

Чтобы не было путаницы, и Агент, и Запрос приводят свой результат к одному виду. Ваша схема всегда помещается в свойство output.

• Запрос: Возвращает Data<T>[] (массив решений, обычно из одного элемента).
• Агент: Возвращает Data<T> (конечное, итоговое состояние).

Идея безопасности типов

Эта библиотека использует Схимию, чтобы обеспечить полную безопасность типов без генерации кода. Цель в том, чтобы типы в коде (TypeScript) точно отражали то, что происходит с данными во время работы агента.

Проблема

В системе с агентами финальная схема, которая отправляется ИИ, почти никогда не является просто схемой пользователя. Это комбинация из:

1. Схемы пользователя (цель).
2. Системных функций (вызовы Инструментов, Советники, мета-свойства).

Эти функции включаются обработчиками сообщений. Например, если добавить сообщение :term[Советник]{canonical="advisor" href="/simple-ru/acts/017*agent_advisor.md"} в контекст, специальный обработчик добавит в финальную схему массив advisors.

Решение: конвейер преобразования типов

Мы хотим создать систему типов, которая работает так же, как и логика выполнения. Как обработчики сообщений меняют JSON-схему во время работы, так же они должны изменять и уточнять тип в коде.

Процесс выглядит так:

1. Вывод типа: Схема пользователя превращается в тип T.
2. Уточнение: Каждый активный обработчик сообщений дополняет или изменяет T.
   • Обработчик Советника: Добавляет { advisors: Advisor[] }
   • Обработчик Инструмента: Добавляет { calls: Call[] }
   • Обработчик Мета-данных: Добавляет { meta: Meta }
3. Сборка: Финальный тип — это точное пересечение того, что хотел пользователь, и того, что умеет система.

Расширяемость

Эта архитектура создана открытой.

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

Считая схему единственным источником правды, мы гарантируем: если код скомпилировался, значит, он соответствует правилам.

Идея наблюдаемости и стандартизации

Мы стремимся ввести строгие стандарты для рабочих процессов агента, чтобы всё работало одинаково с разными ИИ-моделями.

Нормализация токенов

Разные модели по-разному считают использование ресурсов. Мы планируем привести эту статистику к единому виду, отслеживая:

• Входные токены: Сколько использовано памяти для контекста.
• Выходные токены: Сколько сгенерировано контента.
• Токены на размышление: Сколько ресурсов потрачено на внутренние рассуждения.

Прозрачность процесса мышления

Модели всё чаще показывают свои внутренние рассуждения. Мы считаем это важной частью протокола:

• Доступ: Предоставление прямого доступа к потоку «мыслей» модели.
• Бюджет: Стандартизация параметров «бюджета на размышления» для разных моделей. Это позволит агентам запрашивать нужную глубину рассуждений независимо от того, какой ИИ используется.

Архитектура с учётом кэширования

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

Метрики токенов

Мы будем отслеживать использование кэша, чтобы показать экономию:

• Токены, прочитанные из кэша: Данные, взятые из памяти.
• Токены, записанные в кэш: Новые данные, добавленные в память.

Оптимизация через дозапись

Чтобы кэш работал максимально эффективно, библиотека использует режимы, которые не сбрасывают его:

• Дозапись вместо перезаписи: Предпочтение отдаётся добавлению новых данных, а не замене всего контекста.
• Логика слияния: Использование естественного слияния Данных и Советников для постепенного обновления состояния.
• Режим вывода: Структурирование вывода так, чтобы он линейно продолжал историю диалога.

Управление контекстом

Чтобы найти баланс между использованием кэша и ограничениями памяти, мы предоставим настраиваемое Сжатие Контекста:

• Ленивое сжатие: Оптимизированный процесс, который сворачивает историю в один снимок только при необходимости, сохраняя кэш как можно дольше.
• Настройка: Переключатель «Оптимизация кэша» для включения этих функций в зависимости от требований к скорости и стоимости.