freeact

Overview

freeact is a lightweight AI agent library using Python as the common language to define executable actions and tool interfaces. This is in contrast to traditional approaches where actions and tools are described with JSON. A unified code-based approach enables freeact agents to reuse actions from earlier steps as tools or skills in later steps. This design allows agents to build on their previous work and compose more complex actions from simpler ones.

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

freeact agents are LLM agents that:

• generate code actions in Python instead of function calls in JSON
• act by executing these code actions in a sandboxed environment
• use tools described through code and docstrings rather than JSON
• can use any feature from any Python package as tool definitions
• can store code actions as reusable skills in long-term memory
• can use these skills as tools in 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.

Documentation

• freeact: https://gradion-ai.github.io/freeact/
• ipybox: https://gradion-ai.github.io/ipybox/

Quickstart

Place API keys for Anthropic and Gemini in a .env file:

# For Claude 3.7. Sonnet
ANTHROPIC_API_KEY=...

# For Gemini with search tool
GEMINI_API_KEY=...

Add MCP server data to an mcp.json file:

{
    "mcpServers": {
        "pubmed": {
            "command": "uvx",
            "args": ["--quiet", "pubmedmcp@0.1.3"],
            "env": {"UV_PYTHON": "3.12"}
        }
    }
}

Start an agent with uvx via the freeact CLI:

uvx freeact \
  --ipybox-tag=ghcr.io/gradion-ai/ipybox:basic \
  --model-name=anthropic/claude-3-7-sonnet-20250219 \
  --reasoning-effort=low \
  --skill-modules=freeact_skills.search.google.stream.api \
  --mcp-servers=mcp.json

Then have a conversation with the agent: