Metadata-Version: 2.3
Name: openmas
Version: 0.1.5
Summary: OpenMAS: Easily Build Smart Multi-Agent Systems
License: MIT
Keywords: multi-agent-systems,mas,agent,ai,mcp,model-context-protocol,framework
Author: Wilson Urdaneta
Author-email: wilson.urdaneta@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: all
Provides-Extra: grpc
Provides-Extra: mcp
Provides-Extra: mqtt
Requires-Dist: aiohttp (>=3.11.18,<4.0.0)
Requires-Dist: fastapi (>=0.115.12,<0.116.0)
Requires-Dist: grpcio (>=1.71.0,<2.0.0) ; extra == "grpc" or extra == "all"
Requires-Dist: grpcio-tools (>=1.71.0,<2.0.0) ; extra == "grpc" or extra == "all"
Requires-Dist: httpx (>=0.25.0)
Requires-Dist: httpx-sse (>=0.4.0,<0.5.0)
Requires-Dist: mcp (>=1.7.1) ; extra == "mcp" or extra == "all"
Requires-Dist: paho-mqtt (>=1.6.1,<2.0.0) ; extra == "mqtt" or extra == "all"
Requires-Dist: protobuf (>=5.26.1,<6.0.0) ; extra == "grpc" or extra == "all"
Requires-Dist: pydantic (>=2.5.0,<3.0.0)
Requires-Dist: python-chess (>=1.999,<2.0)
Requires-Dist: python-dotenv (>=1.1.0,<2.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: structlog (>=23.2.0,<24.0.0)
Requires-Dist: typer (>=0.15.2,<0.16.0)
Requires-Dist: uvicorn (>=0.34.2,<0.35.0)
Project-URL: Documentation, https://docs.openmas.ai
Project-URL: Homepage, https://openmas.ai
Project-URL: Repository, https://github.com/openmas-ai/openmas
Description-Content-Type: text/markdown

# OpenMAS

[![PyPI version](https://img.shields.io/pypi/v/openmas.svg)](https://pypi.org/project/openmas/)
[![Python Version](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![CI/CD](https://github.com/openmas-ai/openmas/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/openmas-ai/openmas/actions)
[![codecov](https://codecov.io/gh/openmas-ai/openmas/graph/badge.svg)](https://codecov.io/gh/openmas-ai/openmas)

**Easily Build Smart Multi-Agent Systems**

**OpenMAS** streamlines asynchronous Multi-Agent System (MAS) development in Python. By providing a lightweight **framework**, standardized structure, and helpful CLI tools, it handles the foundational setup, freeing you to concentrate on what matters most: designing and implementing sophisticated agent behaviors.

Inspired by modern development ecosystems and driven by real-world use cases like coding and gaming agents, OpenMAS aims to streamline the entire MAS lifecycle, with particular attention to integrating communication protocols like the **Model Context Protocol (MCP)** alongside standard web protocols.

**Full Documentation:** [**https://docs.openmas.ai**](https://docs.openmas.ai)

## Key Features

* **Simplified Agent Development:** Build agents inheriting from `BaseAgent` with a clear asynchronous lifecycle (`setup`, `run`, `shutdown`).
* **Flexible Communication:** Pluggable communicators for HTTP, Model Context Protocol (SSE & Stdio), gRPC, MQTT, with **lazy loading** to keep dependencies minimal. Easily extend with custom communicators. See [Communication](https://docs.openmas.ai/guides/communication).
* **Structured Projects:** Standardized directory layout (`agents/`, `shared/`, `extensions/`, `packages/`) generated by `openmas init` promotes modularity and maintainability. See [Project Structure](https://docs.openmas.ai/project_structure).
* **Layered Configuration:** Robust system loading configuration from files (`openmas_project.yml`, `config/*.yml`), `.env`, and environment variables. See [Configuration Guide](https://docs.openmas.ai/guides/configuration).
* **Agent Reasoning Agnosticism:** While `BaseAgent` inherently supports heuristic-based logic, OpenMAS facilitates integrating diverse reasoning mechanisms. Follow guides for [LLM Integration](https://docs.openmas.ai/guides/llm_integration) (using official LLM client libraries like OpenAI, Anthropic, Google Gemini) or explore built-in support for [BDI Patterns](https://docs.openmas.ai/guides/reasoning_integration) (including `BdiAgent` and [SPADE-BDI](https://pypi.org/project/spade-bdi/) integration examples).
* **Workflow Implementation:** Implement various agent interaction patterns (see [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)). While specific helpers exist for the [Orchestrator-Worker pattern](https://docs.openmas.ai/guides/patterns), the core framework enables building custom workflows like **prompt chaining, routing, and parallel execution**, with more helpers planned for future releases. See [Agent Patterns](https://docs.openmas.ai/guides/patterns).
* **Developer Workflow Tools:** Use the `openmas` CLI tool for initializing projects (`openmas init`), validating configuration (`openmas validate`), running agents locally (`openmas run`), managing dependencies (`openmas deps`), and generating deployment artifacts (`openmas generate-dockerfile`, `openmas generate-compose`). See [CLI Docs](https://docs.openmas.ai/cli/index).
* **Extensibility:** Design encourages local project extensions (`extensions/`) and shareable external packages (`packages/`).
* **Testing Utilities:** Includes `MockCommunicator` and `AgentTestHarness` to facilitate unit and integration testing. See [Testing Your Agents](https://docs.openmas.ai/guides/testing-utilities).

## Model Context Protocol (MCP) Support

OpenMAS now supports MCP 1.7.1, providing a more stable and resilient integration with Anthropic's Model Context Protocol. The MCP integration allows agents to:

- Call tools provided by other agents
- Register tools for other agents to call
- Handle errors gracefully
- Communicate using either SSE (HTTP) or STDIO transports

See the [MCP 1.7.1 Integration Guide](docs/guides/mcp_integration.md) for more details.

## Installation

```bash
pip install openmas
```

