III · Tool Use & EnvironmentEmerging★

Code-as-Action Agent

also known as CodeAct Agent, Code-Writing Agent, Python-Action ReAct, Executable Code Actions

Have the agent emit a code snippet as its action each step, executed in a constrained interpreter, instead of emitting JSON tool calls; tool composition becomes function nesting and control flow inside the snippet.

This pattern helps complete certain larger patterns —

  • specialisesReAct★★— Interleave a single thought, a single tool call, and a single observation per step so the agent reasons over fresh evidence.

Context

A team is building an agent whose steps frequently need to compose multiple tool results: fetch a list, filter it by some predicate, then call a second tool for each remaining item. The model is strong at writing short snippets of Python or JavaScript, and the deployment can host a sandboxed interpreter that the agent's actions can run in.

Problem

When the action channel is JSON tool calls, the agent has to unroll every composition across many turns. Expressing 'fetch orders, keep the ones over a threshold, then call refund on each' takes a turn for the fetch, a turn to inspect, then one turn per refund, with the whole intermediate list passing through the context window each time. Token cost balloons and the natural composability of a programming language (loops, conditionals, local variables) has to be faked through bespoke meta-tools or multi-turn glue.

Forces

  • Programming languages express composition (loops, conditionals, function nesting) natively.
  • JSON tool-call format flattens that composition into a sequence of turns.
  • Executing model-generated code is a real security surface.
  • Models trained on code emit composed actions more compactly than JSON ones.

Example

A data-analysis agent needs to fetch a list of orders, filter to those over a threshold, and call a second tool for each one. With JSON tool calls, it takes a turn per order plus glue. The team switches to Code-as-Action: each step the agent emits a small Python snippet that runs in a constrained interpreter, so the whole composition is one snippet — fetch, filter, loop, call. Tool composition becomes ordinary control flow, and the conversation collapses from twenty turns to one.

Diagram

Solution

Therefore:

Replace the JSON tool-call channel with a code-snippet channel. The agent emits a Python (or DSL) snippet; the host executes it in a sandboxed interpreter that pre-imports the available tools as functions and an allow-list of safe builtins/modules. Tool results are returned as Python values usable by subsequent code. The agent can compose tools inside one snippet (loops, conditionals, intermediate variables) and observe the printed output. Bracket every snippet with a sandbox that whitelists imports and prevents arbitrary IO.

What this pattern forbids. The agent may only execute Python operations against the explicitly allowlisted imports and tool functions; arbitrary import or system calls fail at the sandbox boundary.

The smaller patterns that complete this one —

  • usesCode Execution★★— Let the model emit code, run it in a sandbox, and treat the run as the answer instead of trusting the model to compute in its head.
  • usesSandbox Isolation★★— Run agent-emitted code or actions in a contained environment with restricted filesystem, network, and process privileges.

And the patterns that stand alongside it, or against it —

  • alternative-toTool Use★★— Let the LLM produce typed calls against an external toolkit instead of producing free-form text the surrounding system has to parse.
  • alternative-toParallel Tool Calls★★— Allow the model to emit several independent tool calls in one assistant turn; the host executes them in parallel.
  • complementsStructured Output★★— Constrain the model's output to conform to a JSON Schema (or similar typed shape).
  • composes-withMCP-as-Code-API★— Materialize MCP servers as a directory of typed code wrappers so the agent writes code that imports them and large tool outputs flow between calls inside the sandbox without ever entering the model's context window.
  • alternative-toJSON-Only Action Schema✕— Anti-pattern: restrict the agent's action language to JSON tool-call dictionaries even for tasks where code-as-action (functions composing, loops, conditionals over results) would be the natural shape.
  • complementsCode-Then-Execute with Dataflow Analysis★— Have the agent emit code in a sandbox DSL whose values are statically tagged trusted/tainted via dataflow analysis before execution, enabling per-value policy enforcement.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

Used in recipes

Used in frameworks

Show 21 more

References

Provenance