When to reach for it
- Calculations, data transformations, or complex tool calls must be precisely executable.
- The result should be reproducible.
- Multi-step logic composes more cleanly as one program than as a chain of separate tool calls.
CodeAct.
Think in code. Execute. Observe. Repeat.
The agent uses executable code rather than pure text as its primary medium for action and reasoning — it writes code, runs it in a sandbox, observes the typed result, and iterates, so a computation is executed rather than approximated in prose.
When it backfires
- Code execution cannot be safely isolated in a sandbox.
- The task is purely linguistic.
- The overhead of a code runtime outweighs a single direct tool call.
The tradeoff
Maximum precision and reproducibility oppose a high sandbox, security, and runtime overhead.
A loop you can draw on a napkin.
Think, emit code, execute in a sandbox, observe the typed result — and back to think. Code is the action.
Two ways this pattern will hurt you.
Sandbox escapes via file or network access
The emitted code reads sensitive files or opens outbound connections despite the sandbox.
Fix · Use a hardened sandbox with strict seccomp policies, no network, and a read-only filesystem.
The agent treats execution errors as success signals
A failed tool call returns stderr, but the agent interprets it as a valid observation and proceeds with corrupted state.
Fix · Always check exit codes. Treat non-zero exits as errors and route to an error-handling node.
Where CodeAct is native.
Microsoft Agent Frameworkcode executionNative