Hyperlight CodeAct

Installiere das Paket

dotnet add package Microsoft.Agents.AI.Hyperlight --prerelease

Microsoft.Agents.AI.Hyperlight wird getrennt von den Kernabstraktionen ausgeliefert, sodass Sie die Sandbox-Laufzeit nur einbinden, 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 handelt sich um eine AIContextProvider, die laufspezifische CodeAct-Anweisungen sowie das Tool execute_code einschleust, während anbietereigene Tools von der direkten Tool-Oberfläche des Agenten ferngehalten werden. Der Anbieter wendet snapshot/restore pro Ausführung an, sodass der Gast bei jedem Aufruf von einem bekannten sauberen Zustand beginnt.

Verwenden Sie die HyperlightCodeActProviderOptions.CreateForWasm(modulePath) Factory, um den Wasm-basierten Python-Gast anzusprechen, der von den Beispielen verwendet wird; CreateForJavaScript() ist auch für das JavaScript-Backend verfügbar.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hyperlight;
using OpenAI.Chat;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
var guestPath = Environment.GetEnvironmentVariable("HYPERLIGHT_PYTHON_GUEST_PATH")
    ?? throw new InvalidOperationException("HYPERLIGHT_PYTHON_GUEST_PATH is not set.");

using var codeAct = new HyperlightCodeActProvider(
    HyperlightCodeActProviderOptions.CreateForWasm(guestPath));

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions()
    {
        ChatOptions = new()
        {
            Instructions = "You are a helpful assistant. When the user asks something quantitative, "
                + "write Python and call `execute_code` instead of guessing.",
        },
        AIContextProviders = [codeAct],
    });

Console.WriteLine(await agent.RunAsync("What is the 20th Fibonacci number?"));

Werkzeuge, Datei-Einhängepunkte und Einträge in der Zulassungsliste für ausgehende Verbindungen können im Voraus über HyperlightCodeActProviderOptions (Tools, FileMounts, AllowedDomains, HostInputDirectory) bereitgestellt oder zur Laufzeit über die AddTools(...), RemoveTools(...), ClearTools(), AddFileMounts(...), AddAllowedDomains(...) des Anbieters sowie entsprechende Get*-Accessoren verwaltet werden.

Funktionsweise von Genehmigungen und Hosttools

Agent Framework-Tools enthalten Genehmigungsmetadaten, die steuern, ob sie automatisch aufgerufen werden können, oder zur Benutzergenehmigung anhalten müssen. In .NET muss die Freigabe explizit aktiviert werden, indem ein AIFunction in ApprovalRequiredAIFunction eingeschlossen wird.

Der Hauptunterschied zwischen der Registrierung eines Tools auf HyperlightCodeActProvider und seiner direkten Registrierung beim Agenten besteht darin, wie das Tool aufgerufen wird, und nicht darin, wo die Funktion letztendlich ausgeführt wird:

• Auf HyperlightCodeActProviderOptions.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.
• Tools, die direkt auf dem Agent registriert sind (z. B. via AsAIAgent(tools: [...])), werden dem Modell als erstklassige Tools angezeigt, und jeder direkte Aufruf berücksichtigt die eigenen Genehmigungsmetadaten dieses Tools.

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.

Das CodeActApprovalMode Enum steuert, wie das execute_code Werkzeug selbst genehmigt wird:

• CodeActApprovalMode.NeverRequire (Standard): Die Genehmigung wird von den registrierten Tools weitergegeben. Wenn ein Tool in der Registry in ApprovalRequiredAIFunction eingebettet ist, erfordert execute_code ebenfalls eine Genehmigung; andernfalls nicht.
• CodeActApprovalMode.AlwaysRequire: execute_code Erfordert vor dem Aufruf immer eine Benutzergenehmigung.

Faustregel:

• Setzen Sie günstige, deterministische, sicher verkettbare Tools beim Anbieter ein, damit das Modell viele Aufrufe in einem execute_code Durchgang verfassen kann.
• Kapseln Sie nebenwirkungsbehaftete oder sensible Operationen in ApprovalRequiredAIFunction (und ziehen Sie in Betracht, sie stattdessen als direkte Agent-Tools beizubehalten), sodass jede Ausführung einzeln sichtbar und genehmigbar bleibt.

Im nächsten Beispiel werden zwei sichere Tools (fetch_docs, query_data) sowie ein sensibles send_email-Tool registriert, das in ApprovalRequiredAIFunction eingebettet ist. Da mindestens ein registriertes Tool eine Genehmigung erfordert, führt der Standardmodus NeverRequire dazu, dass execute_code selbst bei jedem Aufruf eine Genehmigung erfordert.

AIFunction fetchDocs = AIFunctionFactory.Create(
    (string topic) => $"Docs for {topic}: (...)",
    name: "fetch_docs",
    description: "Fetch documentation for a given topic.");

AIFunction queryData = AIFunctionFactory.Create(
    (string query) => $"Rows for `{query}`: []",
    name: "query_data",
    description: "Run a read-only SQL-like query against the sample store.");

AIFunction sendEmail = new ApprovalRequiredAIFunction(
    AIFunctionFactory.Create(
        (string to, string subject) => $"Sent '{subject}' to {to}.",
        name: "send_email",
        description: "Send an email on behalf of the user."));

var options = HyperlightCodeActProviderOptions.CreateForWasm(guestPath);
options.Tools = [fetchDocs, queryData, sendEmail];

using var codeAct = new HyperlightCodeActProvider(options);

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions()
    {
        ChatOptions = new()
        {
            Instructions = "You are a helpful assistant. Prefer orchestrating your work in a single "
                + "`execute_code` block using `call_tool(...)` over issuing many direct tool calls.",
        },
        AIContextProviders = [codeAct],
    });

Da Hosttools außerhalb der Sandbox FileMounts ausgeführt werden, schränken AllowedDomains 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 HyperlightExecuteCodeFunction für die direkte Verkabelung

Wenn Sie execute_code auf demselben Agenten mit Tools kombinieren müssen, die nur direkt verwendet werden können, oder wenn die Sandkastenkonfiguration während der gesamten Lebensdauer des Agenten festgelegt ist, verwenden Sie HyperlightExecuteCodeFunction anstelle des Providers. Es ist ein eigenständiges AIFunction Gerät, das eine einzelne Momentaufnahme der bereitgestellten Optionen zur Bauzeit erfasst und für jeden Aufruf wiederverwendet.

Im Gegensatz zu HyperlightCodeActProvider fügt die eigenständige Funktion keine Prompt-Anleitung automatisch ein, daher sind Sie selbst dafür verantwortlich, die Ausgabe von BuildInstructions(...) zu den Agentenanweisungen hinzuzufügen. Übergeben Sie toolsVisibleToModel: false, wenn die registrierten Tools nur über call_tool(...) erreichbar sind, und true, wenn dieselben Tools dem Modell auch direkt zugänglich sind.

AIFunction calculate = AIFunctionFactory.Create(
    (double a, double b) => a * b,
    name: "multiply",
    description: "Multiply two numbers.");

var options = HyperlightCodeActProviderOptions.CreateForWasm(guestPath);
options.Tools = [calculate];

using var executeCode = new HyperlightExecuteCodeFunction(options);

var instructions =
    "You are a helpful assistant. When math is involved, solve it by writing Python "
    + "and calling `execute_code` instead of computing values yourself.\n\n"
    + executeCode.BuildInstructions(toolsVisibleToModel: false);

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(instructions: instructions, tools: [executeCode]);

HyperlightExecuteCodeFunction implementiert auch IDisposable. Wenn die Konfiguration eine Genehmigung erfordert (gemäß ApprovalMode oder weil ein konfiguriertes Tool selbst in ApprovalRequiredAIFunction eingebettet ist), stellt die Instanz über ApprovalRequiredAIFunction einen AITool.GetService(...)-Proxy bereit, worüber der Rest des Frameworks Genehmigungsanforderungen erkennt.

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 HostInputDirectory, um ein Hostverzeichnis unter /input/ verfügbar zu machen.
• Verwenden Sie FileMounts, um bestimmte Hostpfade über new FileMount(hostPath, mountPath) der Sandbox zuzuordnen.
• Verwenden Sie AllowedDomains, um ausgehenden Zugriff nur für bestimmte Ziele oder Methoden über new AllowedDomain(target, methods) zu aktivieren.

