freeact 0.7.4

Freeact code action agent

freeact

[!NOTE] Next generation freeact

This is the next generation of freeact, a complete rewrite. Older versions are maintained on the 0.6.x branch and can be obtained with pip install freeact<0.7.

Freeact is a lightweight, general-purpose agent that acts via code actions rather than JSON tool calls¹⁾. It writes executable Python code that can call multiple tools programmatically, process intermediate results, and use loops and conditionals in a single pass, which would otherwise require many inference rounds with JSON tool calling.

Beyond executing tools, freeact can develop new tools from successful code actions, evolving its own tool library over time. Tools are defined via Python interfaces, progressively discovered and loaded from the agent's workspace²⁾ rather than consuming context upfront. All execution happens locally in a secure sandbox via ipybox and sandbox-runtime.

Supported models: Freeact supports models compatible with Pydantic AI, with gemini-3-flash-preview as the current default.

Documentation

• 📚 Documentation
• 🚀 Quickstart
• 🤖 llms.txt
• 🤖 llms-full.txt

Interfaces

Freeact provides a Python SDK for application integration, and a CLI tool for running the agent in a terminal.

Features

Freeact combines the following elements into a coherent system:

Feature	Description
Programmatic tool calling	Agents call tools programmatically within code actions rather than through JSON structures. Freeact generates typed Python APIs from MCP tool schemas to enable this. LLMs are heavily pretrained on Python code, making this more reliable than JSON tool calling.
Reusable code actions	Successful code actions can be saved as discoverable tools with clean interfaces where function signature, data models and docstrings are separated from implementation. Agents can then use these tools in later code actions, preserving behavior as executable tools. The result is tool libraries that evolve as agents work.
Agent skills	Freeact supports the agentskills.io specification, a lightweight format for extending agent capabilities with specialized knowledge and workflows. Freeact provides skills for saving code actions as tools, enhancing existing tools, and structured task planning.
Progressive loading	Tool and skill information is loaded in stages as needed, rather than consuming context upfront. For tools: category names, tool names, and API definitions load progressively as needed. For skills: metadata loads at startup; full instructions load when triggered.
Sandbox mode	Code actions execute locally in a stateful IPython kernel via ipybox. Sandbox mode restricts filesystem and network access for executed code (example). Stdio MCP servers can be sandboxed independently.
Unified approval	Code actions, programmatic tool calls, and JSON-based tool calls all require approval before proceeding. Unified approval ensures every action can be inspected and gated with a uniform interface regardless of how it originates.
Subagents	Agents can delegate subtasks to child agents that run with their own kernel and context. Parent and child share the same event stream and approval flow.
Python ecosystem	Agents can use any Python package available in the execution environment, from data processing with pandas to visualization with matplotlib to HTTP requests with httpx. Many capabilities like data transformation or scientific computing don't need to be wrapped as tools when agents can call libraries directly.

Beyond task execution

Most agents focus on either software development (coding agents) or on non-coding task execution using predefined tools, but not both. Freeact covers a wider range of this spectrum, from task execution to tool development. Its primary function is executing code actions with programmatic tool calling, guided by user instructions and custom skills.

Beyond task execution, freeact can save successful code actions as reusable tools or enhance existing tools, acting as a toolsmith in its workspace²⁾. For heavier tool engineering like refactoring or reducing tool overlap, freeact is complemented by coding agents like Claude Code, Gemini CLI, etc. Currently the toolsmith role is interactive, with autonomous tool library evolution planned for future versions.

---

¹⁾ Freeact also supports JSON-based tool calls on MCP servers, but mainly for internal operations.
²⁾ A workspace is an agent's working directory where it manages tools, skills, configuration and other resources.