Introduction

freeact is a lightweight AI agent library that uses Python code for defining tool interfaces and executable code actions. This is in contrast to traditional approaches where tool interfaces and actions are defined in JSON.¹

A unified code-based approach enables freeact agents to reuse code actions from earlier steps as tools or skills in later steps. Agents can build upon their previous work and compose more complex code actions from simpler ones.²

A unified code-based approach for defining actions and skills.

Overview

freeact agents are LLM agents that:

• generate code actions in Python and execute them in a sandboxed environment
• can use any function or methods from any Python package as tool definition
• can store generated code actions as skills in long-term memory
• can reuse these skills as tools in other code actions and improve on them
• support invocation and composition of MCP tools in code actions

Supported models

freeact supports usage of any LLM from any provider as code action model via LiteLLM.

Sponsored by

Motivation

Most LLMs today excel at understanding and generating code. It is therefore a natural choice to provide agents with tool interfaces defined in Python, annotated with docstrings. These are often defined in modules that provide the interfaces or facades for larger packages, rather than implementation details that aren't relevant for tool usage.

A code-based approach enables freeact agents to go beyond simple function calling. For example, agents can instantiate classes and use their methods for stateful processing, or act on complex result types that not only encapsulate data but also provide result-specific behavior via methods.

Because tool definitions and code actions use the same programming language, tools can be natively composed. Another advantage is that code actions generated at one step can be reused as tools in later steps. This allows freeact agents to learn from past experiences and compose more complex actions from simpler ones. We use the term skills instead of tools throughout our documentation, to convey their greater generality.

---

1. Code actions can significantly outperform JSON-based approaches, showing up to 20% higher success rates as shown in the CodeAct paper. ↩

2. This approach became popular with the Voyager paper where it was applied to Minecraft playing agents. ↩