actants

A Python framework for building LLM agents. Defaults to Ollama for local development; integrates OpenAI, Anthropic, Gemini, and every major OpenAI-compatible host (Groq, Mistral, xAI, DeepSeek, Together, Fireworks, OpenRouter, Cerebras, Perplexity) via opt-in extras. Includes MCP (Model Context Protocol) and A2A (Agent2Agent Protocol) clients and servers, an embeddings client, SQLite-based storage helpers, OpenTelemetry GenAI tracing, and a Click + Rich CLI scaffold.

Install

pip install actants

Optional extras:

pip install 'actants[openai,anthropic,mcp,a2a]'

For the default Ollama provider, also install Ollama, start it, and pull the default model:

ollama serve      # if it isn't already running
ollama pull llama3.2

llama3.2 is what LLM() asks for unless you say otherwise. To use a model you have already pulled, pass it explicitly — LLM(model="qwen2.5:7b") — or set ACTANTS_MODEL.

Quickstart

import asyncio
from actants import Agent, LLM


async def main():
    agent = Agent(llm=LLM())  # Ollama, llama3.2 by default
    result = await agent.run("Say hello.")
    print(result.content)


asyncio.run(main())

If the model isn't on your Ollama server, actants tells you which models are and what to run to fix it.

Tools

Register async functions as tools and pass them to an Agent:

from actants import Agent, LLM, ToolRegistry

tools = ToolRegistry()


async def add(a: int, b: int) -> int:
    return a + b


tools.register_function("add", "Add two integers", add)

agent = Agent(llm=LLM(model="llama3.2"), tools=tools)
result = await agent.run("What is 17 + 25?")

The JSON Schema the model sees is derived from add's type annotations, so every tool parameter must be annotated. Pass input_schema= explicitly for anything annotations cannot express.

The model decides when to call the tool; Agent dispatches it and feeds the result back through the tool-calling loop.

Streaming

Agent.stream() yields typed events:

from actants.agents import (
    AgentTextDelta,
    AgentToolCallStarted,
    AgentToolCallCompleted,
    AgentRunCompleted,
)

async for event in agent.stream("explain transformers in one paragraph"):
    match event:
        case AgentTextDelta(text=t):
            print(t, end="", flush=True)
        case AgentToolCallStarted(call=c):
            print(f"\n→ {c.name}({c.arguments})")
        case AgentToolCallCompleted(value=v):
            print(f"  ← {v}")
        case AgentRunCompleted():
            print()

Switching providers

from actants import Agent, LLM, LLMSettings

Agent(llm=LLM())  # Ollama (default)
Agent(llm=LLM(settings=LLMSettings(provider="openai", model="gpt-4o")))  # OPENAI_API_KEY
Agent(
    llm=LLM(settings=LLMSettings(provider="anthropic", model="claude-3-5-sonnet"))
)  # ANTHROPIC_API_KEY
Agent(
    llm=LLM(settings=LLMSettings(provider="groq", model="llama-3.3-70b-versatile"))
)  # GROQ_API_KEY
Agent(llm=LLM(provider="xai", model="grok-4"))  # XAI_API_KEY
Agent(llm=LLM(provider="deepseek", model="deepseek-chat"))  # DEEPSEEK_API_KEY

Cost tracking covers the models actants has verified prices for. A model with no published price in actants.cost.PRICING is reported as unknown, not as $0.00 — CostTracker.untracked_models lists them, so a total that is really a lower bound says so rather than looking like a free run.

Provider and model can also be set via ACTANTS_PROVIDER / ACTANTS_MODEL environment variables, or by passing a provider instance as the first positional argument to LLM. Since 0.5.3, the provider name alone also works: LLM(provider="openai", model="gpt-4o").

See Configuration for the full list of environment variables.

MCP

Expose an agent's tools over the Model Context Protocol:

from actants.mcp import serve

serve(agent)  # stdio
serve(agent, transport="streamable-http", port=8000)  # HTTP

Consume tools from one or more MCP servers:

from actants import Agent, LLM, ToolRegistry
from actants.mcp import MCPClient

async with MCPClient(
    {
        "git": {"command": "uvx", "args": ["mcp-server-git"]},
        "fs": {"command": "uvx", "args": ["mcp-server-filesystem", "/tmp"]},
    }
) as mcp:
    registry = ToolRegistry()
    for tool in mcp.tools():
        registry.register(tool)
    agent = Agent(llm=LLM(), tools=registry)

The config shape matches Claude Desktop's mcpServers. Requires the [mcp] extra and the official mcp Python SDK.

A2A

Run an agent as an A2A server:

from actants.a2a import serve

serve(agent, host="0.0.0.0", port=9000)
# /.well-known/agent-card.json + JSON-RPC at /

Call a remote A2A agent as a tool:

from actants import Agent, LLM, ToolRegistry
from actants.a2a import RemoteAgent

registry = ToolRegistry()
registry.register(RemoteAgent("https://example.com"))
agent = Agent(llm=LLM(), tools=registry)

The Agent Card is auto-generated from the agent's tool registry. Streaming uses Server-Sent Events. Requires the [a2a] extra and the official a2a-sdk Python package.

Tracing

actants emits OpenTelemetry GenAI semantic-convention spans (invoke_agent, chat, execute_tool, embeddings). Cost is recorded under actants.cost.usd because the OTel GenAI spec does not yet define a cost attribute. Spans are forwarded to whichever OTLP collector you configure; actants itself sends nothing.

Benchmark

Measured against LangChain 1.3.14, Pydantic AI 2.21.0, LlamaIndex 0.14.23, and the raw ollama client, on one machine (Apple M4 Pro, Python 3.13.5, Ollama 0.32.4, qwen2.5:7b). Framework overhead is isolated from model time with a recording proxy; latency is p50 over 7 samples with framework order shuffled between rounds.

actants has the smallest install and the lowest per-call overhead of the frameworks tested — statistically tied with hand-written raw HTTP — and loses on tool ergonomics: registering one tool took 20 lines against LangChain's 10, because 0.5.3 — the version measured — required a hand-written JSON Schema. Annotation-based schema inference ships in 1.0, so that row is now pessimistic; the table has not yet been re-run against 1.0 and still reports what was actually measured rather than what is expected.

Model time dominates all wall-clock differences; these overheads are ~5 ms on top of a ~150 ms model call. Single machine, small samples, no retrieval or concurrency measured.

Full methodology, caveats, per-task snippets, and reproduction commands: docs/BENCHMARK.md. Run it yourself with python benchmarks/run_benchmarks.py --runs 7.

Project layout

Agent           state, memory, hooks, streaming events
LLM             provider gateway, retry, fallback, cost, cache
Provider        Ollama, OpenAI, Anthropic, Gemini, Groq, Mistral

Opt-in modules: mcp, a2a, embeddings, storage, cli, tracing, observability, config, testing.

Stability

actants is 1.0. Within the 1.x series, code using only the public API — exactly what actants.__all__ exports — keeps working and keeps meaning the same thing. Names starting with _ are private. The mcp, a2a, and bench modules are provisional because the specs they track are still moving.

Deprecations get a DeprecationWarning plus at least two minor releases and six months before removal, which never happens outside a major version. Run python -W error::DeprecationWarning -m pytest against your suite to find out whether an upgrade affects you before it does.

Full policy — what semver covers here, what is explicitly not promised, and how it is enforced in CI: Stability policy.

The package emits no telemetry.

Links

• Issues: https://github.com/openintelligence-labs/actants/issues
• License: MIT
• Part of Open Intelligence Labs