var options = HyperlightCodeActProviderOptions.CreateForWasm(guestPath);
options.Tools = [compute];
options.FileMounts =
[
    new FileMount("/host/data", "/input/data"),
    new FileMount("/host/models", "/sandbox/models"),
];
options.AllowedDomains =
[
    new AllowedDomain("https://api.github.com"),
    new AllowedDomain("https://internal.api.example.com", ["GET"]),
];

using var codeAct = new HyperlightCodeActProvider(options);

Die gleichen FileMounts- und AllowedDomains-Sammlungen sowie Tools können zur Laufzeit auch über AddFileMounts(...), RemoveFileMounts(...), AddAllowedDomains(...) und RemoveAllowedDomains(...) auf HyperlightCodeActProvider geändert werden.

Ausgabeleitfaden

Um Text von execute_codeanzuzeigen, beenden Sie den Gastcode 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.

Aktuelle Einschränkungen

Dieses Paket befindet sich noch in der Vorschauphase, und es gibt einige Einschränkungen, die Sie bei Ihrer Planung berücksichtigen sollten:

1. Das Paket hängt von Hyperlight.HyperlightSandbox.Api ab, das noch nicht auf nuget.org veröffentlicht ist. Bis dahin schlägt die Projektwiederherstellung fehl.
2. Die Plattformunterstützung richtet sich nach den veröffentlichten Hyperlight-Backend-Paketen: den unterstützten Linux- (KVM) und Windows-Umgebungen (WHP). Nicht unterstützte Plattformen oder fehlende Virtualisierungs-Back-Ends schlagen beim Erstellen der Sandbox fehl.
3. Das aktuelle Wasm-Back-End führt ein Python Gastmodul aus, das durch HYPERLIGHT_PYTHON_GUEST_PATH angegeben wird. Das JavaScript-Back-End (CreateForJavaScript()) ist für Gastcode in JavaScript verfügbar.
4. 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.
5. Die Genehmigung gilt für den execute_code ganzen Aufruf und nicht für jede Instanz call_tool(...) innerhalb desselben Codeblocks.
6. Toolbeschreibungen, Parameteranmerkungen und Rückgabeformen sind hier wichtiger, da das Modell Code für diesen Vertrag schreibt, anstatt isolierte direkte Toolaufrufe auszuwählen.
7. Es gibt noch keine .NET-Entsprechung des Python-Benchmarkbeispiels – siehe die Python-Registerkarte für das veröffentlichte Vergleichsharness.

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.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework.hyperlight import HyperlightCodeActProvider
from azure.identity import AzureCliCredential

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

# 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."
)
result = await agent.run(query)
print(result.text)

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

Der konzeptionelle Vergleich ist identisch mit jedem CodeAct-Back-End: Derselbe Client, dasselbe Modell, die Tools, die Eingabeaufforderung und das strukturierte Ausgabeschema können entweder über herkömmliche Toolaufrufe oder über Hyperlight-backed CodeAct verkabelt werden. Der einzige Unterschied ist die Tool-Oberfläche: direkte Tools gegenüber einem einzelnen execute_code Tool, das durch HyperlightCodeActProvider unterstützt wird:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework.hyperlight import HyperlightCodeActProvider

# Direct tool calling: the model picks one tool at a time per turn.
direct = Agent(
    client=FoundryChatClient(...),
    instructions="...",
    tools=[fetch_data, compute],
)

# Hyperlight-backed CodeAct: the model writes one program per turn that
# orchestrates the same tools through call_tool(...).
codeact = Agent(
    client=FoundryChatClient(...),
    instructions="...",
    context_providers=[
        HyperlightCodeActProvider(
            tools=[fetch_data, compute],
            approval_mode="never_require",
        ),
    ],
)

Bei Arbeitslasten, die Gesamtsummen in einem Datensatz berechnen, indem wiederholt Daten nachgeschlagen und leichte Berechnungen durchgeführt werden – viele kleine, aufeinander aufbauende Schritte –, kann CodeAct den Orchestrierungsaufwand reduzieren. Messen Sie beide Durchläufe mit einer Stoppuhr und prüfen Sie das zurückgegebene ChatResponse.usage, um die verstrichene Zeit und die Tokennutzung in Ihrer eigenen Umgebung zu vergleichen.

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.
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.