# OpenAgents Framework
A network-based multi-agent framework where agents connect to a central server for communication and coordination.
## Quick Start
1. Start a network server:
```python
from openagents.core.network import AgentNetworkServer
# Create and start server
network = AgentNetworkServer(host="127.0.0.1", port=8765)
network.run()
```
2. Connect agents to the server:
```python
from openagents.core.agent import Agent
# Create and connect agent
agent = Agent(name="MyAgent")
await agent.connect_to_server("127.0.0.1", 8765)
# Send messages to other agents
await agent.send_message("other_agent_id", "Hello!")
```
## Architecture
The framework uses a client-server architecture where:
- A central server manages all agent connections
- Agents connect to the server using WebSocket connections
- All communication between agents goes through the server
- Protocols define message handling behavior
## Project Website
Visit our project website at [https://openagents.org](https://openagents.org) for more information, documentation, and resources.
## Overview
OpenAgents provides an engine for running a network with a set of protocols. The framework is designed to be modular, allowing developers to:
1. Create agents with any combination of protocols
2. Establish networks with specific protocol requirements
3. Contribute custom protocols that can be used by other developers
## Features
- **Modular Protocol System**: Mix and match protocols to create the exact agent network you need
- **Flexible Agent Architecture**: Agents can implement any combination of protocols
- **Customizable Communication Patterns**: Support for direct messaging, publish-subscribe, and more
- **Protocol Discovery**: Agents can discover and interact with other agents based on their capabilities
- **Extensible Framework**: Easy to add new protocols and extend existing ones
## Core Protocols
OpenAgents includes several built-in protocols:
| Protocol | Description | Key Features |
|----------|-------------|--------------|
| Discovery | Agent registration and service discovery | Agent registration/deregistration, Service announcement & discovery, Capability advertising |
| Communication | Message exchange between agents | Direct messaging, Publish-subscribe, Request-response patterns |
| Heartbeat | Agent liveness monitoring | Regular status checks, Network health detection |
| Identity & Authentication | Security and identity management | Agent identifiers, Authentication/authorization |
| Coordination | Task distribution and negotiation | Task negotiation & delegation, Contract-net protocol |
| Resource Management | Resource allocation and tracking | Resource allocation & accounting, Usage metering |
## Project Structure
```
openagents/
├── core/
│ ├── agent.py # Core agent implementation
│ ├── network.py # Core network engine implementation
│ ├── protocol_base.py # Base class for all protocols
│ ├── agent_protocol_base.py # Base class for agent-level protocols
│ └── network_protocol_base.py # Base class for network-level protocols
│
├── protocols/
│ ├── discovery/ # Discovery protocol implementation
│ ├── communication/ # Communication protocol implementation
│ ├── heartbeat/ # Heartbeat protocol implementation
│ └── ... # Other protocol implementations
│
├── configs/ # Configuration files
├── utils/ # Utility functions
├── tests/ # Test suite
├── docs/ # Documentation
└── examples/ # Example implementations
```
## Contributing
We welcome contributions to the OpenAgents framework! Whether you want to fix bugs, add new features, or create new protocols, your help is appreciated.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Development and Testing
### Prerequisites
OpenAgents requires Python 3.8 or higher. The project uses modern async/await patterns throughout.
### Setting Up the Development Environment
#### Option 1: Using pyproject.toml (Recommended)
```bash
# Clone the repository
git clone https://github.com/openagents/openagents.git
cd openagents
# Install with all development dependencies
pip install -e ".[dev]"
```
#### Option 2: Using requirements file
```bash
# Install core package
pip install -e .
# Install test dependencies
pip install -r requirements-test.txt
```
#### Option 3: Using the setup script
```bash
# Run the automated setup and test script
python setup_tests.py
```
#### Option 4: Using Makefile
```bash
# Install dependencies and run tests
make install test
# Or run specific commands
make test-coverage # Run tests with coverage
make test-fast # Run tests in parallel
make all # Full development workflow
```
### Running Tests
The project includes a comprehensive test suite covering all major components:
```bash
# Run all tests
pytest
# Run with verbose output
pytest -v
# Run specific test categories
pytest tests/test_network.py # Core network tests
pytest tests/test_transport.py # Transport layer tests
pytest tests/test_topology.py # Topology tests
pytest tests/test_simple_messaging.py # Protocol tests
# Run tests with coverage
pytest --cov=src/openagents --cov-report=html
# Run tests in parallel (faster)
pytest -n auto
# Run specific test patterns
pytest -k "network" # Tests matching "network"
pytest tests/ -m "not slow" # Exclude slow tests
```
### Test Organization
The test suite includes:
- **Network Tests** (`test_network.py`) - Core network functionality, agent lifecycle, message routing
- **Transport Tests** (`test_transport.py`) - WebSocket transport, connection management
- **Topology Tests** (`test_topology.py`) - Centralized/decentralized topologies, agent discovery
- **Protocol Tests** - Agent discovery, messaging protocols, protocol loading
- **Launcher Tests** (`test_network_launcher.py`) - Configuration loading, network startup
### Test Coverage
The project maintains >90% test coverage across core functionality:
```bash
# Generate coverage report
pytest --cov=src/openagents --cov-report=html
open htmlcov/index.html # View detailed coverage report
```
### Continuous Integration
Tests run automatically on:
- Python 3.8, 3.9, 3.10, 3.11, 3.12
- Multiple operating systems (Linux, macOS, Windows)
- All pull requests and pushes to main branch
Current test status: **57 tests passing** with comprehensive coverage of all major components.
### Local Development Setup
```bash
# Clone the repository
git clone https://github.com/openagents/openagents.git
cd openagents
# Create and activate a virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Install the package in development mode
pip install -e .
# Run an example
python examples/example_network.py
```
### Command Line Interface
OpenAgents provides a command-line interface for basic operations:
```bash
# Launch a network with a configuration file
openagents network launch config.json --runtime 3600
# Get help on available commands
openagents --help
# Set logging level
openagents --log-level DEBUG network launch config.json
```
The CLI is currently under development, with more commands planned for future releases. The configuration file should specify the network name, protocols, and other settings.
Example configuration file (config.json):
```json
{
"name": "MyNetwork",
"protocols": {
"discovery": {},
"communication": {}
}
}
```
For more advanced usage, refer to the Python API examples above.
Raw data
{
"_id": null,
"home_page": "https://github.com/bestagents/openagents",
"name": "openagents",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "OpenAgents Team",
"author_email": "OpenAgents Team <info@openagents.org>",
"download_url": "https://files.pythonhosted.org/packages/80/f8/6f84bbd9eb489b38867209f307f270733a1a662b48d2d93932c5e4e97c39/openagents-0.5.1.tar.gz",
"platform": null,
"description": "# OpenAgents Framework\n\nA network-based multi-agent framework where agents connect to a central server for communication and coordination.\n\n## Quick Start\n\n1. Start a network server:\n```python\nfrom openagents.core.network import AgentNetworkServer\n\n# Create and start server\nnetwork = AgentNetworkServer(host=\"127.0.0.1\", port=8765)\nnetwork.run()\n```\n\n2. Connect agents to the server:\n```python\nfrom openagents.core.agent import Agent\n\n# Create and connect agent\nagent = Agent(name=\"MyAgent\")\nawait agent.connect_to_server(\"127.0.0.1\", 8765)\n\n# Send messages to other agents\nawait agent.send_message(\"other_agent_id\", \"Hello!\")\n```\n\n## Architecture\n\nThe framework uses a client-server architecture where:\n- A central server manages all agent connections\n- Agents connect to the server using WebSocket connections\n- All communication between agents goes through the server\n- Protocols define message handling behavior\n\n## Project Website\n\nVisit our project website at [https://openagents.org](https://openagents.org) for more information, documentation, and resources.\n\n## Overview\n\nOpenAgents provides an engine for running a network with a set of protocols. The framework is designed to be modular, allowing developers to:\n\n1. Create agents with any combination of protocols\n2. Establish networks with specific protocol requirements\n3. Contribute custom protocols that can be used by other developers\n\n## Features\n\n- **Modular Protocol System**: Mix and match protocols to create the exact agent network you need\n- **Flexible Agent Architecture**: Agents can implement any combination of protocols\n- **Customizable Communication Patterns**: Support for direct messaging, publish-subscribe, and more\n- **Protocol Discovery**: Agents can discover and interact with other agents based on their capabilities\n- **Extensible Framework**: Easy to add new protocols and extend existing ones\n\n## Core Protocols\n\nOpenAgents includes several built-in protocols:\n\n| Protocol | Description | Key Features |\n|----------|-------------|--------------|\n| Discovery | Agent registration and service discovery | Agent registration/deregistration, Service announcement & discovery, Capability advertising |\n| Communication | Message exchange between agents | Direct messaging, Publish-subscribe, Request-response patterns |\n| Heartbeat | Agent liveness monitoring | Regular status checks, Network health detection |\n| Identity & Authentication | Security and identity management | Agent identifiers, Authentication/authorization |\n| Coordination | Task distribution and negotiation | Task negotiation & delegation, Contract-net protocol |\n| Resource Management | Resource allocation and tracking | Resource allocation & accounting, Usage metering |\n\n## Project Structure\n\n```\n openagents/\n \u251c\u2500\u2500 core/\n \u2502 \u251c\u2500\u2500 agent.py # Core agent implementation\n \u2502 \u251c\u2500\u2500 network.py # Core network engine implementation\n \u2502 \u251c\u2500\u2500 protocol_base.py # Base class for all protocols\n \u2502 \u251c\u2500\u2500 agent_protocol_base.py # Base class for agent-level protocols\n \u2502 \u2514\u2500\u2500 network_protocol_base.py # Base class for network-level protocols\n \u2502\n \u251c\u2500\u2500 protocols/\n \u2502 \u251c\u2500\u2500 discovery/ # Discovery protocol implementation\n \u2502 \u251c\u2500\u2500 communication/ # Communication protocol implementation\n \u2502 \u251c\u2500\u2500 heartbeat/ # Heartbeat protocol implementation\n \u2502 \u2514\u2500\u2500 ... # Other protocol implementations\n \u2502\n \u251c\u2500\u2500 configs/ # Configuration files\n \u251c\u2500\u2500 utils/ # Utility functions\n \u251c\u2500\u2500 tests/ # Test suite\n \u251c\u2500\u2500 docs/ # Documentation\n \u2514\u2500\u2500 examples/ # Example implementations\n```\n\n## Contributing\n\nWe welcome contributions to the OpenAgents framework! Whether you want to fix bugs, add new features, or create new protocols, your help is appreciated.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Development and Testing\n\n### Prerequisites\n\nOpenAgents requires Python 3.8 or higher. The project uses modern async/await patterns throughout.\n\n### Setting Up the Development Environment\n\n#### Option 1: Using pyproject.toml (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/openagents/openagents.git\ncd openagents\n\n# Install with all development dependencies\npip install -e \".[dev]\"\n```\n\n#### Option 2: Using requirements file\n\n```bash\n# Install core package\npip install -e .\n\n# Install test dependencies\npip install -r requirements-test.txt\n```\n\n#### Option 3: Using the setup script\n\n```bash\n# Run the automated setup and test script\npython setup_tests.py\n```\n\n#### Option 4: Using Makefile\n\n```bash\n# Install dependencies and run tests\nmake install test\n\n# Or run specific commands\nmake test-coverage # Run tests with coverage\nmake test-fast # Run tests in parallel\nmake all # Full development workflow\n```\n\n### Running Tests\n\nThe project includes a comprehensive test suite covering all major components:\n\n```bash\n# Run all tests\npytest\n\n# Run with verbose output\npytest -v\n\n# Run specific test categories\npytest tests/test_network.py # Core network tests\npytest tests/test_transport.py # Transport layer tests\npytest tests/test_topology.py # Topology tests\npytest tests/test_simple_messaging.py # Protocol tests\n\n# Run tests with coverage\npytest --cov=src/openagents --cov-report=html\n\n# Run tests in parallel (faster)\npytest -n auto\n\n# Run specific test patterns\npytest -k \"network\" # Tests matching \"network\"\npytest tests/ -m \"not slow\" # Exclude slow tests\n```\n\n### Test Organization\n\nThe test suite includes:\n\n- **Network Tests** (`test_network.py`) - Core network functionality, agent lifecycle, message routing\n- **Transport Tests** (`test_transport.py`) - WebSocket transport, connection management \n- **Topology Tests** (`test_topology.py`) - Centralized/decentralized topologies, agent discovery\n- **Protocol Tests** - Agent discovery, messaging protocols, protocol loading\n- **Launcher Tests** (`test_network_launcher.py`) - Configuration loading, network startup\n\n### Test Coverage\n\nThe project maintains >90% test coverage across core functionality:\n\n```bash\n# Generate coverage report\npytest --cov=src/openagents --cov-report=html\nopen htmlcov/index.html # View detailed coverage report\n```\n\n### Continuous Integration\n\nTests run automatically on:\n- Python 3.8, 3.9, 3.10, 3.11, 3.12\n- Multiple operating systems (Linux, macOS, Windows)\n- All pull requests and pushes to main branch\n\nCurrent test status: **57 tests passing** with comprehensive coverage of all major components.\n\n### Local Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/openagents/openagents.git\ncd openagents\n\n# Create and activate a virtual environment (optional but recommended)\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Install the package in development mode\npip install -e .\n\n# Run an example\npython examples/example_network.py\n```\n\n### Command Line Interface\n\nOpenAgents provides a command-line interface for basic operations:\n\n```bash\n# Launch a network with a configuration file\nopenagents network launch config.json --runtime 3600\n\n# Get help on available commands\nopenagents --help\n\n# Set logging level\nopenagents --log-level DEBUG network launch config.json\n```\n\nThe CLI is currently under development, with more commands planned for future releases. The configuration file should specify the network name, protocols, and other settings.\n\nExample configuration file (config.json):\n```json\n{\n \"name\": \"MyNetwork\",\n \"protocols\": {\n \"discovery\": {},\n \"communication\": {}\n }\n}\n```\n\nFor more advanced usage, refer to the Python API examples above.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A flexible framework for building multi-agent systems with customizable protocols",
"version": "0.5.1",
"project_urls": {
"Documentation": "https://openagents.readthedocs.io",
"Homepage": "https://github.com/bestagents/openagents",
"Issues": "https://github.com/bestagents/openagents/issues",
"Repository": "https://github.com/bestagents/openagents"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9eca79211b3a655fcf248ab4a73b45f8d9cb3e52076dea9a280ea84a938d6c65",
"md5": "52d0948d74476820e5dcbbbde9409bb4",
"sha256": "7fa4ed0ea81d16bdacae48aa375db7034afd753cfd5cd6143550440076d72706"
},
"downloads": -1,
"filename": "openagents-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "52d0948d74476820e5dcbbbde9409bb4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 91509,
"upload_time": "2025-07-19T19:17:10",
"upload_time_iso_8601": "2025-07-19T19:17:10.893968Z",
"url": "https://files.pythonhosted.org/packages/9e/ca/79211b3a655fcf248ab4a73b45f8d9cb3e52076dea9a280ea84a938d6c65/openagents-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "80f86f84bbd9eb489b38867209f307f270733a1a662b48d2d93932c5e4e97c39",
"md5": "c2f0ee6466087699eceb1d27c84d1451",
"sha256": "62db4352212682212d20889e9effc8d170475d6cb1a500a7dfc949713fc178c6"
},
"downloads": -1,
"filename": "openagents-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "c2f0ee6466087699eceb1d27c84d1451",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 92671,
"upload_time": "2025-07-19T19:17:12",
"upload_time_iso_8601": "2025-07-19T19:17:12.331192Z",
"url": "https://files.pythonhosted.org/packages/80/f8/6f84bbd9eb489b38867209f307f270733a1a662b48d2d93932c5e4e97c39/openagents-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 19:17:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bestagents",
"github_project": "openagents",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "openagents"
}
JSON
