Hyperlight CodeAct

Hyperlight jest obecnie udokumentowanym zapleczem CodeActa w Agent Framework. Udostępnia execute_code narzędzie działające w odizolowanej piaskownicy i może wywoływać narzędzia hosta należące do dostawcy w sposób umożliwiany przez call_tool(...).

Aby zapoznać się z omówieniem na poziomie wzorca, zobacz CodeAct.

Dlaczego funkcja Hyperlight CodeAct

Nowoczesne agenty są często bardziej ograniczone przez koszty wywołania narzędzi niż przez sam model. Zadanie, które odczytuje dane, wykonuje lekkie obliczenia i tworzy wynik, może łatwo przekształcić się w łańcuch model -> narzędzie -> model -> narzędzie, nawet jeśli każdy pojedynczy krok jest prosty.

CodeAct wspierany przez Hyperlight upraszcza tę pętlę. Model zapisuje jeden krótki program w języku Python, piaskownica wykonuje go raz, a narzędzia należące do dostawcy są dostępne z poziomu piaskownicy za pomocą polecenia call_tool(...). W typowych obciążeniach narzędziowych tę zmianę można zmniejszyć opóźnienie o około połowę i użycie tokenów o ponad 60%, jednocześnie zapewniając izolację i możliwość inspekcji wykonania.

Wprowadzenie

Wkrótce.

Instalowanie pakietu 

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight jest dostarczany oddzielnie od agent-framework-coreprogramu, więc środowisko uruchomieniowe piaskownicy jest wymagane tylko wtedy, gdy jest to konieczne.

Uwaga / Notatka

Pakiet zależy od silników piaskownicy Hyperlight. Jeśli zaplecze nie zostało jeszcze opublikowane dla bieżącej platformy, wówczas execute_code nie udaje się utworzyć piaskownicy.

Użyj HyperlightCodeActProvider

HyperlightCodeActProvider jest zalecanym punktem wejścia, gdy funkcja CodeAct jest dodawana automatycznie dla każdego wykonania. Wprowadza on instrukcje CodeAct w zakresie wykonania oraz narzędzie execute_code, przy jednoczesnym zachowaniu narzędzi dostawcy poza bezpośrednim dostępem do narzędzi agenta.

Narzędzia zarejestrowane u dostawcy są dostępne w piaskownicy za pośrednictwem call_tool(...)programu , ale nie są widoczne jako narzędzia agenta bezpośredniego. Dostawca udostępnia również zarządzanie w stylu CRUD dla narzędzi, montowania plików i wpisów na liście dozwolonych dla ruchu wychodzącego za pomocą takich metod, jak add_tools(...), remove_tool(...), add_file_mounts(...) i add_allowed_domains(...).

Jak działają zatwierdzenia i narzędzia hosta

Narzędzia platformy agentów posiadają kontrolkę approval_mode , która kontroluje, czy mogą być wywoływane automatycznie, czy muszą zostać wstrzymane w celu zatwierdzenia przez użytkownika.

Główną różnicą między zarejestrowaniem narzędzia na HyperlightCodeActProvider a bezpośrednim zarejestrowaniem na Agent(tools=...) jest sposób, w jaki narzędzie jest wywoływane, a nie miejsce uruchamiania funkcji Python:

  • Narzędzia zarejestrowane na HyperlightCodeActProvider(tools=...) są ukryte przed modelem jako narzędzia bezpośrednie. Model osiąga je, pisząc kod wywołujący call_tool("name", ...) wewnątrz execute_code elementu.
  • Narzędzia zarejestrowane na platformie Agent(tools=...) są udostępniane modelowi jako narzędzia pierwszej klasy, a każde bezpośrednie wywołanie respektuje właściwości tego narzędzia zgodnie z jego approval_mode.

call_tool(...) jest mostkiem powrotnym do wywołań zwrotnych hosta; nie jest ponowną implementacją narzędzia w środowisku piaskownicy. Oznacza to, że narzędzia należące do dostawcy nadal są wykonywane w procesie hosta, z dowolnego systemu plików, sieci i poświadczeń, do których sam proces hosta może uzyskiwać dostęp.

Zasada ogólna:

  • Umieść tanie, deterministyczne, bezpieczne narzędzia łańcuchowe u dostawcy, aby model mógł wykonywać wiele wywołań w ramach jednego execute_code obrotu.
  • Zachowaj operacje mogące wywoływać skutki uboczne lub podlegające zatwierdzeniu jako bezpośrednie narzędzia agenta, często z elementami approval_mode="always_require", dzięki czemu każde wywołanie pozostaje widoczne i możliwe do zatwierdzenia.

Ponieważ narzędzia hosta działają poza piaskownicą, file_mounts oraz allowed_domains ograniczają kod w piaskownicy, a nie wywołanie zwrotne hosta za call_tool(...). Jeśli potrzebujesz kontrolowanego dostępu do poufnego zasobu, preferuj wąskie narzędzie hosta zamiast rozszerzania uprawnień piaskownicy.

