Metadata-Version: 2.4
Name: ant-ai
Version: 1.9.0
Summary: A lightweight Python framework for building multi-agent AI systems
Author: Cezar Sas, Vincenzo Giuffrida, Sandra Mitrović, Matteo Salani
Author-email: Cezar Sas <cezar.sas@supsi.ch>, Vincenzo Giuffrida <vincenzo.giuffrida@supsi.ch>, Sandra Mitrović <sandra.mitrovic@supsi.ch>, Matteo Salani <matteo.salani@supsi.ch>
License-Expression: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: a2a-sdk[sql,http-server,grpc,encryption,telemetry]>=1.1.2
Requires-Dist: fastapi>=0.141.1
Requires-Dist: litellm>=1.97.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: mcp>=2.0.0
Requires-Dist: pathspec>=1.1.1
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: starlette>=1.6.0
Requires-Dist: uvicorn>=0.52.3
Requires-Dist: datafog>=4.8.1 ; extra == 'all'
Requires-Dist: guardrails-ai>=0.11.0 ; extra == 'all'
Requires-Dist: tokenizers>=0.23.1 ; extra == 'all'
Requires-Dist: huggingface-hub>=1.27.0,<2.0 ; extra == 'all'
Requires-Dist: langfuse>=4.14.4 ; extra == 'all'
Requires-Dist: mem0ai>=2.0.18 ; extra == 'all'
Requires-Dist: openai>=2.54.0 ; extra == 'all'
Requires-Dist: graphviz>=0.21 ; extra == 'all'
Requires-Dist: datafog>=4.8.1 ; extra == 'datafog'
Requires-Dist: guardrails-ai>=0.11.0 ; extra == 'guardrails-ai'
Requires-Dist: tokenizers>=0.23.1 ; extra == 'guardrails-ai'
Requires-Dist: huggingface-hub>=1.27.0,<2.0 ; extra == 'guardrails-ai'
Requires-Dist: langfuse>=4.14.4 ; extra == 'langfuse'
Requires-Dist: mem0ai>=2.0.18 ; extra == 'mem0'
Requires-Dist: openai>=2.54.0 ; extra == 'openai'
Requires-Dist: graphviz>=0.21 ; extra == 'viz'
Requires-Python: >=3.14
Project-URL: Homepage, https://idea.idsia.ch/ant-ai/
Project-URL: Documentation, https://idea.idsia.ch/ant-ai/
Project-URL: Repository, https://github.com/idea-idsia/ant-ai
Provides-Extra: all
Provides-Extra: datafog
Provides-Extra: guardrails-ai
Provides-Extra: langfuse
Provides-Extra: mem0
Provides-Extra: openai
Provides-Extra: viz
Description-Content-Type: text/markdown

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/idea-idsia/ant-ai/main/docs/assets/ant_h_white.png">
  <img alt="ANT AI" src="https://raw.githubusercontent.com/idea-idsia/ant-ai/main/docs/assets/ant_h_dark.png" height="100">
</picture>

![Python](https://img.shields.io/badge/Python-3.14%2B-3776AB?logo=python&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green)
![PyPI - Version](https://img.shields.io/pypi/v/ant-ai?label=PyPI)
[![Coverage](https://img.shields.io/codecov/c/github/idea-idsia/ant-ai?label=Coverage&logo=codecov)](https://codecov.io/gh/idea-idsia/ant-ai)
[![Docs](https://img.shields.io/badge/Docs-mkdocs-526cfe?logo=materialformkdocs&logoColor=white)](https://idea.idsia.ch/ant-ai/)
[![DOI](https://zenodo.org/badge/1219140757.svg)](https://doi.org/10.5281/zenodo.21276625)

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

</div>

---

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

**Multi-agent by design.** Agents communicate and delegate via the [A2A protocol](https://github.com/a2aproject/A2A) — no custom glue code required.

**No lock-in.** Swap LLMs, tools, or observability backends without touching your agent logic.

**Structured, not scripted.** Model complex behavior as graphs — know exactly what runs, when, and why.

**Observable from day one.** Built-in tracing via [Langfuse](https://langfuse.com/) and lifecycle hooks for guardrails.

## Installation

Requires Python 3.14+. Install with [uv](https://docs.astral.sh/uv/):

```sh
uv add ant-ai
```

Or grab everything at once:

```sh
uv add "ant-ai[all]"
```

Need just a piece — OpenAI, Langfuse, mem0, guardrails, viz? See the [install guide](https://idea.idsia.ch/ant-ai/install/) for the full list of extras.

Or clone and sync for local development:

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

## Quickstart

### Single agent

```python
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}"


llm = LiteLLMChat(model="gpt-4o-mini")

agent = Agent(
    name="WeatherAgent",
    system_prompt="You are a helpful weather assistant.",
    llm=llm,
    tools=[get_weather],
)

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

### Streaming events

`agent.stream()` interleaves live `ContentDeltaEvent`s (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:

```python
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

```python
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
```

## Development

```sh
# Install dev dependencies and pre-commit hooks
uv sync --all-extras
uv run pre-commit install

# Run tests
uv run pytest

# Serve docs locally
uv run mkdocs serve
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributing guide, branching model, and review process.

## License

This software is licensed under the MIT license. See the [LICENSE](LICENSE) file for details.

## Citation

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

```bibtex
@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).<br><img src="https://ec.europa.eu/regional_policy/images/information-sources/logo-download-center/eu_funded_en.jpg" alt="Funded by the European Union" height="40"/> |
