https://github.com/swarmzero/swarmzero
SwarmZero's SDK for building AI agents, swarms of agents and much more.
https://github.com/swarmzero/swarmzero
agent-swarms ai ai-agent ai-swarm decentralized-ai gen-ai gennerative-ai llm multi-agent-framework multi-agent-systems swarm swarms
Last synced: 7 days ago
JSON representation
SwarmZero's SDK for building AI agents, swarms of agents and much more.
- Host: GitHub
- URL: https://github.com/swarmzero/swarmzero
- Owner: swarmzero
- License: apache-2.0
- Created: 2024-08-09T21:16:48.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-01T00:13:23.000Z (9 months ago)
- Last Synced: 2025-01-01T00:33:42.057Z (9 months ago)
- Topics: agent-swarms, ai, ai-agent, ai-swarm, decentralized-ai, gen-ai, gennerative-ai, llm, multi-agent-framework, multi-agent-systems, swarm, swarms
- Language: Python
- Homepage: https://swarmzero.ai
- Size: 1.37 MB
- Stars: 201
- Watchers: 3
- Forks: 29
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://badge.fury.io/py/swarmzero)
[](https://github.com/swarmzero/swarmzero/actions/workflows/test.yml)
[](https://pypi.org/project/swarmzero/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://twitter.com/SwarmZeroAI)
[](https://discord.gg/vnJvW4wZp9)
[](https://swarmzero.ai)
[](https://docs.swarmzero.ai)
# SwarmZero SDK
This library provides you with an easy way to create and run AI Agents and Swarms of Agents.
Supported LLM Providers:
- [OpenAI](https://platform.openai.com/docs/models/)
- [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure%2Cglobal-standard%2Cstandard-chat-completions)
- [Anthropic](https://docs.anthropic.com/en/docs/about-claude/models)
- [MistralAI](https://docs.mistral.ai/getting-started/models/models_overview/)
- [Gemini](https://ai.google.dev/gemini-api/docs/models/gemini)
- [Nebius](https://docs.nebius.com/studio/inference/models)
- [Ollama](https://ollama.com/library)
- [AWS Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/)
- [OpenRouter](https://openrouter.ai/docs)
## Project Requirements
- Python >= 3.11
## Installation
You can either directly install with pip:
```sh
pip install swarmzero
```
Or can either directly install with poetry:
```sh
poetry add swarmzero
```
Or add it to your _requirements.txt_ file:
```sh
...
swarmzero==x.y.z
...
```
## Environment Setup
You need to specify an `OPENAI_API_KEY` in a _.env_ file in this directory.
Make a copy of the [.env.example](.env.example) file and rename it to _.env_.
## Configuration Setup
To use a configuration file with your `Agent`, follow these steps:
1. **Create a Configuration File**:
- Create a TOML or YAML file (e.g., `swarmzero_config.toml` or `swarmzero_config.yaml`) in your project directory. (See [swarmzero_config_example.toml](./swarmzero_config_example.toml) or [swarmzero_config_example.yaml](./swarmzero_config_example.yaml)).
2. **Create an SDK Context**:
- Create an instance of SDKContext with the path to your configuration file.
- The SDKContext allows you to manage configurations, resources, and utilities across your SwarmZero Agents more efficiently.
```python
from swarmzero.sdk_context import SDKContext
sdk_context = SDKContext(config_path="./swarmzero_config.toml")
# or use a YAML file
# sdk_context = SDKContext(config_path="./swarmzero_config.yaml")
```
2. **Specify the Configuration Path**:
- When creating a `Agent` instance, provide the relative or absolute path to your configuration file.
- Agent will use the configuration from the SDK Context. If you have one agent you can directly pass the config_path it will create the sdk_context for you.
```python
from swarmzero import Agent
simple_agent = Agent(
name="Simple Agent",
functions=[],
instruction="your instructions for this agent's goal",
# sdk_context=sdk_context
config_path="./swarmzero_config.toml"
# or use a YAML file
# config_path="./swarmzero_config.yaml"
)
```
## Usage
> _More detailed examples can be found at https://github.com/swarmzero/examples_
First import the `Agent` class:
```python
from swarmzero import Agent
```
Load your environment variables:
```python
from dotenv import load_dotenv
load_dotenv()
```
Then create a Agent instance:
```python
my_agent = Agent(
name="my_agent",
functions=[],
instruction="your instructions for this agent's goal",
)
```
Then, run your agent:
```python
my_agent.run()
```
Finally, call the API endpoint, `/api/v1/chat`, to see the result:
```sh
curl --request POST \
--url http://localhost:8000/api/v1/chat \
--header 'Content-Type: multipart/form-data' \
--form 'user_id="test"' \
--form 'session_id="test"' \
--form 'chat_data={ "messages": [ { "role": "user", "content": "Who is Satoshi Nakamoto?" } ] }'
```
### Adding tools
You can create tools that help your agent handle more complex tasks. Here's an example:
````python
import os
from typing import Optional, Dict
from web3 import Web3
from swarmzero import Agent
from dotenv import load_dotenv
load_dotenv()
rpc_url = os.getenv("RPC_URL") # add an ETH Mainnet HTTP RPC URL to your `.env` file
def get_transaction_receipt(transaction_hash: str) -> Optional[Dict]:
"""
Fetches the receipt of a specified transaction on the Ethereum blockchain and returns it as a dictionary.
:param transaction_hash: The hash of the transaction to fetch the receipt for.
:return: A dictionary containing the transaction receipt details, or None if the transaction cannot be found.
"""
web3 = Web3(Web3.HTTPProvider(rpc_url))
if not web3.is_connected():
print("unable to connect to Ethereum")
return None
try:
transaction_receipt = web3.eth.get_transaction_receipt(transaction_hash)
return dict(transaction_receipt)
except Exception as e:
print(f"an error occurred: {e}")
return None
if __name__ == "__main__":
my_agent = Agent(
name="my_agent",
functions=[get_transaction_receipt]
)
my_agent.run()
"""
[1] send a request:
```
curl --request POST \
--url http://localhost:8000/api/v1/chat \
--header 'Content-Type: multipart/form-data' \
--form 'user_id="test"' \
--form 'session_id="test"' \
--form 'chat_data={ "messages": [ { "role": "user", "content": "Who is the sender of this transaction - 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060" } ] }'
```
[2] result:
The address that initiated the transaction with hash 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060 is 0xA1E4380A3B1f749673E270229993eE55F35663b4.
"""
````
### Creating a Swarm
You can create a swarm of agents to collaborate on complex tasks. Here's an example of how to set up and use a swarm:
````python
from swarmzero.swarm import Swarm
from swarmzero.agent import Agent
from swarmzero.sdk_context import SDKContext
import asyncio
# Create SDK Context
sdk_context = SDKContext(config_path="./swarmzero_config_example.toml")
# or
# sdk_context = SDKContext(config_path="./swarmzero_config_example.yaml")
def save_report():
return "save_item_to_csv"
def search_on_web():
return "search_on_web"
# Create individual agents
agent1 = Agent(name="Research Agent", instruction="Conduct research on given topics", sdk_context=sdk_context,
functions=[search_on_web])
agent2 = Agent(name="Analysis Agent", instruction="Analyze data and provide insights", sdk_context=sdk_context,
functions=[save_report])
agent3 = Agent(name="Report Agent", instruction="Compile findings into a report", sdk_context=sdk_context, functions=[])
# Create swarm
swarm = Swarm(name="Research Team", description="A swarm of agents that collaborate on research tasks",
instruction="Be helpful and collaborative", functions=[], agents=[agent1, agent2, agent3])
async def chat_with_swarm():
return await swarm.chat("Can you analyze the following data: [1, 2, 3, 4, 5]")
if __name__ == "__main__":
asyncio.run(chat_with_swarm())
````
### Workflow
You can orchestrate agents, swarms, and tools in a flexible workflow. Each step
can run sequentially, in parallel, conditionally, or in a loop.
````python
from swarmzero import Workflow, WorkflowStep, StepMode
from swarmzero.sdk_context import SDKContext
import asyncio
# Create SDK Context
sdk_context = SDKContext(config_path="./swarmzero_config.toml")
# agent1, agent2, agent3, and agent4 are pre-defined Agent instances
workflow = Workflow(
name="Research Workflow",
description="Research and Analysis Pipeline",
instruction="Demo workflow",
sdk_context=sdk_context,
steps=[
# Sequential step - runs agent1
WorkflowStep(runner=agent1.chat),
# Parallel step - runs agent2 and agent3
WorkflowStep(runner=[agent2.chat, agent3.chat], mode=StepMode.PARALLEL),
# Loop step - repeats until condition is met
WorkflowStep(
runner=agent4.chat,
mode=StepMode.LOOP,
condition=lambda res: "done" in res,
max_iterations=5,
),
],
)
async def run_workflow():
return await workflow.run("Start research")
if __name__ == "__main__":
asyncio.run(run_workflow())
````
#### Nested Workflows
Workflow steps can themselves be workflows. This allows complex pipelines to be
composed from smaller, reusable ones.
````python
inner = Workflow(
name="Inner",
steps=[WorkflowStep(runner=agent1.chat)],
)
outer = Workflow(
name="Outer",
steps=[WorkflowStep(runner=inner)],
)
async def run_nested():
return await outer.run("start")
if __name__ == "__main__":
asyncio.run(run_nested())
````
### Adding Retriever
You can add retriever tools to create vector embeddings and retrieve semantic information. It will create vector index for every pdf documents under 'swarmzero-data/files/user' folder and can filter files with required_exts parameter.
- SwarmZero agent supports ".md", '.mdx' ,".txt", '.csv', '.docx', '.pdf' file types.
- SwarmZero agent supports 4 type of retriever (basic, chroma, pinecone-serverless, pinecone-pod) and controlled with retrieval_tool parameter.
````python
from swarmzero import Agent
from dotenv import load_dotenv
load_dotenv()
if __name__ == "__main__":
my_agent = Agent(
name="retrieve-test",
functions=[],
retrieve = True,
required_exts = ['.md'],
retrieval_tool='chroma'
)
my_agent.run()
"""
[1] send a request:
```
curl --request POST \
--url http://localhost:8000/api/v1/chat \
--header 'Content-Type: multipart/form-data' \
--form 'user_id="test"' \
--form 'session_id="test"' \
--form 'chat_data={ "messages": [ { "role": "user", "content": "Can you summarise the documents?" } ] }'
```
"""
````
### Adding Sample Prompts
Users of your agent/swarm may not always be familiar with its abilities.
Providing sample prompts allows them to explore what you have built.
Here's how to add sample prompts which they can use before committing to use your agent/swarm.
#### Default
In your swarmzero_config.toml file, create a **top level** entry called `[sample_prompts]` and add a new array to the key `prompts` like this:
```toml
[sample_prompts]
prompts = [
"What can you help me do?",
"Which tools do you have access to?",
"What are your capabilities?"
]
```
#### Specific agents in a swarm
```toml
[target_agent_id]
model = "gpt-3.5-turbo"
timeout = 15
environment = "dev"
enable_multi_modal = true
ollama_server_url = 'http://123.456.78.90:11434'
sample_prompts = [
"What can you help me do?",
"Which tools do you have access to?",
"What are your capabilities?"
]
```
See [./swarmzero_config_example.toml](./swarmzero_config_example.toml) or [./swarmzero_config_example.yaml](./swarmzero_config_example.yaml) for example configuration files.
## Contributing
### Setup
If you want to contribute to the codebase, you would need to set up your dev environment. Follow these steps:
- Create a new file called .env
- Copy the contents of [.env.example](.env.example) into your new .env file
- API keys for third-party tools are not provided.
- `OPENAI_API_KEY` from OpenAI
- If you don't have Poetry installed, you can install it using the following commands:
```sh
curl -sSL https://install.python-poetry.org | python3 -
export PATH="$HOME/.local/bin:$PATH"
```
- Activate the Virtual Environment created by Poetry with the following command:
```sh
poetry shell
```
- Install dependencies.
```sh
poetry install --no-root
```
### Testing
- Make sure you're in the `tests/` directory:
```sh
cd tests/
```
- Run the test suite:
```sh
pytest
```
- Run tests for a specific module:
```sh
pytest tests/path/to/test_module.py
```
- Run with verbose output:
```sh
pytest -v
```
- Run with a detailed output of each test (including print statements):
```sh
pytest -s
```
- Run with coverage report:
```sh
pip install coverage pytest-cov
pytest --cov --cov-report=html
```
Reports file `tests/htmlcov/index.html`
## API Doc
Open [http://localhost:8000/docs](http://localhost:8000/docs) with your browser to see the Swagger UI of the API.
## Learn More