CodeAct 2026: When AI Agents Write Code Instead of Calling JSON Tools

Posted on: 5/14/2026 10:31:20 AM

In 2024, most AI Agents communicated with tools through a familiar format: JSON tool calls. Each step, the LLM emits a JSON block invoking exactly one function — clean, parseable, validatable. But by late 2025 and across 2026, a new wave is upending this pattern: CodeAct — agents write Python code directly (instead of JSON), execute it in a , and use the result for the next step. Hugging Face's Smolagents defaults to CodeAct. Manus AI's breakout in early 2026 also bet on "code as the universal action space". The original CodeAct paper by Wang et al. (ICML 2024) measured striking gains: +20% success rate, -30% steps. Why did such a seemingly small format change reshape the industry?

1. What is CodeAct — and how is it different from JSON tool calls?

CodeAct (short for Code as Action) is a paradigm where each "action" of an AI Agent is not a JSON object calling a single tool, but an executable code snippet (typically Python) — where tools are exposed as functions, and the LLM is free to compose them with variables, loops, and conditionals.

A concrete example. Suppose an agent must "find the 5 largest cities in Vietnam, get the population of each, then sum them up".

cities = search_cities(country="VN", limit=5)
populations = [get_population(city=c) for c in cities]
total = sum(populations)
print(f"Total: {total:,}")

2. A short history of CodeAct

3. CodeAct architecture in production

A standard CodeAct system has 5 components — notably, the is now mandatory, not optional.

graph TB
    subgraph User["User"]
        Q["Question / Task"]
    end
    subgraph Agent["Agent Loop"]
        LLM["LLM (planner + code writer)"]
        PARSE["Code Parser / Validator"]
    end
    subgraph Sandbox["Sandbox Runtime (CRITICAL)"]
        EXE["Python Interpreter (E2B / Pyodide / Docker / Modal)"]
        TOOL["Tools as Python functions"]
    end
    subgraph State["State Management"]
        VAR["Variables (persisted across turns)"]
        OUT["stdout / stderr"]
    end
    Q --> LLM
    LLM -->|"Code block"| PARSE
    PARSE -->|"AST validated"| EXE
    EXE <--> TOOL
    EXE --> VAR
    EXE --> OUT
    OUT -->|"Observation"| LLM
    VAR -.->|"Reuse next turn"| EXE

    classDef user fill:#e94560,stroke:#fff,color:#fff
    classDef agent fill:#16213e,stroke:#fff,color:#fff
    classDef  fill:#ff9800,stroke:#fff,color:#fff
    classDef state fill:#f8f9fa,stroke:#e94560,color:#2c3e50
    class Q user
    class LLM,PARSE agent
    class EXE,TOOL 
    class VAR,OUT state

5 components

1. LLM Planner + Coder: One model both plans and writes code. Must be Python-fluent (Claude Sonnet, GPT-4 class or above) — this is why CodeAct underperforms with sub-7B models.
2. Code Parser/Validator: Extracts code blocks from LLM output (usually inside ```python fences), AST-checks to block dangerous imports before sending to .
3. Sandbox Runtime: Mandatory. 2026 options: E2B (Firecracker microVM), Pyodide+Deno (WebAssembly), Modal, Docker, Daytona, Azure Container Apps Dynamic Sessions.
4. Tools as Functions: Tools are not JSON schemas but Python functions pre-imported into the namespace. The LLM can inspect docstring/signature.
5. State Persistence: Variables must persist across turns (no reset each time). Sandboxes need to be stateful — this is where pure Pyodide is harder than microVMs.

4. Comparing CodeAct vs JSON Tool Call

5. Walkthrough — Building a CodeAgent with Smolagents

Smolagents is the cleanest CodeAct implementation. The code below builds an agent that writes its own Python to complete tasks.

from smolagents import CodeAgent, LiteLLMModel, tool

@tool
def search_cities(country: str, limit: int = 5) -> list[str]:
    """Find the largest cities in a country.
    Args:
        country: ISO country code (VN, US, ...)
        limit: Number of cities to return
    """
    # Mocked — production would call a real API
    return ["Ho Chi Minh", "Hanoi", "Da Nang", "Hai Phong", "Can Tho"][:limit]

@tool
def get_population(city: str) -> int:
    """Return the population of a city."""
    data = {"Ho Chi Minh": 9300000, "Hanoi": 8500000,
            "Da Nang": 1230000, "Hai Phong": 2050000, "Can Tho": 1240000}
    return data.get(city, 0)

model = LiteLLMModel(model_id="anthropic/claude-sonnet-4-6")

agent = CodeAgent(
    tools=[search_cities, get_population],
    model=model,
    executor_type="e2b",   # : e2b | docker | local
    additional_authorized_imports=["statistics"],
    max_steps=5,
)

result = agent.run("What's the total population of the 5 largest cities in Vietnam? Include standard deviation.")
print(result)

At runtime, the agent will produce code similar to:

cities = search_cities(country="VN", limit=5)
populations = [get_population(city=c) for c in cities]

import statistics
total = sum(populations)
stdev = statistics.stdev(populations)
print(f"Total: {total:,}")
print(f"StDev: {stdev:,.0f}")

A single LLM call accomplishes finding the cities, fetching populations, summing the total, and computing statistics — something a JSON tool call would need 7-8 round trips for.

6. Security — The is non-negotiable

CodeAct is only safe if the is solid. Letting LLM-generated code run on the main process means a mild prompt injection could os.system("rm -rf /"). Comparison of popular 2026 runtimes:

7. Observation Loop and cross-turn state

The subtlest part of CodeAct is the multi-turn loop. After each turn, the agent must "see" three things: (1) the code that ran, (2) stdout/stderr, (3) variables still alive in the namespace.

sequenceDiagram
    participant U as User
    participant A as Agent (LLM)
    participant S as Sandbox
    U->>A: "Analyze this week's error logs"
    A->>S: code: logs = fetch_logs(days=7)
    S-->>A: stdout: "(fetched 12,450 records)" + var: logs
    Note over A: LLM sees var logs is ready
    A->>S: code: errors = [l for l in logs if l.level=="ERROR"]
top = Counter(e.module for e in errors).most_common(5)
print(top)
    S-->>A: stdout: [("payment", 234), ("auth", 189), ...]
    A->>U: "The payment module errors most (234 times)..."

This is a major difference from JSON tool calls: in the old pattern, every observation must be stuffed into the next turn's prompt context. With CodeAct, large observations (12,450 log records) stay in memory, the LLM only references the variable name — saving enormous amounts of token budget.

8. 6 common mistakes when deploying CodeAct

9. CodeAct in multi-agent systems

When scaling to multiple agents, CodeAct unlocks an interesting pattern: the orchestrator agent calls sub-agents like functions. Smolagents has the concept of managed_agents — sub-agents are wrapped as callables in the parent's namespace.

from smolagents import CodeAgent

researcher = CodeAgent(tools=[web_search, scrape], model=model, name="researcher",
                       description="Search and read web content")
analyst = CodeAgent(tools=[run_sql, plot_chart], model=model, name="analyst",
                    description="Analyze data and produce charts")

orchestrator = CodeAgent(
    tools=[],
    model=model,
    managed_agents=[researcher, analyst],
    max_steps=10,
)

orchestrator.run("Find OpenAI's 3 main competitors in 2026, get their revenue, plot a comparison chart")

The orchestrator might write code like:

competitors_text = researcher(query="3 main competitors of OpenAI in 2026 and their revenue")
chart_url = analyst(query=f"Plot a bar chart from this data: {competitors_text}")
print(chart_url)

This is the purest expression of "agents as functions" — no complex message bus, no pub/sub, just Python function calls inside a .

10. Future — Is code really the "universal action space"?

Apple ML Research (2026) calls CodeAct "the most expressive action format we have today". But open questions remain:

One thing is clear in 2026: the new generation of agent frameworks all natively support code execution (Smolagents, OpenHands, Manus, Letta), while older frameworks (LangChain, AutoGen) are scrambling to add code-mode to keep up. If you're building a new agent system today, CodeAct deserves serious consideration as the default — provided you invest properly in your .

11. Conclusion

CodeAct isn't "magic" — it's simply using the right tool for the right job. JSON is good for RPC; code is good for composition. As agents take on increasingly complex tasks (data analysis, multi-step reasoning, orchestration), JSON tool calls reveal limits in round-trip count and composition ability. CodeAct gives the LLM back a language designed for computers to understand — code.

The price you pay is complexity. Don't deploy CodeAct without a clear isolation strategy. E2B, Modal, Daytona, Azure Container Apps Dynamic Sessions — pick one and invest seriously. The reward is smarter, faster, cheaper agents (fewer LLM calls) — and most importantly: agents that fix mid-flight errors themselves instead of looping back to ask you.

References

• Wang, X. et al. — Executable Code Actions Elicit Better LLM Agents (ICML 2024)
• Apple Machine Learning Research — CodeAct: Your LLM Agent Acts Better when Generating Code
• Hugging Face — Introducing smolagents: simple agents that write actions in code
• Hugging Face Docs — smolagents documentation
• Hugging Face Agents Course — Writing actions as code snippets or JSON blobs
• GitHub — xingyaoww/code-act — official repo
• GitHub — huggingface/smolagents