Code-Action Agents in Python: One Program vs 37 Tool Calls

A code-action agent (the idea is often called CodeAct, or code as action) changes what the model's action is. A ReAct agent acts by calling one tool, reading the result, and deciding the next call. A code-action agent acts by writing a program: loops, filters and sums run as Python, and the tools are ordinary functions the program calls. One model turn can stand for dozens of tool calls.

In Promptise Foundry it's one argument on build_agent:

    agent = await build_agent(
        model="openai:gpt-5-mini",
        servers={"shop": StdioServerSpec(command=sys.executable, args=["shop_server.py"])},
        agent_pattern="code-action",  # starts a Docker sandbox for the program
    )

Promptise starts a Docker container for the program with no network, gives it a Python stub for each tool, and runs the real tools on your side when the program calls them. MCP results that are JSON arrive in the program as lists and dicts. The answer is the line the program prints after RESULT:.

The sandbox guide covers the container itself: what it blocks, how to set limits, and what happened when an agent was asked to break out. This guide is about the other half of the decision: does a program over your MCP tools beat a tool-calling loop, and where does it go wrong? If you're choosing between all the built-in patterns, the reasoning patterns guide runs code-action next to eight others.

• Python 3.10 or newer.

• Docker, installed and running. There's no fallback: without a working sandbox, build_agent raises RuntimeError instead of running model-written code on your machine. The first run pulls the python:3.11-slim image.

• Promptise Foundry 1.3.4 or newer with the sandbox extra, which adds the Docker SDK for Python.

• An API key for a model provider. The examples use openai:gpt-5-mini.

pip install "promptise[sandbox]>=1.3.4"
export OPENAI_API_KEY="sk-..."

A code-action agent earns its keep on gather-then-compute work, so the MCP server below makes the agent gather. list_orders returns 30 order IDs, get_order returns one order with its lines, and get_price returns one product's price. Any question about September revenue means one call per order, plus prices.

import random

from promptise.mcp.server import MCPServer

server = MCPServer("shop")

# Sample data: 30 September orders, generated the same way on every run.
PRICES = {"KB-101": 89, "MS-220": 35, "MN-270": 249, "HD-330": 119, "DK-410": 179, "CB-055": 13}
CUSTOMERS = ["Acme Corp", "Birchwood Ltd", "Cobalt Labs", "Dunmore Studio",
             "Elmfield Cafe", "Fjordline Design", "Granite Health", "Halcyon Books"]

rng = random.Random(2)
ORDERS = {}
for n in range(1, 31):
    order_id = f"SO-{9000 + n}"
    skus = rng.sample(list(PRICES), rng.randint(1, 3))
    ORDERS[order_id] = {
        "id": order_id,
        "customer": rng.choice(CUSTOMERS),
        "status": rng.choice(["shipped"] * 6 + ["refunded", "pending"]),
        "discount_pct": rng.choice([0, 0, 5, 10, 15]),
        "lines": [{"sku": sku, "qty": rng.randint(1, 12)} for sku in skus],
    }


@server.tool()
async def list_orders(month: str) -> list[str]:
    """List the IDs of the orders placed in a month, e.g. "2026-09".

    Args:
        month: The month as YYYY-MM.
    """
    return list(ORDERS) if month == "2026-09" else []


@server.tool()
async def get_order(order_id: str) -> dict:
    """Get one order as {id, customer, status, discount_pct, lines: [{sku, qty}]}.

    Args:
        order_id: An order ID from list_orders, e.g. "SO-9001".
    """
    order = ORDERS.get(order_id)
    if order is None:
        raise ValueError(f"No order {order_id}")
    return order


@server.tool()
async def get_price(sku: str) -> dict:
    """Get a product's unit price in USD as {sku, unit_price}.

    Args:
        sku: A product SKU from an order line, e.g. "KB-101".
    """
    if sku not in PRICES:
        raise ValueError(f"No product {sku}")
    return {"sku": sku, "unit_price": PRICES[sku]}


