{"id":22561567,"url":"https://github.com/versionhq/multi-agent-system","last_synced_at":"2025-10-08T16:53:30.145Z","repository":{"id":266701059,"uuid":"895587380","full_name":"versionHQ/multi-agent-system","owner":"versionHQ","description":"Autonomous agent networks for task automation that requires multi-step reasoning","archived":false,"fork":false,"pushed_at":"2025-04-01T07:20:35.000Z","size":3275,"stargazers_count":13,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T21:02:46.445Z","etag":null,"topics":["agentic-ai","autonomous-agents","composiotool","docling","graph-theory","langchain","litellm","matplotlib","mem0ai","multi-agent-systems","multi-step-reasoning","networkx","orchestration-framework","pydantic","pygraphviz","python3","rag","self-directed-learning"],"latest_commit_sha":null,"homepage":"https://versi0n.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/versionHQ.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-28T13:41:28.000Z","updated_at":"2025-04-01T07:20:15.000Z","dependencies_parsed_at":"2025-01-16T18:28:43.291Z","dependency_job_id":"15af9b2a-b7f9-435f-a905-aac32b8e851e","html_url":"https://github.com/versionHQ/multi-agent-system","commit_stats":null,"previous_names":["versionhq/agents","versionhq/multi-agent-system"],"tags_count":74,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versionHQ%2Fmulti-agent-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versionHQ%2Fmulti-agent-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versionHQ%2Fmulti-agent-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/versionHQ%2Fmulti-agent-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/versionHQ","download_url":"https://codeload.github.com/versionHQ/multi-agent-system/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248111870,"owners_count":21049577,"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":["agentic-ai","autonomous-agents","composiotool","docling","graph-theory","langchain","litellm","matplotlib","mem0ai","multi-agent-systems","multi-step-reasoning","networkx","orchestration-framework","pydantic","pygraphviz","python3","rag","self-directed-learning"],"created_at":"2024-12-07T22:07:57.836Z","updated_at":"2025-10-08T16:53:30.135Z","avatar_url":"https://github.com/versionHQ.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Overview\n\n[![DL](https://img.shields.io/badge/Download-30K+-red)](https://clickpy.clickhouse.com/dashboard/versionhq)\n![MIT license](https://img.shields.io/badge/License-MIT-green)\n[![Publisher](https://github.com/versionHQ/multi-agent-system/actions/workflows/publish.yml/badge.svg)](https://github.com/versionHQ/multi-agent-system/actions/workflows/publish.yml)\n![PyPI](https://img.shields.io/badge/PythonSDK-v1.2.4+-blue)\n![python ver](https://img.shields.io/badge/Python-3.11|3.12|3.13-purple)\n![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)\n\n\nA Python framework for autonomous agent networks that handle task automation with multi-step reasoning.\n\n**Visit:**\n\n- [Playground](https://versi0n.io/)\n- [Documentation](https://versionhq.github.io/multi-agent-system/)\n- [Github](https://github.com/versionHQ/)\n- [Python SDK](https://pypi.org/project/versionhq/)\n\n\u003chr /\u003e\n\n## Table of Content\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Key Features](#key-features)\n  - [Agent Network](#agent-network)\n  - [Graph Theory Concept](#graph-theory-concept)\n  - [Task Graph](#task-graph)\n  - [Optimization](#optimization)\n- [Quick Start](#quick-start)\n  - [Package installation](#package-installation)\n  - [Launching an agent](#launching-an-agent)\n  - [Automating workflows](#automating-workflows)\n  - [Executing a single task](#executing-a-single-task)\n  - [Supervising agents](#supervising-agents)\n- [Technologies Used](#technologies-used)\n- [Project Structure](#project-structure)\n- [Setting Up Your Project](#setting-up-your-project)\n  - [Installing package manager](#installing-package-manager)\n  - [Installing dependencies](#installing-dependencies)\n  - [Adding env secrets to .env file](#adding-env-secrets-to-env-file)\n- [Contributing](#contributing)\n  - [Steps](#steps)\n  - [Package Management with uv](#package-management-with-uv)\n  - [Pre-Commit Hooks](#pre-commit-hooks)\n  - [Documentation](#documentation)\n- [Trouble Shooting](#trouble-shooting)\n- [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\u003chr /\u003e\n\n## Key Features\n\n`versionhq` is a Python framework designed for automating complex, multi-step tasks using autonomous agent networks.\n\nUsers can either configure their agents and network manually or allow the system to automatically manage the process based on provided task goals.\n\n\n###  Agent Network\n\nAgents adapt their formation based on task complexity.\n\nYou can specify a desired formation or allow the agents to determine it autonomously (default).\n\n\n|                 | **Solo Agent**  | **Supervising**  | **Squad**         | **Random**      |\n| :---            | :---            | :---             | :---              | :---            |\n| **Formation**   | \u003cimg src=\"https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/rbgxttfoeqqis1ettlfz.png\" alt=\"solo\" width=\"200\"\u003e | \u003cimg src=\"https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/zhungor3elxzer5dum10.png\" alt=\"solo\" width=\"200\"\u003e | \u003cimg src=\"https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/dnusl7iy7kiwkxwlpmg8.png\" alt=\"solo\" width=\"200\"\u003e | \u003cimg src=\"https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/sndpczatfzbrosxz9ama.png\" alt=\"solo\" width=\"200\"\u003e |\n| **Usage**       | \u003cul\u003e\u003cli\u003eA single agent with tools, knowledge, and memory.\u003c/li\u003e\u003cli\u003eWhen self-learning mode is on - it will turn into **Random** formation.\u003c/li\u003e\u003c/ul\u003e | \u003cul\u003e\u003cli\u003eLeader agent gives directions, while sharing its knowledge and memory.\u003c/li\u003e\u003cli\u003eSubordinates can be solo agents or networks.\u003c/li\u003e\u003c/ul\u003e | \u003cul\u003e\u003cli\u003eShare tasks, knowledge, and memory among network members.\u003c/li\u003e\u003c/ul\u003e | \u003cul\u003e\u003cli\u003eA single agent handles tasks, asking help from other agents without sharing its memory or knowledge.\u003c/li\u003e\u003c/ul\u003e |\n| **Use case**    | An email agent drafts promo message for the given audience. | The leader agent strategizes an outbound campaign plan and assigns components such as media mix or message creation to subordinate agents. | An email agent and social media agent share the product knowledge and deploy multi-channel outbound campaign. | 1. An email agent drafts promo message for the given audience, asking insights on tones from other email agents which oversee other clusters. 2. An agent calls the external agent to deploy the campaign. |\n\n\u003chr /\u003e\n\n### Graph Theory Concept\n\nTo completely automate task workflows, agents will build a `task-oriented network` by generating `nodes` that represent tasks and connecting them with dependency-defining `edges`.\n\nEach node is triggered by specific events and executed by an assigned agent once all dependencies are met.\n\nWhile the network automatically reconfigures itself, you retain the ability to direct the agents using `should_reform` variable.\n\n\nThe following code snippet explicitly demonstrates the `TaskGraph` and its visualization, saving the diagram to the `uploads` directory.\n\n```python\nimport versionhq as vhq\n\ntask_graph = vhq.TaskGraph(directed=False, should_reform=True) # triggering auto formation\n\ntask_a = vhq.Task(description=\"Research Topic\")\ntask_b = vhq.Task(description=\"Outline Post\")\ntask_c = vhq.Task(description=\"Write First Draft\")\n\nnode_a = task_graph.add_task(task=task_a)\nnode_b = task_graph.add_task(task=task_b)\nnode_c = task_graph.add_task(task=task_c)\n\ntask_graph.add_dependency(\n   node_a.identifier, node_b.identifier,\n   dependency_type=vhq.DependencyType.FINISH_TO_START, weight=5, description=\"B depends on A\"\n)\ntask_graph.add_dependency(\n   node_a.identifier, node_c.identifier,\n   dependency_type=vhq.DependencyType.FINISH_TO_FINISH, lag=1, required=False, weight=3\n)\n\n# To visualize the graph:\ntask_graph.visualize()\n\n# To start executing nodes:\nlatest_output, outputs = task_graph.activate()\n\nassert isinstance(last_task_output, vhq.TaskOutput)\nassert [k in task_graph.nodes.keys() and v and isinstance(v, vhq.TaskOutput) for k, v in outputs.items()]\n```\n\n\u003chr /\u003e\n\n### Task Graph\n\nA `TaskGraph` represents tasks as `nodes` and their execution dependencies as `edges`, automating rule-based execution.\n\n`Agent Networks` can handle `TaskGraph` objects by optimizing their formations.\n\n\u003cimg src=\"https://res.cloudinary.com/dfeirxlea/image/upload/v1739337639/pj_m_home/zfg4ccw1m1ww1tpnb0pa.png\" width=\"300px\"\u003e\n\n\u003chr /\u003e\n\n### Optimization\n\nAutonomous agents are model-agnostic and can leverage their own and their peers' knowledge sources, memories, and tools.\n\nAgents are optimized during network formation, but customization is possible before or after.\n\nThe following code snippet demonstrates agent customization:\n\n```python\nimport versionhq as vhq\n\nagent = vhq.Agent(role=\"Marketing Analyst\")\n\n# update the agent\nagent.update(\n   llm=\"gemini-2.0\", # updating LLM (Valid llm_config will be inherited to the new LLM.)\n   tools=[vhq.Tool(func=lambda x: x)], # adding tools\n   max_rpm=3,\n   knowledge_sources=[\"\u003cKC1\u003e\", \"\u003cKS2\u003e\"], # adding knowledge sources. This will trigger the storage creation.\n   memory_config={\"user_id\": \"0001\"}, # adding memories\n   dummy=\"I am dummy\" # \u003c- invalid field will be automatically ignored\n)\n```\n\n\u003chr /\u003e\n\n## Quick Start\n\n### Package installation\n\n```\npip install versionhq\n```\n\n(Python 3.11 | 3.12 | 3.13)\n\n\n### Launching an agent\n\n\n```python\nimport versionhq as vhq\n\nagent = vhq.Agent(role=\"Marketer\")\nres = agent.start()\n\nassert isinstance(res, vhq.TaskOutput) # contains agent's response in text, JSON, Pydantic formats with usage recordes and eval scores.\n```\n\n\n### Automating workflows\n\n```python\nimport versionhq as vhq\n\nnetwork = vhq.form_agent_network(\n   task=\"draft a promo plan\",\n   expected_outcome=\"marketing plan, budget, KPI targets\",\n)\nres, tg = network.launch()\n\nassert isinstance(res, vhq.TaskOutput) # the latest output from the workflow\nassert isinstance(tg, vhq.TaskGraph) # contains task nodes and edges that connect the nodes with dep-met conditions\n```\n\n\n### Executing a single task\n\nYou can simply build and execute a task using `Task` class.\n\n```python\nimport versionhq as vhq\nfrom pydantic import BaseModel\n\nclass CustomOutput(BaseModel):\n   test1: str\n   test2: list[str]\n\ndef dummy_func(message: str, **kwargs) -\u003e str:\n   test1 = kwargs[\"test1\"] if kwargs and \"test1\" in kwargs else \"\"\n   test2 = kwargs[\"test2\"] if kwargs and \"test2\" in kwargs else \"\"\n   if test1 and test2:\n      return f\"\"\"{message}: {test1}, {\", \".join(test2)}\"\"\"\n\ntask = vhq.Task(\n   description=\"Amazing task\",\n   response_schema=CustomOutput,\n   callback=dummy_func,\n   callback_kwargs=dict(message=\"Hi! Here is the result: \")\n)\n\nres = task.execute(context=\"testing a task function\")\nassert isinstance(res, vhq.TaskOutput)\n```\n\n\n### Supervising agents\n\nTo create an agent network with one or more manager agents, designate members using the `is_manager` tag.\n\n```python\nimport versionhq as vhq\n\nagent_a = vhq.Agent(role=\"Member\", llm=\"gpt-4o\")\nagent_b = vhq.Agent(role=\"Leader\", llm=\"gemini-2.0\")\n\ntask_1 = vhq.Task(\n   description=\"Analyze the client's business model.\",\n   response_schema=[vhq.ResponseField(title=\"test1\", data_type=str, required=True),],\n   allow_delegation=True\n)\n\ntask_2 = vhq.Task(\n   description=\"Define a cohort.\",\n   response_schema=[vhq.ResponseField(title=\"test1\", data_type=int, required=True),],\n   allow_delegation=False\n)\n\nnetwork =vhq.AgentNetwork(\n   members=[\n      vhq.Member(agent=agent_a, is_manager=False, tasks=[task_1]),\n      vhq.Member(agent=agent_b, is_manager=True, tasks=[task_2]), # Agent B as a manager\n   ],\n)\nres, tg = network.launch()\n\nassert isinstance(res, vhq.NetworkOutput)\nassert not [item for item in task_1.processed_agents if \"vhq-Delegated-Agent\" == item]\nassert [item for item in task_1.processed_agents if \"agent b\" == item]\n```\n\nThis will return a list with dictionaries with keys defined in the `ResponseField` of each task.\n\nTasks can be delegated to a manager, peers within the agent network, or a completely new agent.\n\n\u003chr /\u003e\n\n## Technologies Used\n\n**Schema, Data Validation**\n\n* [Pydantic](https://docs.pydantic.dev/latest/): Data validation and serialization library for Python.\n* [Upstage](https://console.upstage.ai/docs/getting-started/overview): Document processer for ML tasks. (Use `Document Parser API` to extract data from documents)\n* [Docling](https://ds4sd.github.io/docling/): Document parsing\n\n**Workflow, Task Graph**\n\n* [NetworkX](https://networkx.org/documentation/stable/reference/introduction.html): A Python package to analyze, create, and manipulate complex graph networks. Ref. [Gallary](https://networkx.org/documentation/latest/auto_examples/index.html)\n* [Matplotlib](https://matplotlib.org/stable/index.html): For graph visualization.\n* [Graphviz](https://graphviz.org/about/): For graph visualization.\n\n**LLM Curation**\n\n* [LiteLLM](https://docs.litellm.ai/docs/providers): LLM orchestration platform\n\n**Tools**\n\n* [Composio](https://composio.dev/): Conect RAG agents with external tools, Apps, and APIs to perform actions and receive triggers. We use [tools](https://composio.dev/tools) and [RAG tools](https://app.composio.dev/app/ragtool) from Composio toolset.\n\n\n**Storage**\n\n* [mem0ai](https://docs.mem0.ai/quickstart#install-package): Agents' memory storage and management.\n* [Chroma DB](https://docs.trychroma.com/): Vector database for storing and querying usage data.\n* [SQLite](https://www.sqlite.org/docs.html): C-language library to implements a small SQL database engine.\n\n\n**Deployment**\n\n* [uv](https://docs.astral.sh/uv/): Python package installer and resolver\n* [pre-commit](https://pre-commit.com/): Manage and maintain pre-commit hooks\n* [setuptools](https://pypi.org/project/setuptools/): Build python modules\n\n\u003chr /\u003e\n\n## Project Structure\n\n```\n.\n.github\n└── workflows/                # Github actions\n│\ndocs/                         # Documentation\nmkdocs.yml                    # MkDocs config\n│\nsrc/\n└── versionhq/                # Orchestration framework package\n│     ├── agent/              # Core components\n│     └── llm/\n│     └── task/\n│     └── tool/\n│     └── ...\n│\n└──tests/                     # Pytest - by core component and use cases in the docs\n│     └── agent/\n│     └── llm/\n│     └── ...\n│\n└── .diagrams/  [.gitignore]  # Local directory to store graph diagrams\n│\n└── .logs/      [.gitignore]  # Local directory to store error/warning logs for debugging\n│\n│\npyproject.toml                # Project config\n.env.sample                   # sample .env file\n\n```\n\n\u003chr /\u003e\n\n## Setting Up Your Project\n\n### Installing package manager\n\n   For MacOS:\n\n   ```\n   brew install uv\n   ```\n\n   For Ubuntu/Debian:\n   ```\n   sudo apt-get install uv\n   ```\n\n\n### Installing dependencies\n\n   ```\n   uv venv\n   source .venv/bin/activate\n   uv lock --upgrade\n   uv sync --all-extras\n   ```\n\n   - AssertionError/module mismatch errors: Set up default Python version using `.pyenv`\n      ```\n      pyenv install 3.12.8\n      pyenv global 3.12.8  (optional: `pyenv global system` to get back to the system default ver.)\n      uv python pin 3.12.8\n      echo 3.12.8 \u003e\u003e .python-version\n      ```\n\n   - `pygraphviz` related errors: Run the following commands:\n      ```\n      brew install graphviz\n      uv pip install --config-settings=\"--global-option=build_ext\" \\\n      --config-settings=\"--global-option=-I$(brew --prefix graphviz)/include/\" \\\n      --config-settings=\"--global-option=-L$(brew --prefix graphviz)/lib/\" \\\n      pygraphviz\n      ```\n\n      * If the error continues, skip pygraphviz installation by:\n      ```\n      uv sync --all-extras --no-extra pygraphviz\n      ```\n\n### Adding env secrets to .env file\n\nCreate `.env` file in the project root and add secret vars following `.env.sample` file.\n\n\n\u003chr /\u003e\n\n## Contributing\n\n`versionhq` is a open source project.\n\n### Steps\n\n1. Create your feature branch (`git checkout -b feature/your-amazing-feature`)\n\n2. Create amazing features\n\n3. Add a test funcition to the `tests` directory and run **pytest**.\n\n   - Add secret values defined in `.github/workflows/run_test.yml` to your Github `repository secrets` located at settings \u003e secrets \u0026 variables \u003e Actions.\n\n   - Run a following command:\n      ```\n      uv run pytest tests -vv --cache-clear\n      ```\n\n   **Building a new pytest function**\n\n   * Files added to the `tests` directory must end in `_test.py`.\n\n   * Test functions within the files must begin with `test_`.\n\n   * Pytest priorities are `1. playground \u003e 2. docs use cases \u003e 3. other features`\n\n\n4. Update `docs` accordingly.\n\n5. Pull the latest version of source code from the main branch (`git pull origin main`) *Address conflicts if any.\n\n6. Commit your changes (`git add .` / `git commit -m 'Add your-amazing-feature'`)\n\n7. Push to the branch (`git push origin feature/your-amazing-feature`)\n\n8. Open a pull request\n\n\n**Optional**\n\n* Flag with `#! REFINEME` for any improvements needed and `#! FIXME` for any errors.\n\n* `Playground` is available at `https://versi0n.io`.\n\n\n### Package Management with uv\n\n- Add a package: `uv add \u003cpackage\u003e`\n- Remove a package: `uv remove \u003cpackage\u003e`\n- Run a command in the virtual environment: `uv run \u003ccommand\u003e`\n\n* After updating dependencies, update `requirements.txt` accordingly or run `uv pip freeze \u003e requirements.txt`\n\n\n### Pre-Commit Hooks\n\n1. Install pre-commit hooks:\n   ```\n   uv run pre-commit install\n   ```\n\n2. Run pre-commit checks manually:\n   ```\n   uv run pre-commit run --all-files\n   ```\n\nPre-commit hooks help maintain code quality by running checks for formatting, linting, and other issues before each commit.\n\n* To skip pre-commit hooks\n   ```\n   git commit --no-verify -m \"your-commit-message\"\n   ```\n\n### Documentation\n\n* To edit the documentation, see `docs` repository and edit the respective component.\n\n* We use `mkdocs` to update the docs. You can run the docs locally at http://127.0.0.1:8000/.\n\n   ```\n   uv run python3 -m mkdocs serve --clean\n   ```\n\n* To add a new page, update `mkdocs.yml` in the root. Refer to [MkDocs documentation](https://squidfunk.github.io/mkdocs-material/getting-started/) for more details.\n\n\u003chr /\u003e\n\n## Trouble Shooting\n\nCommon issues and solutions:\n\n* API key errors: Ensure all API keys in the `.env` file are correct and up to date. Make sure to add `load_dotenv()` on the top of the python file to apply the latest environment values.\n\n* Database connection issues: Check if the Chroma DB is properly initialized and accessible.\n\n* Memory errors: If processing large contracts, you may need to increase the available memory for the Python process.\n\n* Issues related to dependencies: `rm -rf uv.lock`, `uv cache clean`, `uv venv`, and run `uv pip install -r requirements.txt -v`.\n\n* Issues related to `torch` installation: Add optional dependencies by `uv add versionhq[torch]`.\n\n* Issues related to agents and other systems: Check `.logs` directory located at the root of the project directory for error messages and stack traces.\n\n* Issues related to `Python quit unexpectedly`: Check [this stackoverflow article](https://stackoverflow.com/questions/59888499/macos-catalina-python-quit-unexpectedly-error).\n\n* `reportMissingImports` error from pyright after installing the package: This might occur when installing new libraries while VSCode is running. Open the command pallete (ctrl + shift + p) and run the Python: Restart language server task.\n\n\u003chr /\u003e\n\n## Frequently Asked Questions (FAQ)\n**Q. Where can I see if the agent is working?**\n\nA. Visit [playground](https://versi0n.io).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversionhq%2Fmulti-agent-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fversionhq%2Fmulti-agent-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversionhq%2Fmulti-agent-system/lists"}