CodeAct Agent Framework

• CodeAct Agent Framework is a novel paradigm where LLMs interact by generating executable Python or pseudocode to integrate reasoning, planning, and acting.
• It employs modular roles such as Planner, ToolCaller, and Replanner to structure multi-step task decomposition and robust error-handling.
• Empirical benchmarks like VirtualHome, GAIA, and HotpotQA show significant token efficiency and performance gains compared to traditional methods.

A CodeAct Agent Framework is a class of agentic architectures in which LLMs interact with their environment via the generation and execution of structured code actions. Unlike traditional API- or JSON-based tool call schemes, CodeAct agents unify reasoning, planning, and acting into a code-centric paradigm, utilizing dynamic Python (or pseudocode) modules to mediate multi-agent workflows, impose typed control-flow, and enable efficient multi-step task decomposition. Such frameworks yield interpretable, modular, and token-efficient solutions, and have become central in leading systems for complex tool use, autonomous multi-agent reasoning, and dynamic action composition (Yang et al., 4 Jul 2025, Wang et al., 1 Feb 2024).

1. Fundamental Architecture and Action Space

The core design principle of a CodeAct Agent Framework is the abstraction of all agent-environment interactions as first-class code actions. In this model, the LLM emits executable Python (or strongly typed pseudocode) representing compound actions, reusable subroutines, and error-handling logic, as opposed to natural language directives or ad hoc JSON schemas.

A typical CodeAct agent formalizes its decision process over a state space $S$, representing the agent’s interaction history, environment observations, and tool availability. The action space at step $t$ is a set of valid code snippets $$A_t \subset \{\text{Python code over available tools}\}$$. Upon execution within a Python interpreter or a simulated pseudocode runtime, each action yields a structured observation or exception, which is looped back into the state history (Yang et al., 4 Jul 2025, Wang et al., 1 Feb 2024, Yuan et al., 13 Jan 2025).

In multi-agent systems, roles such as Planner, ToolCaller, and Replanner are implemented as specialized agents emitting codified plans and adapting to structured feedback. Each role is initialized with explicit system prompts—often specified in YAML or Python dict forms—and pursues its subroutine in modular pseudocode enriched with control structures (loops, assertions, Boolean branching) and typed variable annotations (Yang et al., 4 Jul 2025).

Table: Formal Definitions Extracted from CodeAct-style Frameworks

Component	Formal Definition or Example
Action	$$Action = Tool(arg_1: T_1,…, arg_k: T_k) \rightarrow Observation$$
Plan	$$Plan = def\, f(in_1: T_1,…, in_n: T_n) \rightarrow Seq[Action]$$
Feedback	$$(failed\_step: Action, error\_msg: String, env\_state: State)$$
Pseudocode	assert(cond: Bool) else: <subroutine>; while (cond): <stmt_list>

2. Codified Prompting Language and Modular Reasoning

CodeAct frameworks employ a syntax that is close to executable Python: function-style headers, comments as “thought” steps, explicit type annotations, and idioms for control flow and variable scoping. Each agent step may emit a block such as:

assert('close' to 'bread') else: find('bread') grab('bread')

This modular structure confers several advantages:

• Subroutines become independently verifiable units, with each action step and its precondition testable in isolation.
• Rich programmatic control flow—conditionals, loops, assertions—reduces the overhead needed to express complex plans or adapt to execution feedback.
• Inter-agent messages, when needed for multi-agent synchronization or external tool invocation, use JSON/pseudocode representations with explicit argument typing for interoperability (Yang et al., 4 Jul 2025).

This structured prompting language enables interpretable “chain of thought,” with comments serving as explanatory traces and code as the substrate of reasoning.

3. Token Efficiency: Quantification and Mechanisms

A defining feature of CodeAct frameworks is their token efficiency. Where traditional natural language prompting for multi-step reasoning and tool use incurs high token overhead (due to verbose English instructions, repeated context, and ambiguous referents), codified pseudocode yields compact representations and minimizes repeated boilerplate.

Empirical reductions in token usage, as measured on multi-agent benchmarks, are substantial:

$$\begin{align*} \text{Reduction}_{\text{input}} &= \frac{T_{\text{NL baseline}} - T_{\text{CodeAgents}}}{T_{\text{NL baseline}}} \times 100\% \ \text{Reduction}_{\text{output}} &= \frac{O_{\text{NL baseline}} - O_{\text{CodeAgents}}}{O_{\text{NL baseline}}} \times 100\% \end{align*}$$

With input token usage reduced by $55\text{–}87\%$ and output tokens by $41\text{–}70\%$ across VirtualHome, GAIA, and HotpotQA, these savings directly facilitate longer context windows, larger agent teams, and more scalable agentic systems (Yang et al., 4 Jul 2025).

4. Evaluation Benchmarks and Quantitative Results

The capabilities of CodeAct-based systems have been validated across a range of high-complexity benchmarks:

• VirtualHome (3D simulation, long-horizon, single-agent): CodeAgents achieve a new state-of-the-art success rate (SR) of $56\%$ ($0.56 \pm 0.11$), up from $36\%$ ($0.36 \pm 0.05$) for natural language baselines.
• GAIA (multi-agent, tool-augmented QA): Absolute accuracy gains of $10.7\%$ and input token usage reduced by $67.8\%$.
• HotpotQA (multi-hop QA): Accuracy increase of $6.1\%$ ($0.52$ vs $0.49$), with input reduction of $72.3\%$.

The following empirical table summarizes key results from (Yang et al., 4 Jul 2025):

Benchmark	Metric	NL Baseline	CodeAgents	Improvement
VirtualHome	SR	$0.36 \pm 0.05$	$\mathbf{0.56 \pm 0.11}$	$+20$ p.p.
GAIA	Accuracy	$0.56$	$0.62$	$+10.7\%$, tokens $\downarrow67.8\%$
HotpotQA	Accuracy	$0.49$	$0.52$	$+6.1\%$, tokens $\downarrow72.3\%$

Such results confirm the statistical and practical impact of codified action representations in continuous agent reasoning.

5. Agent Modularity, Extension, and Scalability

A hallmark of the CodeAct paradigm is rigorous modularity. Each agent role (Planner, ToolCaller, Replanner) is encapsulated as a typed subroutine, with well-specified input/output channels and explicit control flow. Patterns such as assertion checking, error-handling, and subplan generation are abstracted as reusable pseudocode blocks, promoting compositionality and rapid extension (e.g., by inserting new primitive tools or introducing additional agent roles).

Plans written in constrained pseudocode are amenable to static analysis, local error localization, and even offline execution/simulation. Empirical evidence indicates that the framework supports seamless scaling from single-agent, long-horizon plans (as in VirtualHome), to large multi-agent, tool-intensive domains (as in GAIA or HotpotQA) (Yang et al., 4 Jul 2025).

Token efficiency, enforceable program structure, and modularity work in concert to support larger environments, longer planning horizons, and richer agent teams while maintaining interpretability and verifiability.

6. Limitations, Comparisons, and Future Directions

While CodeAct agent frameworks advance the field, limitations remain:

• Plan generation and error-handling are only as robust as the control structures and typing constraints embedded in the pseudocode. Environments with highly dynamic or ambiguous semantics may require richer type systems or more advanced error recovery.
• The practical implementation of the “code as action” principle involves challenges in safe code execution, sandboxing, and robust feedback to the agent.
• Integration of new external tools requires their APIs to be accessible in the code domain, with argument typing and error reporting harmonized to the framework’s expectations.

Comparative analyses with systems such as AgentScope, PoAct, and CoAct-1 suggest that code-centric action, when combined with modular role assignment and reflection-driven plan repair, achieves substantial gains in reasoning accuracy and efficiency. Token-aware evaluation has emerged as a critical metric for real-world deployment (Gao et al., 22 Aug 2025, Yuan et al., 13 Jan 2025, Song et al., 5 Aug 2025).

Future directions include enhanced intent modeling, shared memory architectures for inter-agent communication, automated code reflection and self-repair, more expressive prompt languages (beyond Pythonic pseudocode), and formal verification of agent-generated plans.

7. Summary Table: Extracted Metrics for CodeAct Frameworks

Aspect	Value/Description
Input token reduction	$55\text{–}87\%$
Output token reduction	$41\text{–}70\%$
VirtualHome success rate	$0.56 \pm 0.11$ (CodeAgents), $0.36 \pm 0.05$ (NL baseline)
HotpotQA accuracy gain	$+6.1\%$ absolute
GAIA accuracy gain	$+10.7\%$ absolute
Modular roles	Planner, ToolCaller, Replanner, extensible subroutines
Code structure	Typed pseudocode modules with assertions, loops, branches
Example system prompt format	Python dict/YAML specifying agent role, tool registry, cycle structure

• "CodeAgents: A Token-Efficient Framework for Codified Multi-Agent Reasoning in LLMs" (Yang et al., 4 Jul 2025)
• "Executable Code Actions Elicit Better LLM Agents" (Wang et al., 1 Feb 2024)
• "PoAct: Policy and Action Dual-Control Agent for Generalized Applications" (Yuan et al., 13 Jan 2025)
• "AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications" (Gao et al., 22 Aug 2025)
• "CoAct-1: Computer-using Agents with Coding as Actions" (Song et al., 5 Aug 2025)