if __name__ == "__main__":
    server.run()

The first line of each docstring matters more than usual here. The code-action prompt shows the model each tool as a Python signature followed by that line, and nothing else, so the line names the fields the tool returns.

Three questions, from easy to fiddly: total net revenue of shipped orders, the customer who spent the most, and the product with the most units outside refunded orders. The revenue questions need prices and discounts; the units question doesn't. Computed straight from the data, these are the answers every agent has to reach:

"""The right answers, computed straight from the server's data."""
from collections import Counter, defaultdict

from shop_server import ORDERS, PRICES


def order_total(order):
    gross = sum(line["qty"] * PRICES[line["sku"]] for line in order["lines"])
    return gross * (100 - order["discount_pct"]) / 100


shipped = [o for o in ORDERS.values() if o["status"] == "shipped"]
print(f"orders: {len(ORDERS)}, shipped: {len(shipped)}")
print(f"net revenue, shipped: ${sum(order_total(o) for o in shipped):,.2f}")

by_customer = defaultdict(float)
for o in shipped:
    by_customer[o["customer"]] += order_total(o)
top = max(by_customer, key=by_customer.get)
print(f"top customer, shipped: {top} ${by_customer[top]:,.2f}")

units = Counter()
for o in ORDERS.values():
    if o["status"] != "refunded":
        for line in o["lines"]:
            units[line["sku"]] += line["qty"]
(sku, qty), (second, second_qty) = units.most_common(2)
print(f"most units, not refunded: {sku} {qty} (next: {second} {second_qty})")

orders: 30, shipped: 24
net revenue, shipped: $34,959.30
top customer, shipped: Elmfield Cafe $7,452.85
most units, not refunded: MN-270 105 (next: CB-055 74)

Start with what you'd get anyway. A small LangChain callback counts model calls and tokens for any pattern, because Promptise passes the run's config to every model call, including the one that writes the program:

from langchain_core.callbacks import BaseCallbackHandler


class Usage(BaseCallbackHandler):
    """Count model calls and tokens for one run."""

    def __init__(self):
        self.calls = self.input_tokens = self.output_tokens = 0

    def on_llm_end(self, response, **kwargs):
        self.calls += 1
        usage = response.generations[0][0].message.usage_metadata or {}
        self.input_tokens += usage.get("input_tokens", 0)
        self.output_tokens += usage.get("output_tokens", 0)

    def __str__(self):
        return f"{self.calls} model calls, {self.input_tokens:,} input + {self.output_tokens:,} output tokens"

import asyncio
import sys
import time

from promptise import build_agent
from promptise.config import StdioServerSpec

from usage import Usage

QUESTION = (
    "Which customer spent the most on shipped orders in September 2026, after discounts, "
    "and how much? An order's total is qty x unit price over its lines, minus its discount."
)


async def main():
    agent = await build_agent(
        model="openai:gpt-5-mini",
        servers={"shop": StdioServerSpec(command=sys.executable, args=["shop_server.py"])},
        agent_pattern="react",  # the default
    )
    try:
        usage = Usage()
        start = time.perf_counter()
        result = await agent.ainvoke(
            {"messages": [{"role": "user", "content": QUESTION}]},
            config={"callbacks": [usage]},
        )
        report = agent.last_report
        print(">>>", result["messages"][-1].content)
        print(f"tool calls: {report.tool_calls}, path: {' -> '.join(report.nodes_visited)}")
        print(f"usage: {usage}, {time.perf_counter() - start:.1f} s")
    finally:
        await agent.shutdown()


asyncio.run(main())

>>> Elmfield Cafe — $7,452.85 (total for shipped orders in September 2026, after discounts).
tool calls: 37, path: reason -> reason -> reason -> reason
usage: 4 model calls, 7,324 input + 3,689 output tokens, 40.7 s

Right answer, from 37 tool calls (the list, 30 orders and each of the six prices once) in four model calls: when the model asks for several tools in one turn, Promptise runs them in parallel. The arithmetic happened in the model's head and came out right, which it did in every ReAct run here.

code_action_agent.py is react_agent.py with agent_pattern="code-action" and two logging lines that print the program the model writes. Promptise logs it at DEBUG level:

# Print the program the model writes (Promptise logs it at DEBUG level).
logging.basicConfig(format="%(message)s")
logging.getLogger("promptise.engine.code_action").setLevel(logging.DEBUG)


async def main():
    agent = await build_agent(
        model="openai:gpt-5-mini",
        servers={"shop": StdioServerSpec(command=sys.executable, args=["shop_server.py"])},
        agent_pattern="code-action",  # starts a Docker sandbox for the program
    )

Here's a run with every default, trimmed to the lines that matter:

[promptise] Initializing sandbox environment...
[promptise] Sandbox ready for code-action (backend: docker)
code-action program:
…
def main():
    month = "2026-09"
    try:
        order_ids_raw = list_orders(month)
    except Exception as e:
        print("RESULT: Error calling list_orders: {}".format(e))
        return
    order_ids = _as_list(order_ids_raw)

    prices_cache = {}
    spent_by_customer = defaultdict(float)
    calls_made = 1  # counted list_orders

    for oid in order_ids:
…
            # get price from cache or call get_price
            if sku not in prices_cache:
                try:
                    price_raw = get_price(sku)
                except Exception:
                    # assume price 0 on failure
                    prices_cache[sku] = 0.0
                else:
                    calls_made += 1
                    price_obj = _ensure_parsed(price_raw)
                    unit_price = 0.0
                    if isinstance(price_obj, dict):
                        unit_price = _to_float(price_obj.get("unit_price"))
                    else:
                        # if price_raw is a plain number or string
                        unit_price = _to_float(price_obj)
                    prices_cache[sku] = unit_price
            unit_price = prices_cache.get(sku, 0.0)
            subtotal += qty * unit_price
…
        # safety: prevent too many calls (should be under 50)
        if calls_made >= 49:
            # stop fetching more orders to avoid exceeding budget
            break
…
code-action exit=0 stdout='RESULT: Elmfield Cafe spent $7,452.85\n' stderr=''
>>> Elmfield Cafe spent $7,452.85
usage: 1 model calls, 384 input + 2,108 output tokens, 39.6 s

One model call, about a quarter of ReAct's tokens, and the right answer. list_orders returned a real list, so the loop worked on the first try, and the program kept a price cache, so it made the same 37 calls ReAct did. The model still wrapped every call in try and wrote helpers for results that might be strings: it can't know the shape of the data until the program runs, so it writes defensively.

Look at the last block before the output. The prompt tells the model it may make at most 50 tool calls, so this program counts its own calls and stops fetching orders once it has made 49. With 30 orders that never triggers. Over 60 orders, the same program would stop partway through the list and print a partial total without any error. Keep that in mind for the section on the tool budget.

One run proves little. So each setup answered each of the three questions 5 times, with a fresh agent every run, and the answer was checked automatically for the right number (and name or SKU). Model calls and tokens come from the Usage callback, tool calls from the tool trace, times from the wall clock. The four setups ran interleaved, one question at a time: ReAct, code-action with defaults, code-action with max_tool_calls=150, and the same plus one instruction, "Let errors from the tool functions raise; never wrap them in try/except."

Tokens, tool calls and model calls are means per run; times are medians; cost is GPT-5 mini at $0.25 per million input and $2.00 per million output tokens. Errors are runs that ended in an exception instead of an answer. The 60 runs cost $0.35 together. The machine was running other work at the same time, which slows every number here, ReAct's included.

What the numbers say:

