ant-ai 1.12.1

A lightweight Python framework for building tool-driven AI agents and multi-agent systems.

Documentation · Install · Quickstart · Architecture · Contributing

Agents that talk to each other, tools that just work, and a graph you can actually reason about — ant-ai is a lightweight Python framework for building multi-agent systems, from a single tool-using agent to a whole colony of them.

Why ANT AI

Installation

Requires Python 3.14+. Install with uv:

uv add ant-ai

Or grab everything at once:

uv add "ant-ai[all]"

Need just a piece — openai, langfuse, mem0, guardrails-ai, datafog, viz? See the install guide for the full list of extras.

Or clone and sync for local development:

git clone git@github.com:idea-idsia/ant-ai.git
cd ant-ai
uv sync --all-packages --all-groups --all-extras

Quickstart

Your first agent

An agent is an LLM, a system prompt, and a set of tools. Decorate a function with @tool and it becomes callable by the model:

from ant_ai import Agent, Message, State, tool
from ant_ai.llm.integrations import LiteLLMChat


@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"Sunny, 22°C in {city}"


agent = Agent(
    name="WeatherAgent",
    system_prompt="You are a helpful weather assistant.",
    llm=LiteLLMChat(model="gpt-4o-mini"),
    tools=[get_weather],
)

state = State(messages=[Message(role="user", content="What's the weather in Lugano?")])
print(agent.invoke(state))

Streaming

agent.stream() interleaves live ContentDeltaEvents (token by token) before the terminal event they build up to — match on it for live text, or ignore it and just take the final answer:

from ant_ai.core import ContentDeltaEvent, FinalAnswerEvent

async for event in agent.stream(state):
    if isinstance(event, ContentDeltaEvent):
        print(event.delta, end="", flush=True)
    elif isinstance(event, FinalAnswerEvent):
        print()

Structured output

Pass a Pydantic model as response_schema and the final answer comes back as JSON matching it:

from pydantic import BaseModel


class WeatherReport(BaseModel):
    city: str
    temperature: int
    condition: str


answer = agent.invoke(state, response_schema=WeatherReport)
# answer is a JSON string matching WeatherReport

A colony of agents

A Colony wires agents together over A2A: each one runs as its own ASGI service, and a collaboration edge makes one agent callable as a tool by another.

from ant_ai.a2a import Colony

colony = Colony()
colony.agent(
    "codegen", agent=codegen_agent, workflow=codegen_workflow, card=codegen_card
)
colony.agent(
    "testgen", agent=testgen_agent, workflow=testgen_workflow, card=testgen_card
)

colony.collab("codegen", "testgen")  # codegen can now call testgen as a tool

asgi_app = colony.asgi(agent_name="codegen", use_fastapi=True)

Serving an agent to your editor

ACPServer exposes an agent over the Agent Client Protocol, so it runs inside Zed, VSCode, or the Gemini CLI — no changes to the agent itself:

from ant_ai.acp import ACP_ALL_TOOLS, ACPServer

agent = Agent(..., tools=[*ACP_ALL_TOOLS])  # read files, run terminals, push plans

ACPServer(agent=agent, workflow=workflow).serve_stdio()

Documentation

Runnable scripts live in examples/ — an ACP agent for your editor, a stdio→WebSocket proxy, and an interactive ACP test client.

Development

# Install dev dependencies and pre-commit hooks
uv sync --all-packages --all-groups --all-extras
uv run pre-commit install

# Run the test suite (skipping tests that need vLLM or external services)
uv run pytest -m "not vllm and not external"

# Serve the docs locally
uv run mkdocs serve

See CONTRIBUTING.md for the full contributing guide, branching model, and review process.

License

This software is licensed under the MIT license. See the LICENSE file for details.

Citation

If you use ant-ai in your research, please cite it. See CITATION.cff for the machine-readable citation metadata, or use the BibTeX entry below.

@software{Sas_ant-ai_A_lightweight_2026,
author = {Sas, Cezar and Giuffrida, Vincenzo and Mitrović, Sandra and Salani, Matteo},
doi = {10.5281/zenodo.21276625},
license = {MIT},
month = jun,
title = {{ant-ai: A lightweight Python framework for building multi-agent AI systems}},
url = {https://github.com/idea-idsia/ant-ai},
year = {2026}
}

Funding

This project is supported by the following grants.

Acknowledgement
Funded by the Swiss State Secretariat for Education, Research and Innovation (SERI), Project number 24.00596.
Funded by the European Union under Grant Agreement No. 101189745 (HIVEMIND).