Hyperlight CodeAct

Hyperlight — это задокументированная серверная часть для CodeAct в Agent Framework. Он предоставляет execute_code средство, поддерживаемое изолированной средой выполнения песочницы, и может вызывать средства call_tool(...) узла, принадлежащие поставщику.

Общие сведения о уровне шаблона см. в разделе CodeAct.

Почему Hyperlight CodeAct

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

Hyperlight поддерживаемый CodeAct оптимизирует этот цикл. Модель записывает одну короткую программу на Python, песочница выполняет её один раз, и инструменты, принадлежащие поставщику, доступны из песочницы с помощью call_tool(...). В репрезентативных нагрузках с преобладанием инструментов этот сдвиг может сократить задержку примерно вдвое и использование токенов более чем на 60%, сохраняя при этом изоляцию выполнения и возможность аудита.

Get started

Скоро.

Установите пакет

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight поставляется отдельно от agent-framework-core, поэтому вы используете только песочницу, когда это необходимо.

Note

Пакет зависит от компонентов песочницы Hyperlight. Если серверная часть еще не опубликована для вашей текущей платформы, execute_code попытается создать песочницу, но это завершится ошибкой.

Используйте HyperlightCodeActProvider

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

Инструменты, зарегистрированные у поставщика, доступны внутри песочницы через call_tool(...), но они не предоставляются как прямые инструменты агента. Поставщик также предоставляет управление в стиле CRUD для инструментов, подключений файлов и исходящих записей списка разрешений с помощью таких методов, как add_tools(...), remove_tool(...), add_file_mounts(...) и add_allowed_domains(...).

Как работают утверждения и инструменты хоста

Средства Agent Framework содержат approval_mode, который управляет тем, могут ли они вызываться автоматически или должны быть приостановлены для утверждения пользователя.

Основное различие между регистрацией инструмента на HyperlightCodeActProvider и регистрацией его непосредственно на Agent(tools=...) заключается в том, как вызывается инструмент, а не где в конечном счете выполняется функция Python:

  • Средства, зарегистрированные на HyperlightCodeActProvider(tools=...), скрыты от модели в качестве прямых средств. Модель достигает их путем написания кода, вызывающего call_tool("name", ...) внутри execute_code.
  • Средства, зарегистрированные на Agent(tools=...) ней, отображаются в модели как средства первого класса, и каждый прямой вызов учитывает собственный approval_modeинструмент.

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

Как правило:

  • Поместите дешевые, детерминированные, безопасные для цепочки инструменты на поставщика, так чтобы модель могла создавать множество вызовов внутри одного execute_code шага.
  • Сохраняйте побочные эффекты или операции, требующие одобрения, как прямые средства агента, часто с approval_mode="always_require", чтобы каждое вызов оставался по отдельности видимым и подлежащим одобрению.

Поскольку хост-инструменты выполняются за пределами песочницы, file_mounts и allowed_domains ограничивают сам изолированный код, а не обратный вызов узла за call_tool(...). Когда вам нужен контролируемый доступ к конфиденциальному ресурсу, предпочитайте узкое средство узла вместо расширения разрешений песочницы.

Note

Средства, вызываемые через call_tool(...), возвращают значение Python (dict, list, примитив или пользовательский объект) непосредственно в гостевую систему. Любой result_parser, настроенный на FunctionTool, предназначен для потребителей, использующих интерфейс LLM, и не выполняется по пути песочницы — применяйте форматирование внутри функции инструмента, если оно нужно для пользователей песочницы.

Используйте HyperlightExecuteCodeTool для прямого подключения

Если вам нужно интегрировать execute_code с инструментами, работающими только напрямую, на одном агенте, используйте HyperlightExecuteCodeTool вместо провайдера. Для фиксированных конфигураций можно создать инструкции CodeAct один раз и подключить средство напрямую:

from agent_framework_hyperlight import HyperlightExecuteCodeTool

execute_code = HyperlightExecuteCodeTool(
    tools=[compute],
    approval_mode="never_require",
)

codeact_instructions = execute_code.build_instructions(tools_visible_to_model=False)

Этот шаблон полезен, когда поверхность CodeAct является фиксированной, и жизненный цикл поставщика не требуется для каждого запуска. В отличие от самостоятельного средства, инструмент не внедряет руководство по запросу автоматически, поэтому вы несете HyperlightCodeActProviderответственность за добавление build_instructions(...) выходных данных в инструкции для агента самостоятельно.

Настройка файлов и исходящего доступа

Гиперлайт может предоставить дерево /input, доступное только для чтения, и область /output для записи, предназначенную для результатов генерации артефактов.

  • Используйте workspace_root, чтобы сделать рабочую область доступной в /input/.
  • Используйте file_mounts для сопоставления определенных путей хоста в песочницу.
  • Используйте allowed_domains для включения исходящего доступа только для определенных целевых объектов или методов.

file_mounts принимает строку в сокращенном формате, явную пару значений или именованный кортеж (host_path, mount_path). allowed_domains принимает строковый целевой объект, явную (target, method-or-methods) пару или именованный AllowedDomain кортеж.

from agent_framework_hyperlight import HyperlightCodeActProvider

codeact = HyperlightCodeActProvider(
    tools=[compute],
    file_mounts=[
        "/host/data",
        ("/host/models", "/sandbox/models"),
    ],
    allowed_domains=[
        "api.github.com",
        ("internal.api.example.com", "GET"),
    ],
)

Руководство по результатам

Чтобы получить текст из execute_code, завершите код с помощью print(...); Hyperlight не возвращает значение последнего выражения автоматически.

Если доступ к файловой системе включен, записывайте более крупные артефакты в /output/<filename> вместо этого. Возвращенные файлы присоединяются к результату средства, тогда как файлы под /input доступны для чтения в песочнице.

Сравнение CodeAct и прямой вызов инструментов

Пример теста выполняет ту же задачу с тем же клиентом, моделью, инструментами, подсказками и структурированной выходной схемой один раз через вызов традиционного средства и один раз через Hyperlight-backed CodeAct. Единственное различие заключается в проводке: прямые инструменты по сравнению с одним инструментом execute_code, поддерживаемым HyperlightCodeActProvider.

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

Текущие ограничения

Этот пакет по-прежнему находится на стадии альфа-версии, и стоит учитывать некоторые ограничения:

  1. Поддержка платформы согласуется с опубликованными пакетами бэкенда Hyperlight. Сегодня это означает поддерживаемые среды Linux и Windows, а создание песочницы на неподдерживаемых платформах не удастся.
  2. Текущая интеграция выполняет гостевой код Python. Документация по .NET по-прежнему ожидается в ближайшее время.
  3. Состояние интерпретатора в памяти не сохраняется в разных вызовах execute_code . Используйте подключенные файлы и /output артефакты, когда данные должны сохраняться между вызовами.
  4. Утверждение применяется к execute_code вызову в целом, а не к каждому call_tool(...) внутри одного блока кода.
  5. Описания инструментов, аннотации параметров и формы возвращаемых значений имеют большее значение здесь, так как модель пишет код в соответствии с этим контрактом, а не использует изолированные прямые вызовы инструментов.

Дальнейшие действия

Обзор

Связанный контент

  • Last updated on