Hyperlight CodeAct

Hyperlight adalah backend yang saat ini didokumentasikan untuk CodeAct pada Agent Framework. Ini mengekspos alat execute_code yang didukung oleh runtime sandbox terisolasi dan dapat memanggil alat tuan rumah milik penyedia melalui call_tool(...).

Untuk gambaran umum tingkat pola, lihat CodeAct.

Mengapa Hyperlight CodeAct

Agen modern seringkali lebih dibatasi oleh overhead panggilan alat dibandingkan oleh model itu sendiri. Tugas yang membaca data, melakukan komputasi ringan, dan merakit hasil dapat dengan mudah berubah menjadi rantai model - alat ->> model -> interaksi alat, bahkan ketika setiap langkah individu sederhana.

CodeAct yang didukung hyperlight menciutkan perulangan itu. Model ini menulis satu program Python pendek, sandbox mengeksekusinya sekali, dan alat milik penyedia diakses dari dalam sandbox dengan call_tool(...). Dalam beban kerja yang banyak menggunakan alat secara representatif, perubahan itu dapat mengurangi latensi kira-kira setengahnya dan menurunkan penggunaan token lebih dari 60%, sambil menjaga eksekusi tetap terisolasi dan dapat diaudit.

Pasang paketnya 

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

Microsoft.Agents.AI.Hyperlight didistribusikan secara terpisah dari abstraksi inti, jadi Anda hanya menggunakan runtime sandbox saat diperlukan.

Important

Paket .NET masih dalam pratinjau. Proyek ini bergantung pada paket NuGet dari Hyperlight.HyperlightSandbox.Apihyperlight-dev/hyperlight-sandbox; sampai dependensi tersebut dipublikasikan ke nuget.org, proyek akan gagal melakukan restore. Pantau repositori sandbox upstream untuk memeriksa ketersediaannya.

Note

Hyperlight memerlukan virtualisasi perangkat keras pada host: KVM di Linux atau Windows Hypervisor Platform (WHP) pada Windows. Backend Wasm juga memerlukan modul guest Hyperlight Python — tetapkan HYPERLIGHT_PYTHON_GUEST_PATH ke jalur absolutnya sebelum menjalankannya.

Gunakan HyperlightCodeActProvider

HyperlightCodeActProvider adalah titik masuk yang direkomendasikan saat Anda ingin CodeAct ditambahkan secara otomatis untuk setiap eksekusi. Ini adalah AIContextProvider yang menyisipkan instruksi CodeAct dalam cakupan run serta alat execute_code, sekaligus menjaga agar alat milik penyedia tidak muncul pada permukaan alat agen secara langsung. Penyedia menerapkan snapshot/restore pada setiap eksekusi sehingga mesin tamu dimulai dari keadaan bersih yang sudah diketahui setiap kali dijalankan.

Gunakan factory HyperlightCodeActProviderOptions.CreateForWasm(modulePath) untuk menyasar guest Python berbasis Wasm yang digunakan dalam contoh; CreateForJavaScript() juga tersedia untuk backend JavaScript.

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?"));

Note

Hanya satu HyperlightCodeActProvider yang dapat dilampirkan ke agen tertentu. Penyedia menggunakan kunci status tetap sehingga ChatClientAgentvalidasi keunikan kunci status menolak pendaftaran duplikat. HyperlightCodeActProvider menerapkan IDisposable; gunakan deklarasi using agar sandbox yang mendasarinya dilepaskan saat agen tidak lagi diperlukan.

Alat, mount file, dan entri daftar izin outbound dapat disediakan sejak awal melalui HyperlightCodeActProviderOptions (Tools, FileMounts, AllowedDomains, HostInputDirectory) atau dikelola saat runtime melalui AddTools(...), RemoveTools(...), ClearTools(), AddFileMounts(...), AddAllowedDomains(...) milik penyedia, dan aksesor Get* yang sesuai.

Cara kerja persetujuan dan alat host

Alat Agent Framework membawa metadata persetujuan yang mengontrol apakah metadata tersebut dapat dipanggil secara otomatis atau harus dijeda untuk persetujuan pengguna. Dalam .NET, persetujuan bersifat opt-in dengan membungkus AIFunction di dalam ApprovalRequiredAIFunction.

Perbedaan utama antara mendaftarkan alat HyperlightCodeActProvider dan mendaftarkannya langsung pada agen adalah bagaimana alat dipanggil, bukan di mana fungsi pada akhirnya berjalan:

  • Alat yang terdaftar di HyperlightCodeActProviderOptions.Tools disembunyikan dari model sebagai alat langsung. Model mencapainya dengan menulis kode yang memanggil call_tool("name", ...) di dalam execute_code.
  • Alat yang terdaftar langsung pada agen (misalnya melalui AsAIAgent(tools: [...])) ditampilkan kepada model sebagai alat utama, dan setiap pemanggilan langsung mengikuti metadata persetujuan milik alat tersebut.

call_tool(...) adalah jembatan menuju panggilan balik host; ini bukan penerapan ulang di dalam kotak pasir alat tersebut. Itu berarti alat milik penyedia masih dijalankan dalam proses host, dengan sistem file, jaringan, dan kredensial apa pun yang dapat diakses oleh proses host itu sendiri.

Enum CodeActApprovalMode mengatur bagaimana alat execute_code itu sendiri disetujui:

  • CodeActApprovalMode.NeverRequire (default): persetujuan menyebar dari alat terdaftar. Jika ada alat dalam registri yang dibungkus dengan ApprovalRequiredAIFunction, execute_code juga memerlukan persetujuan; jika tidak, execute_code tidak memerlukan persetujuan.
  • CodeActApprovalMode.AlwaysRequire: execute_code selalu memerlukan persetujuan pengguna sebelum pemanggilan.

Sebagai aturan praktis:

  • Letakkan alat murah, deterministik, aman untuk digunakan dalam rantai pada penyedia sehingga model dapat menyusun banyak panggilan dalam satu putaran execute_code.
  • Bungkus operasi yang menimbulkan efek samping atau operasi sensitif dalam ApprovalRequiredAIFunction (dan pertimbangkan untuk tetap menjadikannya sebagai tool agen langsung) agar setiap pemanggilan tetap terlihat jelas dan dapat disetujui secara terpisah.

Sampel berikutnya mendaftarkan dua alat aman (fetch_docs, query_data) ditambah alat sensitif send_email yang dibungkus dalam ApprovalRequiredAIFunction. Karena setidaknya satu alat terdaftar memerlukan persetujuan, mode default NeverRequire menyebabkan execute_code dirinya sendiri memerlukan persetujuan setiap kali dipanggil.

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],
    });

Karena alat host berjalan di luar kotak pasir, FileMounts dan AllowedDomains membatasi kode dalam kotak pasir itu sendiri, bukan panggilan balik host di belakang call_tool(...). Saat Anda memerlukan akses terkontrol ke sumber daya sensitif, utamakan penggunaan alat host dengan akses terbatas daripada memperluas izin kotak pasir.

Gunakan HyperlightExecuteCodeFunction untuk kabel langsung

Saat Anda perlu menggabungkan execute_code dengan alat yang hanya mendukung akses langsung pada agen yang sama, atau konfigurasi sandbox bersifat tetap selama masa aktif agen, gunakan HyperlightExecuteCodeFunction, bukan penyedia. Ini adalah mandiri AIFunction yang menangkap satu rekam jepret dari opsi yang disediakan pada waktu konstruksi dan menggunakannya kembali untuk setiap pemanggilan.

Tidak seperti HyperlightCodeActProvider, fungsi mandiri tidak menyuntikkan panduan prompt secara otomatis, jadi Anda bertanggung jawab untuk menambahkan BuildInstructions(...) output ke instruksi agen sendiri. Gunakan toolsVisibleToModel: false ketika alat yang terdaftar hanya dapat diakses melalui call_tool(...), dan true ketika alat yang sama juga tersedia langsung bagi model.

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 juga mengimplementasikan IDisposable. Ketika konfigurasi memerlukan persetujuan (sesuai ApprovalMode atau karena alat yang dikonfigurasi itu sendiri dibungkus dalam ApprovalRequiredAIFunction), instance mengekspos proksi ApprovalRequiredAIFunction melalui AITool.GetService(...), yang digunakan oleh bagian lain dari framework untuk mendeteksi kebutuhan persetujuan.

Mengonfigurasi file dan akses keluar jaringan

Hyperlight dapat mengekspos pohon baca-saja /input ditambah area bisa-tulis /output untuk artefak yang dihasilkan.

  • Gunakan HostInputDirectory untuk membuat direktori host tersedia di bawah /input/.
  • Gunakan FileMounts untuk memetakan path host tertentu ke dalam sandbox melalui new FileMount(hostPath, mountPath).
  • Gunakan AllowedDomains untuk mengaktifkan akses keluar hanya untuk target atau metode tertentu melalui new AllowedDomain(target, methods).
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);

Koleksi FileMounts dan AllowedDomains yang sama, serta alat, juga dapat dimodifikasi saat runtime melalui AddFileMounts(...), RemoveFileMounts(...), AddAllowedDomains(...), dan RemoveAllowedDomains(...) pada HyperlightCodeActProvider.

Petunjuk hasil

Untuk menampilkan teks dari execute_code, akhiri kode tamu dengan print(...); Hyperlight tidak mengembalikan nilai ekspresi terakhir secara otomatis.

Ketika akses sistem file diaktifkan, tulis artefak yang lebih besar ke /output/<filename> sebagai gantinya. File yang dikembalikan dilampirkan ke hasil perangkat, sementara file di bawah /input tersedia untuk dibaca di dalam sandbox.

Keterbatasan saat ini

Paket ini masih dalam pratinjau, dan ada beberapa batasan yang perlu dipertimbangkan dalam perencanaan:

  1. Paket bergantung pada Hyperlight.HyperlightSandbox.Api, yang belum dipublikasikan di nuget.org. Sampai itu dirilis, restore proyek akan gagal.
  2. Dukungan platform sesuai dengan paket backend Hyperlight yang dipublikasikan: lingkungan Linux (KVM) dan Windows (WHP) yang didukung. Platform yang tidak didukung atau backend virtualisasi yang tidak tersedia akan gagal saat membuat sandbox.
  3. Backend Wasm saat ini menjalankan modul tamu Python yang ditentukan oleh HYPERLIGHT_PYTHON_GUEST_PATH. Backend JavaScript (CreateForJavaScript()) tersedia untuk kode tamu di JavaScript.
  4. Status penerjemah dalam memori tidak bertahan antara panggilan terpisah execute_code. Gunakan file yang di-mount dan artefak /output ketika data perlu dipertahankan di semua pemanggilan.
  5. Persetujuan berlaku untuk execute_code pemanggilan secara keseluruhan, bukan untuk setiap individu call_tool(...) di dalam blok kode yang sama.
  6. Deskripsi alat, anotasi parameter, dan bentuk pengembalian lebih penting di sini karena model menulis kode terhadap kontrak tersebut daripada memilih panggilan alat langsung yang terisolasi.
  7. Belum ada padanan .NET untuk contoh benchmark Python saat ini — lihat tab Python untuk harness perbandingan yang telah dipublikasikan.

Pasang paketnya 

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight dikirim secara terpisah dari agent-framework-core, sehingga Anda hanya mengambil runtime sandbox saat Anda membutuhkannya.

Note

Paket tergantung pada komponen kotak pasir Hyperlight. Jika backend belum diterbitkan untuk platform Anda saat ini, execute_code gagal saat mencoba membuat kotak pasir.

Gunakan HyperlightCodeActProvider

HyperlightCodeActProvider adalah titik masuk yang direkomendasikan saat Anda ingin CodeAct ditambahkan secara otomatis untuk setiap eksekusi. Ini menyuntikkan instruksi CodeAct run-scoped ditambah execute_code alat, sambil menjaga alat milik penyedia dari permukaan alat agen langsung.

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)

Alat yang terdaftar pada penyedia tersedia melalui call_tool(...) di dalam sandbox, tetapi tidak diekspos sebagai alat agen langsung. Penyedia juga mengekspos manajemen gaya CRUD untuk alat, pemasangan file, dan entri daftar izin keluar melalui metode seperti add_tools(...), , remove_tool(...)add_file_mounts(...), dan add_allowed_domains(...).

Cara kerja persetujuan dan alat host

Alat Agent Framework membawa approval_mode yang mengontrol apakah mereka dapat dipanggil secara otomatis atau harus jeda untuk persetujuan pengguna.

Perbedaan utama antara mendaftarkan alat HyperlightCodeActProvider dan mendaftarkannya secara langsung Agent(tools=...) adalah bagaimana alat dipanggil, bukan di mana fungsi Python pada akhirnya berjalan:

  • Alat yang terdaftar di HyperlightCodeActProvider(tools=...) disembunyikan dari model sebagai alat langsung. Model mencapainya dengan menulis kode yang memanggil call_tool("name", ...) di dalam execute_code.
  • Alat yang terdaftar di Agent(tools=...) muncul ke model sebagai alat kelas satu, dan setiap panggilan langsung menghormati alat itu sendiri approval_mode.

call_tool(...) adalah jembatan menuju panggilan balik host; ini bukan penerapan ulang di dalam kotak pasir alat tersebut. Itu berarti alat milik penyedia masih dijalankan dalam proses host, dengan sistem file, jaringan, dan kredensial apa pun yang dapat diakses oleh proses host itu sendiri.

Sebagai aturan praktis:

  • Letakkan alat murah, deterministik, aman untuk digunakan dalam rantai pada penyedia sehingga model dapat menyusun banyak panggilan dalam satu putaran execute_code.
  • Pertahankan operasi dengan efek samping atau yang memerlukan persetujuan sebagai alat langsung untuk agen, sering kali dengan approval_mode="always_require", sehingga setiap pemanggilan tetap terlihat dan dapat disetujui secara individual.

