freeact

<p align="center"> <img src="docs/images/banner.png" alt="freeact" width="100%"> </p> # freeact <p align="left"> <a href="https://gradion-ai.github.io/freeact/"><img alt="Website" src="https://img.shields.io/website?url=https%3A%2F%2Fgradion-ai.github.io%2Ffreeact%2F&up_message=online&down_message=offline&label=docs"></a> <a href="https://pypi.org/project/freeact/"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/freeact?color=blue"></a> <a href="https://github.com/gradion-ai/freeact/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/gradion-ai/freeact"></a> <a href="https://github.com/gradion-ai/freeact/actions"><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/gradion-ai/freeact/test.yml"></a> <a href="https://github.com/gradion-ai/freeact/blob/main/LICENSE"><img alt="GitHub License" src="https://img.shields.io/github/license/gradion-ai/freeact?color=blueviolet"></a> </p> General-purpose AI agent that acts via code actions through a unified execution interface. ## Overview Freeact is a lightweight, general-purpose agent that acts via code actions in a stateful execution environment provided by [ipybox](https://github.com/gradion-ai/ipybox). A unified execution interface allows code actions to contain any combination of Python code, shell commands, and programmatic MCP tool calls, generated in one LLM inference pass. For programmatic MCP tool calling ("code mode"), freeact generates typed Python APIs from MCP server schemas. The agent inspects generated APIs prior to execution and composes them within code actions based on available type information. Successful code actions can be saved as reusable tools, capturing agent experience as executable knowledge, optionally combined with agent skills. Freeact supports tool discovery via agentic and semantic search, loading only task-relevant tool information into the context window. It can enforce application-level approval of code actions, shell commands, and programmatic tool calls, originating from both main agents and subagents. Freeact runs locally on your computer and is available as a CLI tool and Python SDK. > [!NOTE] > **Supported models**: Freeact supports any model compatible with [Pydantic AI](https://ai.pydantic.dev/). See [Configure models](https://gradion-ai.github.io/freeact/guides/models/) for provider configuration and examples. ## Documentation - 📚 [Documentation](https://gradion-ai.github.io/freeact/) - 🚀 [Quickstart](https://gradion-ai.github.io/freeact/getting-started/quickstart/) - 🤖 [llms.txt](https://gradion-ai.github.io/freeact/llms.txt) - 🤖 [llms-full.txt](https://gradion-ai.github.io/freeact/llms-full.txt) ## Capabilities | Capability | Description | |---|---| | **Unified execution** | Freeact agents act by executing Python code, shell commands, and programmatic MCP tool calls. These can be combined within a code action, generated in a single inference pass. | | **Action approval** | Application-level approval of code actions, shell commands, and programmatic tool calls originating from both main agents and subagents. | | **MCP code mode** | Freeact calls MCP server tools programmatically¹⁾ via generated Python APIs. This enables composition of tool calls and intermediate result processing in code actions, reducing LLM roundtrips. | | **Local execution** | Freeact executes code and shell commands locally in an IPython kernel provided by [ipybox](https://github.com/gradion-ai/ipybox). Data, configuration, and generated tools live in local workspaces. | | **Sandbox mode** | IPython kernels optionally run in a sandbox environment based on Anthropic's [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime), enforcing filesystem and network restrictions at OS level. | | **Tool discovery** | Tools are discovered via category browsing or hybrid BM25/vector search. On-demand loading frees the context window and scales to larger tool libraries. | | **Subagent delegation** | Tasks can be delegated to subagents, each using their own execution environment. This enables specialization and parallelization without cluttering the main agent's context. | | **Agent skills** | [agentskills.io](https://agentskills.io/)-based skills add specialized knowledge and workflows, composing naturally with code actions and agent-authored tools. | | **Tool authoring** | Agents can create new tools, enhance existing tools, and save code actions as reusable tools. This captures agent experiences as executable knowledge. | | **Session persistence** | Freeact persists agent state incrementally. Persisted sessions can be resumed and serve as a record for debugging, evaluation, and improvement. | ## Usage | Component | Description | |---|---| | **[Agent SDK](https://gradion-ai.github.io/freeact/getting-started/sdk-tutorial/)** | Agent harness and Python API for building freeact applications. | | **[CLI tool](https://gradion-ai.github.io/freeact/getting-started/quickstart/)** | Terminal interface for interactive conversations with a freeact agent. | --- ¹⁾ Freeact also supports MCP server integration via JSON tool calling, but the recommended approach is programmatic tool calling.