What is Code-Action Agent?

An AI agent architecture where the LLM writes and executes Python (or another language) code as its primary action format, rather than choosing from a fixed list of tools via JSON function calls — popularized by Hugging Face's smolagents framework.

Definition

A code-action agent is one whose primary output format is executable code — typically Python — rather than structured tool-call JSON. When the agent decides to take an action, it writes a code block that performs the action: making HTTP requests, querying databases, transforming data, generating files, or composing several operations into a single block. The framework executes that code and feeds the output back to the agent, which iterates until the task is complete.

Research comparing code-action agents to tool-call agents has consistently shown the code-action paradigm outperforms equivalent tool-call setups on complex multi-step tasks. The reason is structural: code is a more expressive action language than a fixed set of tool calls. An agent can compose, transform, and reason over operations naturally — chaining multiple steps into a single action, using control flow, and handling edge cases — rather than being constrained to one tool call per step. Hugging Face's smolagents framework is the most prominent code-action implementation, and it powers ml-intern (Hugging Face's self-improving research agent released in April 2026).

Why It Matters

For agent designers, the code-action vs. tool-call choice is a fundamental architectural decision. Tool-call agents are easier to constrain (you decide the tool surface) and produce structured logs that are easier to audit. Code-action agents are more capable on complex tasks but require sandboxing for safety. The trade-off depends on your use case: regulated, high-stakes environments often prefer the predictability of tool calls; research, automation, and engineering workflows often benefit from the expressiveness of code actions.

Key Takeaways

Code-action agents output executable code as their primary action format
Often outperform equivalent JSON-tool-call agents on complex multi-step tasks
smolagents (Hugging Face) is the most prominent code-action framework
Requires execution sandboxing for safety — typically a Python sandbox or container
Best suited for engineering, research, and data-analysis workflows; less ideal for highly-constrained domains

How Ertas Helps

When fine-tuning models for use in code-action agent frameworks, Ertas Studio supports training data formats that include task descriptions paired with executed Python code traces and observed outputs. This produces a fine-tune that writes more reliable agent code in your specific domain — particularly valuable when paired with smolagents or similar frameworks for production deployment.