Karena alat host berjalan di luar kotak pasir, file_mounts dan allowed_domains membatasi kode dalam kotak pasir itu sendiri, bukan panggilan balik host di belakang call_tool(...). Saat Anda memerlukan akses terkontrol ke sumber daya sensitif, utamakan penggunaan alat host dengan akses terbatas daripada memperluas izin kotak pasir.

Note

Alat yang dipanggil melalui call_tool(...) mengembalikan nilai Python aslinya (dict, list, primitif, atau objek kustom) langsung ke tamu. Apa pun result_parser yang dikonfigurasi pada FunctionTool ditujukan untuk konsumen LLM dan tidak beroperasi di jalur sandbox — terapkan pemformatan dalam fungsi alat jika diperlukan oleh konsumen di sandbox.

Gunakan HyperlightExecuteCodeTool untuk kabel langsung

Saat Anda perlu mencampur execute_code dengan alat khusus langsung pada agen yang sama, gunakan HyperlightExecuteCodeTool alih-alih penyedia. Untuk konfigurasi tetap, Anda dapat membuat instruksi CodeAct sekali dan menyadap alat secara langsung:

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)

Pola ini berguna ketika permukaan CodeAct diperbaiki dan Anda tidak memerlukan siklus hidup penyedia pada setiap proses. Tidak seperti HyperlightCodeActProvider, alat mandiri tidak menyuntikkan panduan prompt secara otomatis, sehingga Anda bertanggung jawab untuk menambahkan output build_instructions(...) ke instruksi agen Anda sendiri.

Mengonfigurasi file dan akses keluar jaringan

Hyperlight dapat mengekspos pohon baca-saja /input ditambah area bisa-tulis /output untuk artefak yang dihasilkan.

  • Gunakan workspace_root untuk membuat ruang kerja tersedia di bawah /input/.
  • Gunakan file_mounts untuk memetakan jalur host tertentu ke dalam kotak pasir.
  • Gunakan allowed_domains untuk mengaktifkan akses keluar hanya untuk target atau metode tertentu.

file_mounts menerima string singkatan, pasangan eksplisit (host_path, mount_path), atau FileMount tuple bernama. allowed_domains menerima sebuah target string, pasangan eksplisit yang berlabel (target, method-or-methods), atau AllowedDomain tuple yang dinamai.

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

Petunjuk hasil

Untuk menampilkan teks dari execute_code, akhiri kode dengan print(...); Hyperlight tidak mengembalikan nilai ekspresi terakhir secara otomatis.

Ketika akses sistem file diaktifkan, tulis artefak yang lebih besar ke /output/<filename> sebagai gantinya. File yang dikembalikan dilampirkan ke hasil perangkat, sementara file di bawah /input tersedia untuk dibaca di dalam sandbox.

Membandingkan CodeAct dan pemanggilan alat langsung

Perbandingan konseptual sama dengan backend CodeAct apa pun: klien, model, alat, prompt, dan skema output terstruktur yang sama dapat dikabeli baik melalui panggilan alat tradisional atau melalui CodeAct yang didukung Hyperlight. Satu-satunya perbedaan adalah permukaan alat — alat langsung versus satu execute_code alat yang didukung oleh HyperlightCodeActProvider:

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

Untuk beban kerja yang menghitung total pada seluruh set data dengan berulang kali mengambil data dan melakukan perhitungan ringan — banyak langkah-langkah kecil yang dapat dirangkai — CodeAct dapat menghilangkan overhead orkestrasi. Ukur kedua eksekusi dengan stopwatch dan periksa ChatResponse.usage yang dikembalikan untuk membandingkan waktu yang dibutuhkan dan penggunaan token di lingkungan Anda sendiri.

Keterbatasan saat ini

Paket ini masih tahap alfa, dan beberapa batasan layak dipertimbangkan dalam perencanaan:

  1. Dukungan platform sesuai dengan paket backend Hyperlight yang telah diterbitkan. Hari ini berarti lingkungan Linux dan Windows yang didukung; platform yang tidak didukung akan mengalami kegagalan saat membuat sandbox.
  2. Integrasi saat ini menjalankan kode tamu Python.
  3. Status penerjemah dalam memori tidak bertahan antara panggilan terpisah execute_code. Gunakan file yang di-mount dan artefak /output ketika data perlu dipertahankan di semua pemanggilan.
  4. Persetujuan berlaku untuk execute_code pemanggilan secara keseluruhan, bukan untuk setiap individu call_tool(...) di dalam blok kode yang sama.
  5. Deskripsi alat, anotasi parameter, dan bentuk pengembalian lebih penting di sini karena model menulis kode terhadap kontrak tersebut daripada memilih panggilan alat langsung yang terisolasi.

Langkah berikutnya

Cakupan

Konten terkait

  • Last updated on