Modern AI agents often aren’t bottlenecked by model quality, they are bottlenecked by orchestration overhead. When an agent chains together many small tool calls, each step typically requires a new model turn, driving up latency and token usage.<\/p>\n
With CodeAct support in Agent Framework, agents can collapse those multi-step plans into a single executable code block, cutting end-to-end latency by ~50% and token usage by over 60% in representative workloads, without compromising on safety or isolation. CodeAct ships in the new In this post, we walk through a concrete, realistic scenario where CodeAct provides meaningful gains: an agent task that involves many small, chainable tool calls (fetching data, performing light computation, assembling a result). Traditionally, this forces the agent into a loop of model \u2192 tool \u2192 model \u2192 tool interactions. Using CodeAct, the agent instead expresses the full plan as a short Python program that runs once in a sandboxed environment. The tools remain the same, the model remains the same, only the wiring changes. Later, we quantitatively compare both approaches on the same task to show where the latency and token savings come from, and more importantly, when those savings are worth pursuing in your own agents.<\/p>\n Concretely, wiring CodeAct into an agent looks like this. All later snippets build on it, reusing the same imports and the Modern agents are increasingly limited not by model quality, but by how much tool-calling overhead they incur. An agent that needs to read a table, filter it, multiply a few values, and summarize the result will typically burn four or five tool-call round trips, one per step, each one a separate request to the model.<\/p>\n The CodeAct pattern<\/a> collapses that loop. Instead of asking the model to choose a tool, wait for the result, and choose the next tool, we give the model a single Agents that do a lot of tool calling (data wrangling, light computation, chained lookups, report generation) benefit most. A five-step plan that used to be five model turns becomes one The The recommended entry point is The minimal setup shown at the top of the post is the recommended shape: construct the provider with your tools, pass it to the agent via Hyperlight does provide isolation, but it isolates the model-generated<\/em> code, not your tools. The tools you write and register live in your application’s runtime, with whatever access your process has. The Python program the model writes inside That split is the point. Your tools stay deterministic, fully managed code that you reviewed and shipped, and they keep the access they need to do their job (files, network, credentials, internal APIs). The model-generated glue that decides which tools to call, in what order, and how to combine the results stays in the sandbox, where it cannot touch anything except what you explicitly allowed. If you do want the model itself to read a file or hit an HTTP endpoint directly from inside Agent Framework tools carry an With that in mind, the two registration sites differ like this:<\/p>\n This gives you a clean rule of thumb. If a tool is cheap, pure, and safe to chain (data lookups, computations, formatting helpers, read-only API calls), register it on the provider so the model can compose many calls into a single Building on the setup above, adding <\/p>\n The tool takes the same Because By default the sandbox has no access to the host. When a workload needs more, you opt in explicitly on the provider (or on the standalone tool), leaving the rest of the setup unchanged:<\/p>\n Mounted paths show up in the generated CodeAct instructions so the model knows where to read from and where to write artifacts. Allowed domains are enforced at the sandbox boundary, not by convention.<\/p>\n Hyperlight is a micro-VM runtime designed for very small, very fast, strongly isolated guests. Each The result is a local, protected, deterministic place to run the code your model writes: no container daemon, no remote code-interpreter service, no shared Python process with the host agent.<\/p>\n The trade-off CodeAct has historically had to make is safety. Running model-generated code against a host process, or even against a general-purpose container, is a real risk: long-lived shared state, broad filesystem and network reach, and a startup cost high enough that you would not spin up a fresh sandbox per call. Hyperlight removes that trade-off. Because every The repository contains a Both runs use the same agent-framework-hyperlight<\/code> (alpha) package, which runs the model-generated code in a fresh, locally isolated Hyperlight<\/a> micro-VM per call.<\/p>\nget_weather<\/code> tool defined here:<\/p>\nfrom agent_framework import Agent, tool\r\nfrom agent_framework_hyperlight import HyperlightCodeActProvider\r\n\r\n@tool\r\ndef get_weather(city: str) -> dict[str, float | str]:\r\n \"\"\"Return the current weather for a city.\"\"\"\r\n return {\"city\": city, \"temperature_c\": 21.5, \"conditions\": \"partly cloudy\"}\r\n\r\n\r\ncodeact = HyperlightCodeActProvider(\r\n tools=[get_weather],\r\n approval_mode=\"never_require\",\r\n)\r\n\r\nagent = Agent(\r\n client=client,\r\n name=\"CodeActAgent\",\r\n instructions=\"You are a helpful assistant.\",\r\n context_providers=[codeact],\r\n)\r\n\r\nresult = await agent.run(\r\n \"Get the weather for Seattle and Amsterdam and compare them.\"\r\n)\r\n<\/code><\/pre>\nWhy CodeAct<\/h2>\n
execute_code<\/code> tool and let it express the entire plan as a short Python program. Tools the agent would otherwise call directly are exposed inside the program as call_tool(...)<\/code>. The model writes the code once, the sandbox runs it, and the agent gets back a single consolidated result.<\/p>\nexecute_code<\/code> turn containing a short Python script that calls the same tools via call_tool(...)<\/code>. You save latency, you save tokens, and you keep the reasoning trace compact and auditable, because the full plan lives in a single code block instead of being scattered across several tool-call messages.<\/p>\nHow CodeAct works in Agent Framework<\/h2>\n
agent-framework-hyperlight<\/code> package ships two entry points (HyperlightCodeActProvider<\/code> and HyperlightExecuteCodeTool<\/code>) plus typed helpers for file mounts and network policy. The sections below walk through both wirings, explain how approvals interact with sandboxed code, and show how to grant the sandbox controlled access to the host filesystem and network.<\/p>\nThe provider, and the minimal setup<\/h3>\n
HyperlightCodeActProvider<\/code>, a ContextProvider<\/code> that:<\/p>\n\n
execute_code<\/code> tool on every agent run.<\/li>\ncall_tool(...)<\/code>.<\/li>\n<\/ul>\ncontext_providers=[...]<\/code>, and let it handle execute_code<\/code> registration and prompt injection for you.<\/p>\nHow a tool gets invoked<\/h3>\n
execute_code<\/code> runs inside the Hyperlight sandbox, with no host access except the file mounts and allowed domains you opted into. When that sandboxed program calls call_tool(\"name\", ...)<\/code>, Hyperlight bridges the call back out to your runtime, runs your tool there, and returns the result into the sandbox. call_tool(...)<\/code> is that bridge; it is not an in-sandbox reimplementation of your tool.<\/p>\nexecute_code<\/code>, you can grant that with file_mounts<\/code> and allowed_domains<\/code> on the provider, and only those resources become reachable from sandboxed code.<\/p>\nApprovals<\/h3>\n
approval_mode<\/code> that controls whether a call is auto-invoked or paused for a human-in-the-loop decision. The two modes are never_require<\/code> (the framework invokes the tool automatically) and always_require<\/code> (every call raises a function-approval request the agent host has to resolve before the tool runs). This is the primary knob for deciding how much autonomy a given tool gets.<\/p>\n\n
HyperlightCodeActProvider(tools=...)<\/code><\/strong> are not shown to the model as direct tools. The model only sees the single execute_code<\/code> tool, and it reaches your tools by writing a line of Python that calls call_tool(\"name\", ...)<\/code>. Approval, if any, applies to the execute_code<\/code> call as a whole, not to individual call_tool(...)<\/code> invocations within it. Right now, if the execute_code<\/code> tool or any of the tools passed to the provider require approval (regardless of whether they are invoked) the entire code block is gated behind a single approval prompt.<\/li>\nAgent(tools=...)<\/code><\/strong> are surfaced to the model as first-class tools. Each call is a separate tool message the model chooses explicitly, and each one honors its own approval_mode<\/code>.<\/li>\nHyperlightCodeActProvider(tools=...)<\/code> and Agent(tools=...)<\/code><\/strong> are surfaced to the model as first-class tools as well as being available inside the sandbox. The model can choose to call them directly as a first-class tool call, or indirectly via call_tool(...)<\/code> inside the sandbox. Approval applies according to how the model calls them: if called directly, the tool’s own approval_mode<\/code> applies; if called via call_tool(...)<\/code>, the execute_code<\/code> tool’s approval mode applies. This means that the same tool can have different approval modes depending on how the model chooses to invoke it. For instance, if another tool passed to the provider has approval_mode=\"always_require\"<\/code>, the model can choose to call it via call_tool(...)<\/code> inside the sandbox, in which case it will be gated by the provider’s approval mode, or it can call it directly as a first-class tool, in which case it might not be need approval. This also allows the model to decide per-step what the easiest way of calling that tool is, if it just needs the raw result of that tool and only that tool, then it can call it directly, if it needs to manipulate the result or combine it with others, then it can call it via call_tool(...)<\/code> inside the sandbox and do all the processing in one turn. approval_mode<\/code>.<\/li>\n<\/ul>\nexecute_code<\/code> turn. If a tool has side effects you want the user to gate individually (sending email, spending money, writing to production systems), keep it on the agent directly, typically with approval_mode=\"always_require\"<\/code>, so the model has to request each invocation as a first-class tool call. The same tool can also be passed to both; the model will then decide per-step whether to call it via call_tool(...)<\/code> inside execute_code<\/code> or as a first-class tool call.<\/p>\nsend_email<\/code> as a direct, approval-gated tool alongside the sandboxed get_weather<\/code> looks like this; everything else stays the same:<\/p>\n# ... same imports, tools, and provider as above ...\r\n\r\n@tool(approval_mode=\"always_require\")\r\ndef send_email(to: str, subject: str, body: str) -> str:\r\n \"\"\"Send an email. Requires approval on every call.\"\"\"\r\n ...\r\n\r\nagent = Agent(\r\n client=client,\r\n name=\"MixedToolsAgent\",\r\n instructions=\"You are a helpful assistant.\",\r\n context_providers=[codeact],\r\n tools=[send_email], # invoked directly by the model, approval-gated\r\n)\r\n<\/code><\/pre>\nThe standalone
HyperlightExecuteCodeTool<\/code><\/h3>\nHyperlightExecuteCodeTool<\/code> exposes the same sandbox plumbing as a standalone tool<\/code> you add to Agent(tools=...)<\/code> yourself, instead of letting the provider wire it in. Use it when you want full control over how execute_code<\/code> is presented, for example to label it, wrap it in middleware, or build the CodeAct instructions once and embed them in a static agent definition.<\/p>\ntools=...<\/code> list as the provider, and those tools are still reached from sandboxed code via call_tool(...)<\/code>. The key difference from the provider is that the provider injects CodeAct instructions into the system prompt for you on every run; with the standalone tool, you are responsible for putting those instructions in the agent’s instructions<\/code> yourself. Otherwise the model will see the execute_code<\/code> tool as a regular tool that can run python code, but without guidance on how to use it or which tools are available inside the sandbox. HyperlightExecuteCodeTool<\/code> exposes build_instructions(...)<\/code> as a helper that produces exactly that prompt fragment, derived from the tools and sandbox configuration you passed in:<\/p>\nfrom agent_framework_hyperlight import HyperlightExecuteCodeTool\r\n\r\nexecute_code = HyperlightExecuteCodeTool(\r\n tools=[get_weather],\r\n approval_mode=\"never_require\",\r\n)\r\n\r\nagent = Agent(\r\n client=client,\r\n name=\"StandaloneToolAgent\",\r\n instructions=(\r\n \"You are a helpful assistant.\\n\\n\"\r\n + execute_code.build_instructions()\r\n ),\r\n tools=[execute_code, send_email],\r\n)\r\n<\/code><\/pre>\nbuild_instructions()<\/code> runs once at construction time, this path skips the per-run provider lifecycle entirely, useful for fully static agent definitions where the tool set and sandbox configuration do not change between runs.<\/p>\nControlled filesystem and network access<\/h3>\n
# ... same imports and tools as above ...\r\n\r\ncodeact = HyperlightCodeActProvider(\r\n tools=[get_weather],\r\n approval_mode=\"never_require\",\r\n file_mounts=[\r\n \"\/host\/data\", # same path inside the sandbox\r\n (\"\/host\/models\", \"\/sandbox\/models\"), # host \u2192 sandbox mapping\r\n ],\r\n allowed_domains=[\r\n \"api.github.com\", # all methods\r\n (\"internal.api.example.com\", \"GET\"), # GET only\r\n ],\r\n)\r\n<\/code><\/pre>\nHyperlight: the sandbox under the hood<\/h2>\n
execute_code<\/code> call runs in a fresh guest with its own memory, no access to the host filesystem beyond what you explicitly mount, and no network access beyond the domains you allow. Guest startup is measured in milliseconds, so the isolation is essentially free at the granularity of a single tool call.<\/p>\nWhy Hyperlight<\/h3>\n
execute_code<\/code> call gets its own freshly created micro-VM, with only the mounts and domains you opted into, the sandbox is cheap enough to be disposable and strict enough to be the default. You keep the latency and token wins of CodeAct, and you do not pay for them in blast radius.<\/p>\nBenchmark: same task, same tools, different wiring<\/h2>\n
codeact_benchmark.py<\/code> sample<\/a> that compares the two wirings on a workload that is realistic for this style of agent: compute the grand total of every user’s orders, where the model has to look up users, look up each user’s orders, look up discount and tax rates, and call a single line-total computation tool for each order line. The dataset has eight users and a handful of orders each, so finishing the task takes dozens of tool calls.<\/p>\nFoundryChatClient<\/code>, the same model, the same five tools (list_users<\/code>, get_orders_for_user<\/code>, get_discount_rate<\/code>, get_tax_rate<\/code>, compute_line_total<\/code>), the same prompt, and the same structured output schema. The only difference is whether those tools are passed to Agent(tools=...)<\/code> directly or registered on a HyperlightCodeActProvider<\/code> behind a single execute_code<\/code> tool. On a recent run the sample reports:<\/p>\n