• Accuracy was a tie. ReAct was right 15 times in 15, and the three code-action setups 45 times in 45. On a dataset this size, GPT-5 mini doesn't make the arithmetic slips code-action is there to prevent. The sandbox guide shows the same model getting two of four totals wrong over 500 rows in one tool result, so the gap opens as the data grows.

• Code-action used about 3.6 times fewer tokens. ReAct averaged 9,770 tokens a run, code-action with defaults 2,683, because no tool result ever enters the model's context. Nearly all of code-action's tokens are output: about 2,304 to write the program, against 379 of input. Output tokens cost eight times as much, so the cost gap is smaller than the token gap: $0.0087 against $0.0047 a run, about 1.8 times.

• Wall time was about the same. The code-action model call took a median 21.2 s against 35.4 s for ReAct's model calls together, and the sandbox and the bridged calls added a median 8.4 s, for 32.0 s against ReAct's 35.5 s. The next section shows where those seconds go.

• Same tool calls. Every program fetched each price once, like ReAct: 35 calls on average, at most 37. A bigger budget changed nothing, because no program needed more than the default 50.

• The rule about errors changed nothing either. All 46 programs the three setups wrote caught exceptions somewhere, 16 of 16 in the setup told not to. Nothing failed here, so it didn't matter, but a caught error in a program is how a failing tool becomes a silent zero.

• One program in 46 needed a repair. It started with a stray line reading python and crashed with NameError; the error went back to the model and the second program was right. That's the repair loop working as intended.

The execution report counts bridged calls, so agent.last_report.tool_calls matched the tool trace in every run.

To separate the sandbox from the model, a helper script ran code-action with a scripted model, so no API call was made, on a tool that returns its input. Starting a sandbox session took 0.26 to 0.57 seconds, and starting, stopping and removing one 0.45 to 0.74. A program that made no tool calls took 0.7 to 0.8 seconds end to end; one that made 30 bridged calls took 5.5 to 6.4. That's about 0.17 seconds per bridged call on top of a fixed cost under a second.

Two things in the design explain it:

• Every program gets a new container. That's the safe choice, and a repair attempt pays for another one. build_agent also starts and removes one up front to check that Docker works, so building a code-action agent took a median 1.8 s here against 1.5 s for ReAct. Removing a container is fast: Promptise kills it instead of waiting for it to stop.

• Bridged calls are served one at a time. The program writes a request file and waits; a loop on your side polls the container for request files, runs the tool, and writes the response back, each step a command run inside the container. ReAct, by contrast, ran 30 get_order calls in parallel in one step. With 37 calls that's the median 8.4 s between the model's answer and the run's end in the table above.

So code-action trades model time for bridge time. It wins when the model would otherwise read a lot of results, and loses when a few quick tool calls would do. Measure on your own hardware and tools.

Code-action has three settings. Pass them to build_agent as code_action=, either a dict or a CodeActionConfig from promptise.engine; an unknown key raises, and so does code_action= with any other pattern:

The budget is per program: a repaired program starts with a fresh one, so a run makes at most (max_repairs + 1) × max_tool_calls calls. A call beyond it raises ToolBudgetExceeded inside the program, Promptise logs a warning, discards the program's output even if the program caught the error, and asks the model for a program that needs fewer calls. With no repair left, the run raises GraphExecutionError.

That's the design. To see it at work, limits_demo.py gives the agent a budget of 20 tool calls for the top-customer question, which needs 37, and two repairs:

import asyncio
import logging
import sys

from promptise import build_agent
from promptise.config import StdioServerSpec
from promptise.engine import CodeActionConfig, GraphExecutionError

QUESTION = (
    "Which customer spent the most on shipped orders in September 2026, after discounts, "
    "and how much? An order's total is qty x unit price over its lines, minus its discount."
)

logging.basicConfig(format="%(message)s")
logging.getLogger("promptise.engine.code_action").setLevel(logging.DEBUG)


