{"id":24389494,"url":"https://github.com/swarmzero/swarmzero","last_synced_at":"2026-04-09T19:03:03.588Z","repository":{"id":259163702,"uuid":"840500420","full_name":"swarmzero/swarmzero","owner":"swarmzero","description":"SwarmZero's SDK for building AI agents, swarms of agents and much more.","archived":false,"fork":false,"pushed_at":"2025-01-01T00:13:23.000Z","size":1440,"stargazers_count":201,"open_issues_count":0,"forks_count":29,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-01T00:33:42.057Z","etag":null,"topics":["agent-swarms","ai","ai-agent","ai-swarm","decentralized-ai","gen-ai","gennerative-ai","llm","multi-agent-framework","multi-agent-systems","swarm","swarms"],"latest_commit_sha":null,"homepage":"https://swarmzero.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swarmzero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-09T21:16:48.000Z","updated_at":"2025-01-01T00:13:17.000Z","dependencies_parsed_at":"2024-10-28T02:35:15.132Z","dependency_job_id":"bf39306b-c058-41ac-9a40-fdb54ffc8334","html_url":"https://github.com/swarmzero/swarmzero","commit_stats":null,"previous_names":["swarmzero/swarmzero"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmzero%2Fswarmzero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmzero%2Fswarmzero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmzero%2Fswarmzero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmzero%2Fswarmzero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swarmzero","download_url":"https://codeload.github.com/swarmzero/swarmzero/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234660323,"owners_count":18867698,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-swarms","ai","ai-agent","ai-swarm","decentralized-ai","gen-ai","gennerative-ai","llm","multi-agent-framework","multi-agent-systems","swarm","swarms"],"created_at":"2025-01-19T15:33:52.773Z","updated_at":"2025-09-29T20:31:41.254Z","avatar_url":"https://github.com/swarmzero.png","language":"Python","readme":"[![PyPI version](https://badge.fury.io/py/swarmzero.svg)](https://badge.fury.io/py/swarmzero)\n[![CI](https://github.com/swarmzero/swarmzero/actions/workflows/test.yml/badge.svg)](https://github.com/swarmzero/swarmzero/actions/workflows/test.yml)\n[![Python Versions](https://img.shields.io/pypi/pyversions/swarmzero.svg)](https://pypi.org/project/swarmzero/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n[![Twitter Follow](https://img.shields.io/twitter/follow/SwarmZeroAI?style=social)](https://twitter.com/SwarmZeroAI)\n[![](https://dcbadge.limes.pink/api/server/vnJvW4wZp9)](https://discord.gg/vnJvW4wZp9)\n\n[![Website](https://img.shields.io/badge/website-swarmzero.ai-fdb022?style=for-the-badge)](https://swarmzero.ai)\n[![Doc](https://img.shields.io/badge/docs-docs.swarmzero.ai-fdb022?style=for-the-badge)](https://docs.swarmzero.ai)\n\n![](./assets/logo_dark.png)\n\n# SwarmZero SDK\n\nThis library provides you with an easy way to create and run AI Agents and Swarms of Agents.\n\nSupported LLM Providers:\n- [OpenAI](https://platform.openai.com/docs/models/)\n- [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure%2Cglobal-standard%2Cstandard-chat-completions)\n- [Anthropic](https://docs.anthropic.com/en/docs/about-claude/models)\n- [MistralAI](https://docs.mistral.ai/getting-started/models/models_overview/)\n- [Gemini](https://ai.google.dev/gemini-api/docs/models/gemini)\n- [Nebius](https://docs.nebius.com/studio/inference/models)\n- [Ollama](https://ollama.com/library)\n- [AWS Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/)\n- [OpenRouter](https://openrouter.ai/docs)\n\n## Project Requirements\n\n- Python \u003e= 3.11\n\n## Installation\n\nYou can either directly install with pip:\n\n```sh\npip install swarmzero\n```\n\nOr can either directly install with poetry:\n\n```sh\npoetry add swarmzero\n```\n\nOr add it to your _requirements.txt_ file:\n\n```sh\n...\nswarmzero==x.y.z\n...\n```\n\n## Environment Setup\n\nYou need to specify an `OPENAI_API_KEY` in a _.env_ file in this directory.\n\nMake a copy of the [.env.example](.env.example) file and rename it to _.env_.\n\n## Configuration Setup\n\nTo use a configuration file with your `Agent`, follow these steps:\n\n1. **Create a Configuration File**:\n\n   - 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)).\n\n2. **Create an SDK Context**:\n\n   - Create an instance of SDKContext with the path to your configuration file.\n   - The SDKContext allows you to manage configurations, resources, and utilities across your SwarmZero Agents more efficiently.\n\n   ```python\n   from swarmzero.sdk_context import SDKContext\n\n   sdk_context = SDKContext(config_path=\"./swarmzero_config.toml\")\n   # or use a YAML file\n   # sdk_context = SDKContext(config_path=\"./swarmzero_config.yaml\")\n   ```\n\n2. **Specify the Configuration Path**:\n\n   - When creating a `Agent` instance, provide the relative or absolute path to your configuration file.\n   - 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.\n\n\n   ```python\n   from swarmzero import Agent\n\n   simple_agent = Agent(\n       name=\"Simple Agent\",\n       functions=[],\n       instruction=\"your instructions for this agent's goal\",\n       # sdk_context=sdk_context\n       config_path=\"./swarmzero_config.toml\" \n       # or use a YAML file\n       # config_path=\"./swarmzero_config.yaml\" \n   )\n   ```\n\n## Usage\n\n\u003e _More detailed examples can be found at https://github.com/swarmzero/examples_\n\nFirst import the `Agent` class:\n\n```python\nfrom swarmzero import Agent\n```\n\nLoad your environment variables:\n\n```python\nfrom dotenv import load_dotenv\nload_dotenv()\n```\n\nThen create a Agent instance:\n\n```python\nmy_agent = Agent(\n    name=\"my_agent\",\n    functions=[],\n    instruction=\"your instructions for this agent's goal\",\n)\n```\n\nThen, run your agent:\n\n```python\nmy_agent.run()\n```\n\nFinally, call the API endpoint, `/api/v1/chat`, to see the result:\n\n```sh\ncurl --request POST \\\n  --url http://localhost:8000/api/v1/chat \\\n  --header 'Content-Type: multipart/form-data' \\\n  --form 'user_id=\"test\"' \\\n  --form 'session_id=\"test\"' \\\n  --form 'chat_data={ \"messages\": [ { \"role\": \"user\", \"content\": \"Who is Satoshi Nakamoto?\" } ] }'\n```\n\n### Adding tools\n\nYou can create tools that help your agent handle more complex tasks. Here's an example:\n\n````python\nimport os\nfrom typing import Optional, Dict\nfrom web3 import Web3\nfrom swarmzero import Agent\nfrom dotenv import load_dotenv\n\nload_dotenv()\n\nrpc_url = os.getenv(\"RPC_URL\") # add an ETH Mainnet HTTP RPC URL to your `.env` file\n\ndef get_transaction_receipt(transaction_hash: str) -\u003e Optional[Dict]:\n    \"\"\"\n    Fetches the receipt of a specified transaction on the Ethereum blockchain and returns it as a dictionary.\n\n    :param transaction_hash: The hash of the transaction to fetch the receipt for.\n    :return: A dictionary containing the transaction receipt details, or None if the transaction cannot be found.\n    \"\"\"\n    web3 = Web3(Web3.HTTPProvider(rpc_url))\n\n    if not web3.is_connected():\n        print(\"unable to connect to Ethereum\")\n        return None\n\n    try:\n        transaction_receipt = web3.eth.get_transaction_receipt(transaction_hash)\n        return dict(transaction_receipt)\n    except Exception as e:\n        print(f\"an error occurred: {e}\")\n        return None\n\nif __name__ == \"__main__\":\n    my_agent = Agent(\n        name=\"my_agent\",\n        functions=[get_transaction_receipt]\n    )\n\n    my_agent.run()\n\n    \"\"\"\n    [1] send a request:\n\n    ```\n    curl --request POST \\\n    --url http://localhost:8000/api/v1/chat \\\n    --header 'Content-Type: multipart/form-data' \\\n    --form 'user_id=\"test\"' \\\n    --form 'session_id=\"test\"' \\\n    --form 'chat_data={ \"messages\": [ { \"role\": \"user\", \"content\": \"Who is the sender of this transaction - 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060\" } ] }'\n    ```\n\n    [2] result:\n\n    The address that initiated the transaction with hash 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060 is 0xA1E4380A3B1f749673E270229993eE55F35663b4.\n    \"\"\"\n````\n\n### Creating a Swarm\n\nYou can create a swarm of agents to collaborate on complex tasks. Here's an example of how to set up and use a swarm:\n\n````python\nfrom swarmzero.swarm import Swarm\nfrom swarmzero.agent import Agent\nfrom swarmzero.sdk_context import SDKContext\n\nimport asyncio\n\n# Create SDK Context\nsdk_context = SDKContext(config_path=\"./swarmzero_config_example.toml\")\n# or\n# sdk_context = SDKContext(config_path=\"./swarmzero_config_example.yaml\")\n\n\ndef save_report():\n    return \"save_item_to_csv\"\n\n\ndef search_on_web():\n    return \"search_on_web\"\n\n\n# Create individual agents\nagent1 = Agent(name=\"Research Agent\", instruction=\"Conduct research on given topics\", sdk_context=sdk_context,\n               functions=[search_on_web])\nagent2 = Agent(name=\"Analysis Agent\", instruction=\"Analyze data and provide insights\", sdk_context=sdk_context,\n               functions=[save_report])\nagent3 = Agent(name=\"Report Agent\", instruction=\"Compile findings into a report\", sdk_context=sdk_context, functions=[])\n\n# Create swarm\nswarm = Swarm(name=\"Research Team\", description=\"A swarm of agents that collaborate on research tasks\",\n              instruction=\"Be helpful and collaborative\", functions=[], agents=[agent1, agent2, agent3])\n\n\nasync def chat_with_swarm():\n    return await swarm.chat(\"Can you analyze the following data: [1, 2, 3, 4, 5]\")\n\n\nif __name__ == \"__main__\":\n    asyncio.run(chat_with_swarm())\n````\n\n### Workflow\n\nYou can orchestrate agents, swarms, and tools in a flexible workflow. Each step\ncan run sequentially, in parallel, conditionally, or in a loop.\n\n````python\nfrom swarmzero import Workflow, WorkflowStep, StepMode\nfrom swarmzero.sdk_context import SDKContext\nimport asyncio\n\n# Create SDK Context\nsdk_context = SDKContext(config_path=\"./swarmzero_config.toml\")\n\n# agent1, agent2, agent3, and agent4 are pre-defined Agent instances\n\nworkflow = Workflow(\n    name=\"Research Workflow\",\n    description=\"Research and Analysis Pipeline\",\n    instruction=\"Demo workflow\",\n    sdk_context=sdk_context,\n    steps=[\n        # Sequential step - runs agent1\n        WorkflowStep(runner=agent1.chat),\n        # Parallel step - runs agent2 and agent3\n        WorkflowStep(runner=[agent2.chat, agent3.chat], mode=StepMode.PARALLEL),\n        # Loop step - repeats until condition is met\n        WorkflowStep(\n            runner=agent4.chat,\n            mode=StepMode.LOOP,\n            condition=lambda res: \"done\" in res,\n            max_iterations=5,\n        ),\n    ],\n)\n\nasync def run_workflow():\n    return await workflow.run(\"Start research\")\n\nif __name__ == \"__main__\":\n    asyncio.run(run_workflow())\n````\n\n#### Nested Workflows\n\nWorkflow steps can themselves be workflows. This allows complex pipelines to be\ncomposed from smaller, reusable ones.\n\n````python\ninner = Workflow(\n    name=\"Inner\",\n    steps=[WorkflowStep(runner=agent1.chat)],\n)\n\nouter = Workflow(\n    name=\"Outer\",\n    steps=[WorkflowStep(runner=inner)],\n)\n\nasync def run_nested():\n    return await outer.run(\"start\")\n\nif __name__ == \"__main__\":\n    asyncio.run(run_nested())\n````\n\n### Adding Retriever\n\nYou 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.\n\n- SwarmZero agent supports \".md\", '.mdx' ,\".txt\", '.csv', '.docx', '.pdf' file types.\n- SwarmZero agent supports 4 type of retriever (basic, chroma, pinecone-serverless, pinecone-pod) and controlled with retrieval_tool parameter.\n\n````python\nfrom swarmzero import Agent\nfrom dotenv import load_dotenv\n\nload_dotenv()\n\nif __name__ == \"__main__\":\n    my_agent = Agent(\n        name=\"retrieve-test\",\n        functions=[],\n        retrieve = True,\n        required_exts = ['.md'],\n        retrieval_tool='chroma'\n    )\n\n    my_agent.run()\n\n    \"\"\"\n    [1] send a request:\n\n    ```\n    curl --request POST \\\n    --url http://localhost:8000/api/v1/chat \\\n    --header 'Content-Type: multipart/form-data' \\\n    --form 'user_id=\"test\"' \\\n    --form 'session_id=\"test\"' \\\n    --form 'chat_data={ \"messages\": [ { \"role\": \"user\", \"content\": \"Can you summarise the documents?\" } ] }'\n    ```\n    \"\"\"\n````\n\n\n### Adding Sample Prompts\n\nUsers of your agent/swarm may not always be familiar with its abilities.\nProviding sample prompts allows them to explore what you have built.\nHere's how to add sample prompts which they can use before committing to use your agent/swarm.\n\n#### Default\nIn your swarmzero_config.toml file, create a **top level** entry called `[sample_prompts]` and add a new array to the key `prompts` like this:\n```toml\n[sample_prompts]\nprompts = [\n  \"What can you help me do?\",\n  \"Which tools do you have access to?\",\n  \"What are your capabilities?\"\n]\n```\n\n#### Specific agents in a swarm\n```toml\n[target_agent_id]\nmodel = \"gpt-3.5-turbo\"\ntimeout = 15\nenvironment = \"dev\"\nenable_multi_modal = true\nollama_server_url = 'http://123.456.78.90:11434'\nsample_prompts = [\n    \"What can you help me do?\",\n    \"Which tools do you have access to?\",\n    \"What are your capabilities?\"\n]\n```\n\nSee [./swarmzero_config_example.toml](./swarmzero_config_example.toml) or [./swarmzero_config_example.yaml](./swarmzero_config_example.yaml) for example configuration files.\n\n\n## Contributing\n\n### Setup\n\nIf you want to contribute to the codebase, you would need to set up your dev environment. Follow these steps:\n\n- Create a new file called .env\n- Copy the contents of [.env.example](.env.example) into your new .env file\n- API keys for third-party tools are not provided.\n  - `OPENAI_API_KEY` from OpenAI\n- If you don't have Poetry installed, you can install it using the following commands:\n\n```sh\ncurl -sSL https://install.python-poetry.org | python3 -\n\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n- Activate the Virtual Environment created by Poetry with the following command:\n\n```sh\npoetry shell\n```\n\n- Install dependencies.\n\n```sh\npoetry install --no-root\n```\n\n### Testing\n\n- Make sure you're in the `tests/` directory:\n\n```sh\ncd tests/\n```\n\n- Run the test suite:\n\n```sh\npytest\n```\n\n- Run tests for a specific module:\n\n```sh\npytest tests/path/to/test_module.py\n```\n\n- Run with verbose output:\n\n```sh\npytest -v\n```\n\n- Run with a detailed output of each test (including print statements):\n\n```sh\npytest -s\n```\n\n- Run with coverage report:\n\n```sh\npip install coverage pytest-cov\npytest  --cov --cov-report=html\n```\n\nReports file `tests/htmlcov/index.html`\n\n## API Doc\n\nOpen [http://localhost:8000/docs](http://localhost:8000/docs) with your browser to see the Swagger UI of the API.\n\n## Learn More\n\n\u003chttps://swarmzero.ai\u003e\n","funding_links":[],"categories":["AI Agent Frameworks"],"sub_categories":["Python"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswarmzero%2Fswarmzero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswarmzero%2Fswarmzero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswarmzero%2Fswarmzero/lists"}