Hyperlight CodeAct

Get started

Bald verfügbar.

Installiere das Paket

pip install agent-framework-hyperlight --pre

wird separat von versendet, sodass Sie die Sandbox-Ausführungsumgebung nur übernehmen, wenn Sie sie benötigen.

HyperlightCodeActProvider verwenden

HyperlightCodeActProvider ist der empfohlene Einstiegspunkt, wenn CodeAct für jede Ausführung automatisch hinzugefügt werden soll. Es fügt laufbereichsspezifische CodeAct-Anweisungen sowie das execute_code-Tool ein, während anbietereigene Tools von der direkten Agenten-Tooloberfläche ferngehalten werden.

async def main() -> None:
    """Run the provider-owned Hyperlight CodeAct sample."""
    # 1. Create the Hyperlight-backed provider and register sandbox tools on it.
    codeact = HyperlightCodeActProvider(
        tools=[compute, fetch_data],
        approval_mode="never_require",
    )

    # 2. Create the client and the agent.
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        name="HyperlightCodeActProviderAgent",
        instructions="You are a helpful assistant.",
        context_providers=[codeact],
        middleware=[log_function_calls],
    )

    # 3. Run a request that should use execute_code plus provider-owned tools.
    query = (
        "Fetch all users, find admins, multiply 7*(3*2), and print the users, "
        "admins, and multiplication result. Use execute_code and call_tool(...) "
        "inside the sandbox."
    )
    print(f"{_CYAN}{'=' * 60}")
    print("Hyperlight CodeAct provider sample")
    print(f"{'=' * 60}{_RESET}")
    print(f"{_CYAN}User: {query}{_RESET}")
    result = await agent.run(query)
    print(f"{_CYAN}Agent: {result.text}{_RESET}")

Tools, die beim Anbieter registriert sind, sind im Sandkasten call_tool(...)verfügbar, werden jedoch nicht als direkte Agenten-Tools verfügbar gemacht. Der Anbieter stellt auch die Verwaltung im CRUD-Format für Tools, Datei-Mounts und ausgehende Zulassungslisteneinträge über Methoden wie add_tools(...), remove_tool(...), add_file_mounts(...) und add_allowed_domains(...) bereit.

Funktionsweise von Genehmigungen und Hosttools

Agent-Framework-Tools enthalten ein approval_mode Steuerelement, welches bestimmt, ob sie automatisch initiiert werden können oder zuerst eine Benutzergenehmigung benötigen.

Der Hauptunterschied zwischen der Registrierung eines Tools HyperlightCodeActProvider und der direkten Registrierung auf Agent(tools=...) besteht darin, wie das Tool aufgerufen wird und nicht, wo die Python-Funktion letztendlich ausgeführt wird:

• Auf HyperlightCodeActProvider(tools=...) registrierte Tools sind im Modell als direkte Tools nicht sichtbar. Das Modell greift auf sie zu, indem es Code schreibt, der call_tool("name", ...) innerhalb execute_code aufgerufen wird.
• Auf dem Modell registrierte Agent(tools=...) Tools werden dem Modell als erstklassige Tools bereitgestellt, und bei jedem direkten Aufruf wird das spezifische approval_mode des Tools berücksichtigt.

call_tool(...) ist eine Rückkehrbrücke zu Host-Rückrufen; es ist keine Neuimplementierung des Tools innerhalb der Sandbox. Dies bedeutet, dass anbietereigene Tools weiterhin im Hostprozess ausgeführt werden, mit dem Dateisystem, Netzwerk und Anmeldeinformationen, auf die der Hostprozess selbst zugreifen kann.

Faustregel:

• Setzen Sie günstige, deterministische, sicher verkettbare Tools beim Anbieter ein, damit das Modell viele Aufrufe in einem execute_code Durchgang verfassen kann.
• Halten Sie Operationen, die Nebenwirkungen haben oder genehmigungspflichtig sind, als direkte Werkzeuge des Agenten, oft mit approval_mode="always_require", sodass jeder Aufruf einzeln sichtbar und genehmigungsfähig bleibt.

Da Hosttools außerhalb der Sandbox file_mounts ausgeführt werden, schränken allowed_domains den im Sandkasten ausgeführten Code selbst ein, nicht den Host-Rückruf hinter call_tool(...). Wenn Sie kontrollierten Zugriff auf eine sensible Ressource benötigen, bevorzugen Sie ein spezialisiertes Host-Tool gegenüber der Erweiterung von Sandkastenberechtigungen.

Verwenden Sie HyperlightExecuteCodeTool für die direkte Verkabelung

Wenn Sie execute_code zusammen mit Tools verwenden müssen, die nur direkt sind, auf demselben Agenten, verwenden Sie HyperlightExecuteCodeTool anstelle des Anbieters. Bei festen Konfigurationen können Sie die CodeAct-Anweisungen einmal erstellen und das Tool direkt verbinden:

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)

Dieses Muster ist nützlich, wenn die CodeAct-Oberfläche festgelegt ist und Sie den Lebenszyklus des Anbieters nicht bei jedem Durchlauf benötigen. Im Gegensatz zu HyperlightCodeActProvider fügt das Standalone-Tool keine Aufforderungen automatisch ein, daher sind Sie dafür verantwortlich, die build_instructions(...)-Ausgabe selbst in die Agenten-Anweisungen einzufügen.

Konfigurieren von Dateien und ausgehender Zugriff

Hyperlight kann eine schreibgeschützte /input Struktur sowie einen schreibbaren /output Bereich für generierte Artefakte verfügbar machen.

• Verwenden Sie workspace_root, um einen Arbeitsbereich unter /input/ verfügbar zu machen.
• Verwenden Sie file_mounts, um bestimmte Hostpfade in die Sandbox zuzuordnen.
• Verwenden Sie allowed_domains, um den ausgehenden Zugriff nur für bestimmte Ziele oder Methoden zu aktivieren.

file_mounts akzeptiert eine Abkürzungszeichenfolge, ein explizites (host_path, mount_path) Paar oder ein benanntes FileMount Tupel. allowed_domains akzeptiert eine Zeichenfolge als Ziel, ein explizites (target, method-or-methods) Paar oder ein AllowedDomain benanntes Tupel.

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"),
    ],
)

Ausgabeleitfaden

Um Text aus execute_codeanzuzeigen, beenden Sie den Code mit print(...); Hyperlight gibt den Wert des letzten Ausdrucks nicht automatisch zurück.

Wenn der Dateisystemzugriff aktiviert ist, schreiben Sie größere Artefakte stattdessen in /output/<filename>. Zurückgegebene Dateien sind dem Tool-Ergebnis beigefügt, während Dateien unter /input in der Sandbox zum Lesen verfügbar sind.

Vergleichen von CodeAct- und direkten Toolaufrufen

Im Benchmarkbeispiel wird dieselbe Aufgabe mit demselben Client-, Modell-, Tools-, Eingabeaufforderungs- und strukturierten Ausgabeschema einmal über herkömmliche Toolaufrufe und einmal über Hyperlight-backed CodeAct ausgeführt. Der einzige Unterschied besteht in der Verdrahtung: direkt verbundene Tools im Vergleich zu einem einzelnen execute_code Werkzeug, das von HyperlightCodeActProvider unterstützt wird.

async def _run_traditional() -> tuple[float, AgentResponse]:
    agent = Agent(
        client=get_client(),
        name="TraditionalAgent",
        instructions=INSTRUCTIONS,
        tools=TOOLS,
        default_options={"response_format": UserGrandTotals},
    )
    start = time.perf_counter()
    result = await agent.run(BENCHMARK_PROMPT)
    elapsed = time.perf_counter() - start
    return elapsed, result


async def _run_codeact() -> tuple[float, AgentResponse]:
    codeact = HyperlightCodeActProvider(
        tools=TOOLS,
        approval_mode="never_require",
    )
    agent = Agent(
        client=get_client(),
        name="CodeActAgent",
        instructions=INSTRUCTIONS,
        context_providers=[codeact],
        default_options={"response_format": UserGrandTotals},
    )
    start = time.perf_counter()
    result = await agent.run(BENCHMARK_PROMPT)
    elapsed = time.perf_counter() - start
    return elapsed, result

In diesem Beispiel berechnet der Agent Gesamtsummen über ein Dataset von Benutzern und Bestellungen, indem Daten wiederholt nachgeschlagen und leichte Berechnungen durchgeführt werden. Genau dies ist die Art von Workflow mit vielen kleinen Schritten, bei dem CodeAct den Orchestrierungsaufwand entfernen kann. Das vollständige Beispiel zeigt die verstrichene Zeit und die Tokenverwendung für beide Ausführungen, sodass Sie die Ausführungsstruktur in Ihrer eigenen Umgebung vergleichen können.

Aktuelle Einschränkungen

Dieses Paket ist noch Alpha, und ein paar Einschränkungen sind eine Planung wert:

1. Die Plattformunterstützung folgt den veröffentlichten Hyperlight-Back-End-Paketen. Heute bedeutet dies unterstützte Linux- und Windows-Umgebungen; Nicht unterstützte Plattformen schlagen beim Erstellen der Sandbox fehl.
2. Die aktuelle Integration führt Python-Gastcode aus. Die .NET-Dokumentation wird in Kürze noch verfügbar sein.
3. Der In-Memory-Interpreter-Zustand bleibt über separate execute_code Aufrufe hinweg nicht bestehen. Verwenden Sie bereitgestellte Dateien und /output Artefakte, wenn Daten über Aufrufe hinweg überleben müssen.
4. Die Genehmigung gilt für den execute_code ganzen Aufruf und nicht für jede Instanz call_tool(...) innerhalb desselben Codeblocks.
5. Toolbeschreibungen, Parameteranmerkungen und Rückgabeformen sind hier wichtiger, da das Modell Code für diesen Vertrag schreibt, anstatt isolierte direkte Toolaufrufe auszuwählen.