Uwaga / Notatka

Narzędzia wywoływane za pomocą call_tool(...) zwracają swoją natywną wartość w Pythonie (dict, list, prymitywny lub niestandardowy obiekt) bezpośrednio do gościa. Każda result_parser skonfigurowana na obiekcie FunctionTool jest przeznaczona dla użytkowników zorientowanych na LLM i nie jest uruchamiana na ścieżce piaskownicy — należy zastosować formatowanie wewnątrz funkcji narzędzia, jeśli jest to potrzebne dla użytkowników w piaskownicy.

Użyj HyperlightExecuteCodeTool do bezpośredniego okablowania

Jeśli musisz mieszać execute_code z narzędziami przeznaczonymi wyłącznie do użytku bezpośredniego w tym samym środowisku agenta, użyj HyperlightExecuteCodeTool zamiast dostawcy narzędzi. W przypadku stałych konfiguracji można utworzyć instrukcje CodeAct raz i bezpośrednio połączyć narzędzie:

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)

Ten wzorzec jest przydatny, gdy powierzchnia CodeAct jest stała i nie potrzebujesz cyklu życia dostawcy przy każdym uruchomieniu. W przeciwieństwie do HyperlightCodeActProviderprogramu autonomiczne narzędzie nie automatycznie wprowadza wskazówek monitu, dlatego użytkownik jest odpowiedzialny za samodzielne dodawanie build_instructions(...) danych wyjściowych do instrukcji agenta.

Konfigurowanie plików i dostępu wychodzącego

Funkcja Hyperlight może uwidocznić drzewo /input tylko do odczytu oraz obszar do zapisu /output dla wygenerowanych artefaktów.

  • Użyj workspace_root, aby włączyć obszar roboczy pod /input/.
  • Użyj file_mounts do mapowania określonych ścieżek hosta do piaskownicy.
  • Służy allowed_domains do włączania dostępu wychodzącego tylko dla określonych obiektów docelowych lub metod.

file_mounts akceptuje skrócony ciąg, jawną (host_path, mount_path) parę lub nazwaną krotkę FileMount . allowed_domains akceptuje jako cel ciąg znaków, jawną parę (target, method-or-methods) lub krotkę nazwaną 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"),
    ],
)

Wskazówki dotyczące danych wyjściowych

Aby wyświetlić tekst z execute_code, zakończ kod za pomocą print(...); Hyperlight nie zwraca automatycznie wartości ostatniego wyrażenia.

Gdy dostęp do systemu plików jest włączony, zamiast tego należy zapisywać większe artefakty do /output/<filename>. Zwrócone pliki są dołączane do wyniku narzędzia, a pliki w obszarze /input są dostępne do odczytu wewnątrz piaskownicy.

Porównanie CodeAct i bezpośredniego wywołania narzędzi

Przykładowy test porównawczy uruchamia to samo zadanie z tym samym klientem, modelem, narzędziami, poleceniem i ustrukturyzowanym schematem danych wyjściowych raz za pomocą tradycyjnego sposobu wywołania narzędzia, a raz za pomocą wywołania opartego na technologii Hyperlight. Jedyną różnicą jest okablowanie: narzędzia bezpośrednie w porównaniu z jednym execute_code narzędziem wspieranym przez HyperlightCodeActProviderprogram .

W tym przykładzie agent oblicza sumy końcowe w zestawie danych użytkowników i zamówień, wielokrotnie wyszukując dane i wykonując obliczenia lekkie. Jest to dokładnie rodzaj przepływu pracy składającego się z wielu małych kroków, w którym CodeAct może usunąć obciążenie orkiestracji. Pełny przykład wyświetla upływający czas i użycie tokenów dla obydwu przebiegów, dzięki czemu można porównać przebieg wykonania we własnym środowisku.

Bieżące ograniczenia

Ten pakiet jest nadal w wersji alfa, a warto zaplanować działania wokół kilku ograniczeń.

  1. Obsługa platformy jest zgodna z opublikowanymi pakietami zaplecza funkcji Hyperlight. Obecnie oznacza to obsługiwane środowiska systemów Linux i Windows; nieobsługiwane platformy nie będą działać podczas tworzenia piaskownicy.
  2. Bieżąca integracja wykonuje kod gościa języka Python. Dokumentacja platformy .NET wkrótce będzie dostępna.
  3. Stan interpretera w pamięci nie jest utrwalany w oddzielnych execute_code wywołaniach. Użyj zamontowanych plików i /output artefaktów, gdy dane muszą być zachowane między wywołaniami.
  4. Zatwierdzenie ma zastosowanie do execute_code wywołania jako całości, a nie do każdego elementu call_tool(...) wewnątrz tego samego bloku kodu.
  5. Opisy narzędzi, adnotacje parametrów i zwracane wyniki mają większe znaczenie, ponieważ model pisze kod zgodnie z tym kontraktem, zamiast wybierać pojedyncze, bezpośrednie wywołania narzędzi.

Następne kroki

Purview

Treści powiązane

  • Last updated on