freeact

Overview

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.

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.

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", "[email protected]"],
            "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: