Local (.NET)

Microsoft.Agents.AI.LocalCodeAct runs generated Python in a child process in the agent's environment. It provides the CodeAct provider pattern without requiring a Hyperlight guest runtime.

This integration uses the CodeAct pattern and relies on the host environment for isolation.

Warning

Local CodeAct is not a security sandbox. Run it only where an external container, virtual machine, or managed hosting environment provides process, filesystem, network, and credential isolation.

Install the package

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

The package requires an explicit Python executable path.

Configure the provider

Register host tools through LocalCodeActProviderOptions. Generated code can call only those tools through await call_tool(...). Apply execution limits to bound subprocess runtime and captured output.

// ── LocalCodeAct provider with sandbox-only host tools ───────────────────────

var codeActOptions = new LocalCodeActProviderOptions
{
    Tools =
    [
        AIFunctionFactory.Create(Compute, name: "compute"),
        AIFunctionFactory.Create(FetchData, name: "fetch_data"),
    ],
    ExecutionLimits = new ProcessExecutionLimits { TimeoutSeconds = 5 },
};

var codeAct = new LocalCodeActProvider(pythonExecutable, codeActOptions);

// ── Build the hosted agent ───────────────────────────────────────────────────

AIAgent agent = new AIProjectClient(new Uri(endpoint), credential)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-local-codeact",
        Description = "Hosted CodeAct agent with sandbox-only compute and fetch_data tools.",
        ChatOptions = new ChatOptions
        {
            ModelId = deploymentName,
            Instructions =
                """
                You are a helpful assistant. Keep your answers brief. Prefer orchestrating your work
                in a single `execute_code` block using `await call_tool(...)` over issuing many
                direct tool calls. The sandbox exposes `compute` and `fetch_data` via `call_tool`.
                """,
        },
        AIContextProviders = [codeAct],
    });

Defense-in-depth controls

Local CodeAct provides:

• AST validation with configurable allowed and blocked imports and built-ins.
• Direct Python subprocess execution without invoking a shell.
• Time, output, result, and captured-file size limits.
• Explicit host-tool registration.
• Read-only and read-write file mounts.
• Configurable working directory and subprocess environment.

These controls reduce risk but don't provide containment. Keep validation enabled, pass a restricted environment dictionary, expose narrow host tools, and run the process inside a strong external sandbox.

Choose a CodeAct runtime

Runtime	Choose it when
Hyperlight	You need an isolated sandbox with filesystem and network controls.
Local CodeAct	Your .NET agent already runs inside an externally sandboxed environment.
Monty	You need a cross-platform restricted interpreter for Python agents.

Next steps

Monty