Metadata-Version: 2.4
Name: ant-ai
Version: 1.0.6
Summary: A lightweight Python framework for building multi-agent AI systems
Author: Cezar Sas, Vincenzo Giuffrida, Sandra Mitrovic, Matteo Salani
Author-email: Cezar Sas <cezar.sas@supsi.ch>, Vincenzo Giuffrida <vincenzo.giuffrida@supsi.ch>, Sandra Mitrovic <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.0.1
Requires-Dist: fastapi>=0.136.0
Requires-Dist: litellm>=1.83.10
Requires-Dist: loguru>=0.7.3
Requires-Dist: mcp>=1.27.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: starlette>=1.0.0
Requires-Dist: uvicorn>=0.44.0
Requires-Dist: langfuse>=4.3.1 ; extra == 'langfuse'
Requires-Dist: openai>=2.24.0 ; extra == 'openai'
Requires-Dist: graphviz>=0.20 ; extra == 'viz'
Requires-Python: >=3.14
Project-URL: Homepage, https://idea-idsia.github.io/ant-ai/
Project-URL: Documentation, https://idea-idsia.github.io/ant-ai/
Project-URL: Repository, https://github.com/idea-idsia/ant-ai
Provides-Extra: langfuse
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.github.io/ant-ai/)

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

</div>

---

`ant-ai` is a lightweight Python framework for building multi-agent systems: graph-based workflow orchestration, first-class agent-to-agent (A2A) communication via the [A2A protocol](https://github.com/a2aproject/A2A), MCP tool integration, lifecycle hooks for guardrails, and built-in observability — all on top of an LLM-agnostic core.

## 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 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

```python
from ant_ai.core import FinalAnswerEvent

async for event in agent.stream(state):
    if isinstance(event, FinalAnswerEvent):
        print(event.content)
```

### 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.

## 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"/> |
