Quickstart

This guide shows how to run a simple task using the freeact CLI tool and the Agent SDK.

CLI Tool

Freeact provides a CLI tool for running the agent in a terminal.

Starting Freeact

Create a workspace directory, set your API key, and start the agent:

mkdir my-workspace && cd my-workspace
echo "GEMINI_API_KEY=your-api-key" > .env
uvx freeact

See Installation for alternative setup options and sandbox mode prerequisites.

Using a different model

The current default model is google-gla:gemini-3-flash-preview. Freeact supports any model compatible with Pydantic AI. To switch providers or configure model settings, see Models.

Generating MCP Tool APIs

On first start, the CLI tool auto-generates Python APIs for configured MCP servers. For example, it creates .freeact/generated/mcptools/google/web_search.py for the web_search tool of the bundled google MCP server. With the generated Python API, the agent can import and call this tool programmatically.

Custom MCP servers

For calling the tools of your own MCP servers programmatically, add them to the ptc_servers section in .freeact/agent.json. Freeact auto-generates a Python API for them when the CLI tool starts.

Running a Task

With this setup and a question like

who is F1 world champion 2025?

the CLI tool should produce an end result similar to the following screenshot:

The screenshot shows:

• Progressive tool loading: The agent progressively loads tool information: lists categories, lists tools in the google category, then reads web_search.py to understand the generated interface.
• Programmatic tool calling: The agent writes Python code that imports the web_search tool from mcptools.google and calls it programmatically (PTC) with the user's query.

The code execution output shows the search result with source URLs. The agent response is a summary of it.

Approval Prompt

Freeact can prompt for approval before running code actions. Shell commands and programmatic tool calls within code actions are intercepted during execution and approved individually. The screenshot below shows the approval prompt for a programmatic tool call (PTC):

Code actions and tool calls can also be pre-approved. See Approval Prompt for prompt options and behavior.

Agent SDK

The CLI tool is built on the Agent SDK that you can use directly in your applications. The following minimal example shows how to run the same task programmatically, with code actions and tool calls auto-approved by the application:

import asyncio

from freeact.agent import (
    Agent,
    ApprovalRequest,
    CodeAction,
    CodeExecutionOutput,
    Response,
    ShellAction,
    Thoughts,
    ToolOutput,
)

from freeact.agent.config import Config

from freeact.tools.pytools.apigen import generate_mcp_sources



async def main() -> None:
    config = await Config.init()

    # Generate Python APIs for MCP servers in ptc_servers
    for server_name, params in config.ptc_servers.items():
        if not (config.generated_dir / "mcptools" / server_name).exists():
            await generate_mcp_sources({server_name: params}, config.generated_dir)

    async with Agent(config=config) as agent:
        prompt = "Who is the F1 world champion 2025?"

        async for event in agent.stream(prompt):
            match event:
                case ApprovalRequest(tool_call=CodeAction(code=code)) as request:
                    print(f"Code action:\n{code}")
                    request.approve(True)
                case ApprovalRequest(tool_call=ShellAction(command=cmd)) as request:
                    print(f"Shell command: {cmd}")
                    request.approve(True)
                case ApprovalRequest(tool_call=tool_call) as request:
                    print(f"Tool: {tool_call.tool_name}")
                    request.approve(True)
                case Thoughts(content=content):
                    print(f"Thinking: {content}")
                case CodeExecutionOutput(text=text):
                    print(f"Code execution output: {text}")
                case ToolOutput(content=content):
                    print(f"Tool call result: {content}")
                case Response(content=content):
                    print(content)


if __name__ == "__main__":
    asyncio.run(main())