Hyperlight CodeAct

Aan de slag

Binnenkort beschikbaar.

Installeer het pakket

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight wordt afzonderlijk geleverd van agent-framework-core, zodat u alleen de sandbox-runtime opneemt wanneer u deze nodig hebt.

Gebruik HyperlightCodeActProvider

HyperlightCodeActProvider is het aanbevolen toegangspunt wanneer u CodeAct automatisch wilt toevoegen voor elke uitvoering. Het injecteert run-scoped CodeAct-instructies plus execute_code tool, terwijl de provider-eigen tools buiten het directe bereik van de agent houden.

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}")

Hulpprogramma's geregistreerd op de provider zijn beschikbaar in de sandbox via call_tool(...), maar worden niet weergegeven als direct beschikbare agenthulpprogramma's. De provider maakt ook CRUD-stijlbeheer beschikbaar voor tools, bestandkoppelingen en uitgaande allow-list-vermeldingen via methoden zoals add_tools(...), remove_tool(...), add_file_mounts(...) en add_allowed_domains(...).

Hoe goedkeuringen en hosthulpprogramma's werken

Agent Framework-hulpprogramma's bevatten een approval_mode die bepaalt of ze automatisch kunnen worden aangeroepen of moeten worden onderbroken voor goedkeuring van de gebruiker.

Het belangrijkste verschil tussen het registreren van een hulpprogramma HyperlightCodeActProvider en het rechtstreeks Agent(tools=...) registreren ervan is hoe het hulpprogramma wordt aangeroepen, niet waar de Python-functie uiteindelijk wordt uitgevoerd:

• Geregistreerde hulpprogramma's op HyperlightCodeActProvider(tools=...) zijn verborgen voor het model als directe tools. Het model bereikt ze door code te schrijven die call_tool("name", ...) aanroept binnen execute_code.
• Hulpprogramma's die zijn geregistreerd op Agent(tools=...), worden als eersteklas hulpprogramma's weergegeven aan het model en bij elke directe aanroep wordt de eigen approval_mode gerespecteerd.

call_tool(...) is een brug terug naar host-callbacks; het is geen in-sandbox herimplementatie van het hulpprogramma. Dit betekent dat hulpprogramma's die eigendom zijn van de provider nog steeds worden uitgevoerd in het hostproces, met elk bestandssysteem, netwerk en referenties waartoe het hostproces zelf toegang heeft.

Vuistregel:

• Plaats goedkope, deterministische, veilig te koppelen hulpprogramma's op de provider, zodat het model veel aanroepen binnen één execute_code cyclus kan samenstellen.
• Houd side-effect-inducerende of goedkeuringsgebonden bewerkingen als directe agenttools en vaak met approval_mode="always_require", zodat elke aanroep afzonderlijk zichtbaar en keurbaar blijft.

Omdat hosthulpprogramma's buiten de sandbox worden uitgevoerd, beperken file_mounts en allowed_domains de code in de sandbox zelf, niet de callback van de host achter call_tool(...). Wanneer u gecontroleerde toegang tot een gevoelige resource nodig hebt, geeft u de voorkeur aan een beperkte hosttool boven het verruimen van sandbox-machtigingen.

Gebruiken HyperlightExecuteCodeTool voor directe bedrading

Gebruik execute_code in plaats van de provider wanneer u HyperlightExecuteCodeTool moet combineren met hulpprogramma's voor direct-only op dezelfde agent. Voor vaste configuraties kunt u de CodeAct-instructies eenmaal compileren en het hulpprogramma rechtstreeks bedraden:

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)

Dit patroon is handig wanneer het CodeAct-oppervlak gefixeerd is en de levenscyclus van de provider niet bij elke uitvoering nodig is. In tegenstelling tot HyperlightCodeActProvider injecteert het zelfstandige hulpprogramma promptrichtlijnen niet automatisch, dus u bent zelf verantwoordelijk voor het toevoegen van de build_instructions(...) uitvoer aan de agentinstructies.

Configureer bestanden en uitgaande toegang

Hyperlight kan een structuur met het kenmerk Alleen-lezen /input weergeven plus een beschrijfbaar /output gebied voor gegenereerde artefacten.

• Gebruik workspace_root dit om een werkruimte beschikbaar te maken onder /input/.
• Gebruik file_mounts om specifieke hostpaden naar de sandbox te mappen.
• Gebruik allowed_domains dit om uitgaande toegang alleen in te schakelen voor specifieke doelen of methoden.

file_mounts accepteert een verkorte notatie, een expliciet (host_path, mount_path) paar of een FileMount genoemde tuple. allowed_domains accepteert een doelstring, een expliciet (target, method-or-methods) paar of een AllowedDomain tuple met naam.

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

Richtlijnen voor uitvoer

Om tekst uit execute_code weer te geven, beëindig de code met print(...); Hyperlight retourneert de waarde van de laatste expressie niet automatisch.

Wanneer de toegang tot het bestandssysteem is ingeschakeld, sla dan grotere objecten op in /output/<filename>. Geretourneerde bestanden worden gekoppeld aan het resultaat van het hulpprogramma, terwijl bestanden onder /input beschikbaar zijn om te lezen in de sandbox.

CodeAct en directe hulpprogramma-aanroepen vergelijken

In het benchmarkvoorbeeld wordt dezelfde taak uitgevoerd met dezelfde client, model, hulpprogramma's, prompt en gestructureerd uitvoerschema één keer via het traditionele aanroepen van hulpprogramma's en eenmaal via CodeAct met Hyperlight-ondersteuning. Het enige verschil is de bedrading: directe gereedschappen versus één execute_code gereedschap dat ondersteund wordt door HyperlightCodeActProvider.

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 dat voorbeeld berekent de agent eindtotalen voor een gegevensset van gebruikers en orders door herhaaldelijk gegevens op te zoeken en lichte berekeningen uit te voeren. Dat is precies het soort werkstroom met veel kleine stappen, waarbij CodeAct de orchestration-overhead kan verwijderen. In het volledige voorbeeld worden de verstreken tijd en het tokengebruik voor beide uitvoeringen getoond, zodat u het uitvoeringspatroon in uw eigen omgeving kunt vergelijken.

Huidige beperkingen

Dit pakket bevindt zich nog steeds in de alfafase en het is verstandig om met een paar beperkingen rekening te houden.

1. Platformondersteuning volgt de gepubliceerde Hyperlight-back-endpakketten. Tegenwoordig betekent dit ondersteunde Linux- en Windows-omgevingen; niet-ondersteunde platforms mislukken bij het maken van de sandbox.
2. De huidige integratie voert Python-gastcode uit. De .NET-documentatie is binnenkort beschikbaar.
3. De toestand van de in-memory interpreter blijft niet behouden bij aparte execute_code aanroepen. Gebruik gekoppelde bestanden en /output artefacten wanneer gegevens moeten blijven bestaan tussen aanroepen.
4. Goedkeuring is van toepassing op de execute_code aanroep als geheel, niet op elke persoon call_tool(...) in hetzelfde codeblok.
5. Beschrijvingen van hulpprogramma's, parameteraantekeningen en de vorm van retourwaarden zijn hier belangrijker omdat het model code schrijft op basis van dat contract in plaats van voor geïsoleerde directe hulpprogramma-oproepen te kiezen.