Code-as-Action Agents: When Python Beats JSON Tool Calling (CodeAct and smolagents)
JSON tool calls force an agent to take one step per round trip. Letting the model write Python collapses loops, branching and composition into a single action. Here is when that wins, how to run it safely, and when to stay with JSON.
Ask an agent: "Find the three largest invoices from last quarter, convert them to USD, and flag any over $10k." With classic JSON tool calling, that is a chain of round trips. List invoices, then one convert_currency call per invoice, then a comparison the model does in its head. Each step costs a full model call, re-sends the growing context, and gives the model another chance to drop a value or mis-copy a number.
A code-as-action agent does the same job in one step. The model writes a short Python snippet that calls your tools as functions, loops, filters and returns the result. Research such as CodeAct (Wang et al., 2024) reported higher success rates and fewer steps than JSON or text actions on multi-step tool tasks, and Hugging Face's smolagents library makes the pattern easy to try. Verify the exact numbers in the papers before quoting them, because they depend on the benchmark and the model.
This post covers why code actions work, a minimal runnable implementation, how to sandbox it, and when you should not use it.
Why JSON tool calling hits a ceiling
JSON tool calling gives the model one action per turn, described as a fixed schema. That design has three costs.
- No composition. The output of tool A has to travel through the model's context to become the input of tool B. The model re-types data it should only reference.
- No control flow. "Do this for every item" becomes N separate model calls, or a bespoke batch tool you have to write.
- Context bloat. Every intermediate result lands in the transcript, even if only one field matters.
Code collapses all three. Variables hold intermediate data outside the context window. for loops and if statements are native. Only what you print or return goes back to the model.
The core loop
The pattern is a small change to the standard agent loop:
- Show the model a list of Python function signatures (your tools) and docstrings.
- The model replies with a code block.
- You execute it in a sandbox, capture stdout and the final value, and append that as the observation.
- Repeat until the model calls a
final_answer(...)function.
A minimal implementation
This is deliberately small so you can see every moving part. It uses the Anthropic Python SDK; check the official docs for current model IDs and parameters.
import io, re, contextlib, anthropic
client = anthropic.Anthropic()
MODEL = "claude-sonnet-5-5" # confirm current model IDs in the docs
# --- your tools: plain Python functions with clear docstrings ---
def list_invoices(quarter: str) -> list[dict]:
"""Return invoices for a quarter like '2026-Q3'. Each has id, amount, currency."""
return [
{"id": "A1", "amount": 9200, "currency": "EUR"},
{"id": "A2", "amount": 15000, "currency": "USD"},
{"id": "A3", "amount": 8000, "currency": "GBP"},
]
def to_usd(amount: float, currency: str) -> float:
"""Convert an amount to USD."""
rates = {"USD": 1.0, "EUR": 1.08, "GBP": 1.27}
return round(amount * rates[currency], 2)
TOOLS = {"list_invoices": list_invoices, "to_usd": to_usd}
SYSTEM = """You solve tasks by writing Python inside ```python blocks.
Available functions:
- list_invoices(quarter: str) -> list[dict]: invoices with id, amount, currency
- to_usd(amount: float, currency: str) -> float
Rules: print() anything you need to see. When done, call final_answer(value).
Write one code block per turn."""
class Done(Exception):
def __init__(self, value): self.value = value
def final_answer(value): raise Done(value)
def run_code(code: str) -> str:
env = {**TOOLS, "final_answer": final_answer, "__builtins__": SAFE_BUILTINS}
buf = io.StringIO()
try:
with contextlib.redirect_stdout(buf):
exec(code, env) # NOT a real sandbox, see the next section
except Done as d:
return f"FINAL::{d.value}"
except Exception as e:
return f"Error: {type(e).__name__}: {e}\nstdout so far:\n{buf.getvalue()}"
return buf.getvalue() or "(no output)"
SAFE_BUILTINS = {k: __builtins__[k] if isinstance(__builtins__, dict) else getattr(__builtins__, k)
for k in ["print", "len", "range", "sum", "min", "max", "sorted",
"enumerate", "zip", "round", "list", "dict", "str", "int", "float"]}
def agent(task: str, max_steps: int = 6) -> str:
messages = [{"role": "user", "content": task}]
for _ in range(max_steps):
resp = client.messages.create(
model=MODEL, max_tokens=1000, system=SYSTEM, messages=messages
)
text = resp.content[0].text
messages.append({"role": "assistant", "content": text})
m = re.search(r"```python\n(.*?)```", text, re.S)
if not m:
return text
obs = run_code(m.group(1))
if obs.startswith("FINAL::"):
return obs[7:]
messages.append({"role": "user", "content": f"Observation:\n{obs}"})
return "Stopped: step budget exhausted"
print(agent("Flag invoices from 2026-Q3 over $10k USD after conversion."))
A typical run produces one snippet that lists invoices, converts each, filters, and calls final_answer. That is two model calls (generate, then maybe a correction) instead of five or more.
Notice the step budget and the error observation. When the code throws, the traceback goes back to the model, which usually fixes it on the next turn. That self-repair is a real advantage over JSON, where a malformed call often fails opaquely.
The same thing with smolagents
If you would rather not own the loop, smolagents ships a CodeAgent. The API has changed between releases, so treat this as a sketch and check the current docs:
from smolagents import CodeAgent, InferenceClientModel, tool
@tool
def to_usd(amount: float, currency: str) -> float:
"""Convert an amount to USD.
Args:
amount: The amount to convert.
currency: ISO currency code such as EUR.
"""
return amount * {"USD": 1.0, "EUR": 1.08}[currency]
agent = CodeAgent(tools=[to_usd], model=InferenceClientModel())
agent.run("Convert 9200 EUR to USD and say whether it exceeds 10000.")
The library handles prompt construction, parsing, and, importantly, offers executor options including a restricted local interpreter and remote sandboxes.
Sandboxing is not optional
The exec call above is a teaching device. Model-written code is untrusted input, and an agent that reads web pages or emails can be steered by prompt injection into writing hostile code. Restricting builtins is trivially bypassable in CPython.
Real options, from weakest to strongest isolation:
| Approach | Isolation | Latency | Notes |
|---|---|---|---|
| Restricted AST interpreter (smolagents local executor) | Low-medium | Very low | Allowlists imports and operations; fine for trusted-ish inputs, not a security boundary on its own |
| Subprocess with rlimits, no network | Medium | Low | Cheap; still shares your kernel and filesystem unless you add namespaces |
| Container (Docker, gVisor) | High | Hundreds of ms | Good default for self-hosting; mount nothing sensitive |
| MicroVM or hosted sandbox (Firecracker, E2B, Modal, Cloudflare Sandbox) | High | 100ms to seconds | Strongest option; also gives you per-run resource limits |
Whatever you pick, apply these controls: no outbound network unless a tool needs it, short wall-clock and memory limits, a read-only filesystem except a scratch directory, and tools as the only path to secrets. The sandbox calls your tool functions through an RPC boundary, so credentials never enter the sandbox. See our earlier post on sandboxing LLM-generated code for a deeper walkthrough.
JSON tool calling vs code actions
| Dimension | JSON tool calling | Code-as-action |
|---|---|---|
| Steps for multi-tool tasks | One per call | Often one for the whole chain |
| Loops and branching | Extra model calls or batch tools | Native |
| Token cost on data-heavy tasks | High, intermediates in context | Lower, intermediates stay in variables |
| Error recovery | Model sees a schema error | Model sees a full traceback |
| Security surface | Small, schema-validated | Large, needs a real sandbox |
| Auditability | Easy: each call is a structured log line | Harder: you log code, then reason about it |
| Permission gating per call | Straightforward | Needs wrapper functions that enforce policy |
| Weaker models | Often fine | Need to be decent at Python |
When to choose which
Choose code actions when tasks chain many tool calls, process lists, do arithmetic or filtering, or touch large intermediate data you do not want in context. Data analysis, spreadsheet-style workflows, and glue across several read-only APIs are the sweet spot.
Choose JSON tool calling when each action is high-stakes and needs a human approval gate (refunds, emails, deploys), when you must produce a strict audit trail, or when your model is weak at coding. A hybrid is common: code for read-only exploration, structured calls for side effects.
Common pitfalls
- Treating
execas a sandbox. It is not. Use real isolation before any untrusted content reaches the agent. - Tools with vague docstrings. The docstring is the whole API for the model. Include argument units, return shape, and failure modes.
- Letting write tools hide inside code. If a function sends email, put the approval check inside the function, not in the prompt. Code can call it in a loop.
- No step or output cap. Infinite loops and 50 MB
printcalls will burn your budget. Truncate observations and cap steps. - Printing everything. The point is to keep data out of context. Tell the model to print summaries, not full lists.
- Skipping evals. Compare both modes on your own task set. Success rate, steps, tokens and cost per task will tell you whether the switch pays off for your workload.
- Not logging the code. Persist every snippet with its observation. It is your trace, and your debugging tool when something goes wrong.
A rollout checklist
- Pick 20 to 50 real multi-step tasks and run them with your current JSON agent for a baseline.
- Wrap your tools as typed Python functions with strong docstrings.
- Stand up an isolated executor with no network, resource limits and a scratch directory.
- Move side-effecting tools behind wrapper functions that enforce approvals and rate limits.
- Re-run the task set; compare success, steps, tokens and latency.
- Ship behind a flag for read-only workflows first, and review the logged code for the first week.
Next steps
Start with one workflow that currently needs five or more sequential tool calls, and rebuild only that path as a code agent. Measure before widening. The pattern is powerful, but its value comes from disciplined sandboxing and evaluation rather than from the code itself.
If you want to build agents like this hands-on, with feedback from practitioners, take a look at the Joinloop AI engineering cohort.
Want to build this yourself?
Join a live cohort and go from reading about AI to shipping it, with practitioners who do it daily.