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

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

Акты (RFC)

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

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

Основные Примитивы

• 001: Агент/Запрос: Атомарная единица вычислений.
  • Преобразует Context + Schema в структурированное Solution.
  • Поддерживает мультиплексирование (одновременное создание нескольких решений).
  • Является основой для всех поведений агентов более высокого уровня.
• 002: Агент/Инструмент: Определение возможности в виде схемы.
  • Определяет интерфейс для действий отдельно от их реализации.
  • Позволяет LLM выбирать поведения на основе структурированных метаданных.
• 003: Агент/Действие: Явная, детерминированная реализация Инструмента в коде.
  • Связывает абстрактные схемы Инструментов с реальным кодом.
  • Поддерживает паттерн Двойного Реестра (разделение интерфейса и реализации).
• 004: Агент/Вызов: Конкретный экземпляр использования Инструмента.
  • Представляет собой параметризованный запрос на выполнение.
  • Служит стандартизированным транспортом между намерением LLM и действием системы.

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

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

Связывание и Поток

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

Орхестрация

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

Концепции

В то время как Акты, описанные выше, определяют механизмы, следующие концепции определяют философию архитектуры:

• 104: Концепция/Скрытое: Поведение по умолчанию "Без Кода".

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

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

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

• Человек-в-цикле (HITL):

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

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

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

Агент vs. Запрос

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

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

Request — это одна атомарная транзакция с LLM. Он предполагает соотношение 1<1> между входным контекстом/схемой и выходным решением.

• Управление: Он не зацикливается. Он выполняет ровно один шаг генерации.
• Мультиплексирование: Он поддерживает создание нескольких возможных решений из одного и того же контекста (с помощью параметра n).
• Стриминг и Колбэки: Он предоставляет механизм callbackPath. Это позволяет системе перехватывать и обрабатывать определённые части структуры (например, calls) по мере их поступления, обеспечивая выполнение инструментов в реальном времени, пока LLM ещё генерирует остальную часть ответа.

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

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

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

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

Чтобы избежать двойственности между двумя режимами, и Агент, и Запрос нормализуют свой вывод. Пользовательская схема всегда оборачивается в свойство output.

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

Видение Типобезопасности

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

Проблема

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

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

Эти функции переключаются Обработчиками Сообщений. Например, добавление сообщения Advisor в контекст активирует обработчик, который внедряет массив advisors в конечную схему вывода.

Решение: Конвейер Редукции Типов

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

Процесс работает следующим образом:

1. Вывод типа: Схема пользователя преобразуется в тип T с помощью FromSchema<S>.
2. Редукция: Каждый активный Обработчик Сообщений оборачивает или изменяет T.
   • Обработчик Советника: Добавляет { advisors: Advisor[] }
   • Обработчик Инструмента: Добавляет { calls: Call[] }
   • Обработчик Мета: Добавляет { meta: Meta }
3. Реконструкция: Конечный тип представляет собой строгое пересечение намерения пользователя и возможностей системы.

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

Эта архитектура спроектирована быть открытой.

• Пользовательские Обработчики: Пользователи могут регистрировать свои собственные обработчики сообщений. Эти обработчики могут изменять схему (во время выполнения) и участвовать в редукции типов (во время компиляции).
• Реестр Инструментов: Инструменты регистрируются глобально через Tool.register. Это определяет интерфейс возможности.
• Реестр Действий: Реализации регистрируются через Activity.register. Это определяет логику выполнения (код) для инструмента.
• Реестр Советников: (Планируется) Советники будут регистрироваться глобально, что позволит подключать определённые персоны и модели рассуждений к любому агенту.
• Реестр Схем: Схемы можно регистрировать через Схимию и ссылаться на них с помощью $ref (например, "$ref": "MySchema"), что позволяет повторно использовать типы по всей системе.

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

Видение Наблюдаемости и Стандартизации

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

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

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

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

Доступ к Мыслительному Процессу

Поскольку модели всё чаще предоставляют доступ к своим внутренним рассуждениям (CoT), мы рассматриваем это как первоклассного участника протокола:

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

Архитектура с Учётом Кэша

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

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

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

• Токены, Прочитанные из Кэша: Токены, полученные из кэша.
• Токены, Записанные в Кэш: Новые токены, добавленные в кэш.

Оптимизация Только для Добавления

Для максимального использования Кэширования Префиксов библиотека вводит специальные режимы работы, которые позволяют избежать инвалидации кэша:

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

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

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

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