async def main():
    agent = await build_agent(
        model="openai:gpt-5-mini",
        servers={"shop": StdioServerSpec(command=sys.executable, args=["shop_server.py"])},
        agent_pattern="code-action",
        code_action=CodeActionConfig(exec_timeout=60, max_repairs=2, max_tool_calls=20),
        trace_tools=True,  # print every tool call
    )
    try:
        result = await agent.ainvoke({"messages": [{"role": "user", "content": QUESTION}]})
        print(">>>", result["messages"][-1].content)
    except GraphExecutionError as exc:
        print("GraphExecutionError:", exc)
    finally:
        await agent.shutdown()


asyncio.run(main())

It ran 5 times. Here's the second run, trimmed:

[promptise] Initializing sandbox environment...
[promptise] Sandbox ready for code-action (backend: docker)
→ Invoking tool: list_orders with {'month': '2026-09'}
…
→ Invoking tool: get_order with {'order_id': 'SO-9019'}
✔ Tool result from get_order: {"id": "SO-9019", "customer": "Granite Health", "status": "shipped", "discount_pct": 10, "lines": [{"sku": "CB-055", "qty": 4}, {"sku": "KB-101", "qty": 2}, {"sku": "MN-270", "qty": 11}]}
code-action node 'reason': tool-call budget exhausted: this program already made 20 tool call(s) (max_tool_calls=20), so the call to 'get_order' was refused and every further call will be; the program's output will be di …
code-action program:
…
code-action exit=1 stdout='' stderr='Traceback (most recent call last):\n  File "/workspace/program.py", line 102, in <module>\n    o_raw = get_order(oid)\n            ^^^^^^^^^^^^^^\n  File "/workspace/promptise_tools.p …
…
code-action program:
…
from collections import defaultdict

MAX_CALLS = 20
_calls_made = 0

def safe_list_orders(month):
    global _calls_made
…
# Process orders sequentially; for each shipped order, only fetch prices if budget allows.
for oid in order_ids:
    # Before attempting get_order, ensure at least one call remains.
    if _calls_made + 1 > MAX_CALLS:
        break
…
code-action exit=0 stdout='RESULT: Elmfield Cafe spent $3640.00\n' stderr=''
>>> Elmfield Cafe spent $3640.00

The first program made 20 calls, the 21st was refused, the warning went to the log and the program crashed. So far, so loud. Then the repair prompt asked for a program that needs at most 20 calls. The model can't get 37 calls' worth of data in 20, so it wrote one that counts its calls and stops reading orders when the budget runs out. That program succeeded, and its total of the first orders became the answer: Elmfield Cafe, $3,640.00 instead of $7,452.85. No exception reached the caller.

All 5 runs ended the same way:

In 3 runs the first program hit the cap and the repair truncated; in 2 the first program, told the limit in its prompt, truncated on its own and never hit the cap at all. None raised. The right customer name in most of them makes it worse: it looks like an answer. This is a weakness in how Promptise 1.3.4 words the budget to the model, reported with a repro, and the fix on your side is simple:

• Size the budget well above what a correct program needs. Count the calls one honest pass over the data takes and leave room; the default of 50 fit these questions with 13 to spare.

• Watch the log. A tool-call budget exhausted warning on promptise.engine.code_action means a program hit the cap, even when the run answered. Send that logger to your monitoring. It stays silent when a program stops itself, as in two of the runs above.

• Check the answer where you can. A total that's too small, zero or None is a truncated program in disguise. A few lines of validation on the RESULT line catch what the program hid.

A crash is the easy failure: the program exits with an error, Promptise sends the last 800 characters of its error output back to the model with the program it wrote, and the model answers with a corrected program. In the 45 code-action runs above, one program needed that, and the repair worked.

The hard failure is a program that doesn't crash: it catches an error, skips a record or stops early, and prints a number. A ReAct agent shows its work in the transcript; a code-action agent shows you one line, and whether that line is right depends on code nobody reviewed. These runs show two ways in:

