Hyperlight CodeAct

Inizia subito

Prossimamente.

Installare il pacchetto

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight viene fornito separatamente da agent-framework-core, quindi il runtime sandbox viene utilizzato solo quando necessario.

Utilizzare HyperlightCodeActProvider.

HyperlightCodeActProvider è il punto di ingresso consigliato quando si vuole aggiungere automaticamente CodeAct per ogni esecuzione. Inserisce le istruzioni CodeAct con ambito di esecuzione e lo strumento execute_code, mentre mantiene gli strumenti di proprietà del provider al di fuori della superficie degli strumenti dell'agente diretto.

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

Gli strumenti registrati nel provider sono disponibili all'interno della sandbox tramite call_tool(...), ma non vengono esposti come strumenti dell'agente diretto. Il provider espone anche la gestione in stile CRUD per strumenti, montaggi di file e voci di elenco elementi consentiti in uscita tramite metodi come add_tools(...), remove_tool(...), add_file_mounts(...)e add_allowed_domains(...).

Funzionamento delle approvazioni e degli strumenti host

Gli strumenti di Agent Framework contengono un oggetto approval_mode che controlla se possono essere richiamati automaticamente o devono essere sospesi per l'approvazione dell'utente.

La differenza principale tra la registrazione di uno strumento HyperlightCodeActProvider in e la registrazione diretta Agent(tools=...) è il modo in cui viene richiamato lo strumento, non dove viene eseguita la funzione Python:

• Gli strumenti registrati in HyperlightCodeActProvider(tools=...) sono nascosti dal modello come strumenti diretti. Il modello li raggiunge scrivendo codice che chiama call_tool("name", ...) all'interno di execute_code.
• Gli strumenti registrati in Agent(tools=...) vengono visualizzati nel modello come strumenti di prima classe e ogni chiamata diretta rispetta il proprio approval_modestrumento.

call_tool(...) è un ponte verso i callback dell'host; non è una reimplementazione dello strumento nell'ambiente sandbox. Ciò significa che gli strumenti di proprietà del provider vengono ancora eseguiti nel processo host, con qualsiasi file system, rete e credenziali a cui può accedere il processo host stesso.

Come regola generale:

• Inserire strumenti economici, deterministici e sicuri nel provider in modo che il modello possa comporre molte chiamate all'interno di un turno execute_code .
• Mantenere le operazioni con effetti collaterali o fornite di approvazione come strumenti di agente diretto, spesso con approval_mode="always_require", in modo che ogni invocazione rimanga visibile e approvabile singolarmente.

Poiché gli strumenti host vengono eseguiti all'esterno della sandbox, file_mounts e allowed_domains vincolano il codice in modalità sandbox e non il callback host gestito dietro call_tool(...). Quando è necessario un accesso controllato a una risorsa sensibile, è preferibile utilizzare uno strumento host dalle capacità limitate rispetto all'estensione delle autorizzazioni nella sandbox.

Uso HyperlightExecuteCodeTool per il cablaggio diretto

Quando è necessario mescolare execute_code con strumenti che funzionano solo direttamente sullo stesso agente, utilizzare HyperlightExecuteCodeTool anziché il provider. Per le configurazioni fisse, è possibile compilare le istruzioni codeAct una sola volta e collegare direttamente lo strumento:

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)

Questo modello è utile quando la superficie CodeAct è fissa e non è necessario il ciclo di vita del provider in ogni esecuzione. A differenza di HyperlightCodeActProvider, lo strumento autonomo non inserisce automaticamente istruzioni di suggerimento, quindi sei responsabile di aggiungere manualmente l'output build_instructions(...) alle istruzioni dell'agente.

Configurare i file e l'accesso in uscita

Hyperlight può esporre un albero /input di sola lettura e un'area /output scrivibile per gli artefatti generati.

• Usare workspace_root per rendere disponibile un'area di lavoro in /input/.
• Usare file_mounts per eseguire il mapping di percorsi host specifici nella sandbox.
• Usare allowed_domains per abilitare l'accesso in uscita solo per destinazioni o metodi specifici.

file_mounts accetta una stringa abbreviata, una coppia di valori esplicita (host_path, mount_path) o una FileMount tupla con nome. allowed_domains accetta una stringa di destinazione, una coppia esplicita (target, method-or-methods) o una AllowedDomain tupla nominata.

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

Indicazioni per l'output

Per visualizzare il testo da execute_code, terminare il codice con print(...); Hyperlight non restituisce automaticamente il valore dell'ultima espressione.

Quando l'accesso al file system è abilitato, scrivere invece su /output/<filename> contenuti di dimensioni maggiori. I file restituiti vengono allegati al risultato dello strumento, mentre i file all'interno di /input sono disponibili per la lettura nella sandbox.

Confrontare CodeAct e le chiamate dirette agli strumenti

L'esempio di benchmark esegue la stessa attività con lo stesso client, modello, strumenti, prompt e schema di output strutturato una volta tramite la chiamata allo strumento tradizionale e una volta tramite CodeAct basato su Hyperlight.The benchmark sample run the same task with the same client, model, tools, prompt, and structured output schema once through traditional tool calling and once through Hyperlight-backed CodeAct. L'unica differenza è il cablaggio: strumenti diretti rispetto a un singolo execute_code strumento supportato da 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 questo esempio, l'agente calcola i totali su un set di dati di utenti e ordini cercando ripetutamente i dati ed eseguendo leggeri calcoli. Questo è esattamente il tipo di flusso di lavoro di molti piccoli passaggi in cui CodeAct può rimuovere il sovraccarico dell'orchestrazione. L'esempio completo stampa il tempo trascorso e l'utilizzo dei token per entrambe le esecuzioni in modo da poter confrontare la forma di esecuzione nel proprio ambiente.

Limitazioni correnti

Questo pacchetto è ancora in fase alfa, e vale la pena tenere in considerazione alcuni vincoli durante la pianificazione:

1. Il supporto della piattaforma segue i pacchetti back-end Hyperlight pubblicati. Oggi significa ambienti Linux e Windows supportati; le piattaforme non supportate avranno esito negativo durante la creazione della sandbox.
2. L'integrazione corrente esegue il codice guest Python. La documentazione di .NET sarà ancora presto disponibile.
3. Lo stato dell'interprete in memoria non persiste tra diverse chiamate execute_code. Usare i file montati e gli artefatti /output quando i dati devono sopravvivere tra le chiamate.
4. L'approvazione si applica all'intera execute_code chiamata, non a ogni individuo call_tool(...) all'interno dello stesso blocco di codice.
5. Le descrizioni degli strumenti, le annotazioni dei parametri e i formati di ritorno sono molto più importanti perché il modello scrive codice in conformità con quel contratto anziché scegliere chiamate dirette isolate.