• Caught exceptions. Every program here wrapped tool calls in try, and an instruction against it didn't change that. If a tool fails for some records, those records count as zero.

• Self-imposed limits. Told the budget, programs counted their calls and stopped early: 3 of the 46 benchmark programs had such a guard (at 49, 50 or 150 calls), plus the one in Step 3. The data was small enough that none triggered.

Log the programs (one logging line, as in Step 3), read a sample, and validate the result. That's the price of the token savings.

The reasoning patterns guide runs code-action on a different kind of task, expense rules written as sentences, next to the other eight built-in patterns. Two neighbours are worth knowing too. agent_pattern="managed" keeps a ReAct loop but replaces the growing transcript with a deduplicated ledger of facts, and the context engineering guide measures that approach. And if what you want is a plan or a checking step rather than a program, the plan-and-execute guide builds and measures those.

These are true of Promptise Foundry 1.3.4. Plan around them:

• A budget that's too small gives wrong answers, not errors. The prompt states max_tool_calls, and models fit the data to it. See the section on the tool budget.

• The answer is one line. It's whatever the program prints after RESULT: (or its last line), with no prose around it. Ask for the format you want in the question, or pass the result to a second call.

• The model sees one line per tool. The prompt lists each tool as a signature plus the first line of its description. Parameter descriptions and return types never reach it, so it writes code for every shape a result might have.

• Bridged calls are sequential. About 0.17 s each here, plus under a second per program for the container. Hundreds of calls add up to a minute.

• The sandbox contains the code, not your tools. The program can call every tool the agent has, as often as the budget allows. Keep that tool set small and read-only where you can; the human-in-the-loop guide covers approvals for the rest. This guide didn't test approvals with code-action.

• Small N. 5 runs per question per setup, one model, one dataset of 30 orders, and a machine that was busy with other work. Treat the ratios as a direction and measure your own task.

What is a code-action agent?

An agent whose action is a program. Instead of calling tools one at a time, the model writes Python that calls them as functions and computes the answer, and the program runs in a sandbox. The approach is often called CodeAct after the 2024 paper Executable Code Actions Elicit Better LLM Agents.

Is code-action better than ReAct?

On these tasks it was as accurate, used about 3.6 times fewer tokens (about 1.8 times cheaper) and took about as long. It pays off when results are large and the computation is exact work; ReAct is the better default for short, conversational tasks, and when you can't predict how many tool calls a job takes.

Does a code-action agent need Docker?

In Promptise, yes. agent_pattern="code-action" turns on a Docker sandbox with no network, and if it can't start one, build_agent raises RuntimeError rather than running model-written code on your machine. The gVisor runtime is an option for stronger isolation.

Can a code-action agent call MCP tools?

Yes. Tools from servers= are bridged into the program like any other tool, and each call runs on your side through the normal MCP client. A result that is JSON arrives as a list or dict, other text as a string, and a tool error raises inside the program.

How do I stop a generated program from calling a tool too often?

Set max_tool_calls in code_action=. It counts every call each program makes, failed ones included, and a run makes at most (max_repairs + 1) × max_tool_calls. Size it above what a correct program needs: in these runs a budget below that produced a wrong answer every time instead of an error. Keep exec_timeout as a second limit on time.

• Code-Action: Agents that Write Programs: the pattern's reference, including the bridge, the tool-call budget and the security model.

• Sandbox: container settings, limits and the gVisor backend.

• AI Agent Reasoning Patterns in Python: all nine built-in patterns, code-action included, measured on three expense questions.

• Reasoning Patterns and Prebuilt Patterns: every built-in agent_pattern and how each is wired.

• AI Agent Code Execution Sandbox: the container, escape attempts and resource limits, with a CSV analysis agent.

• Plan-and-Execute Agents in Python: when you want structure around a tool loop instead of a program.

• Build a Production MCP Server in Python: design tools that return the structured data a program can use.

• Trace Every Tool Call: see what an agent did, call by call.