{"id":48789242,"url":"https://github.com/hsiangnianian/supervisors.rs","last_synced_at":"2026-04-13T19:02:29.889Z","repository":{"id":348508852,"uuid":"1198386359","full_name":"HsiangNianian/supervisors.rs","owner":"HsiangNianian","description":"Agent framework written in rust  and  built for Rust/Python","archived":false,"fork":false,"pushed_at":"2026-04-03T07:57:00.000Z","size":391,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T11:48:11.110Z","etag":null,"topics":["a2a","agent","ai","deerflow","fc","langchain","langgraph","llm","mcp","rag","skills"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HsiangNianian.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T11:28:45.000Z","updated_at":"2026-04-03T07:57:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"0ecf3da2-3847-42b2-bd74-1a5019fcdfb2","html_url":"https://github.com/HsiangNianian/supervisors.rs","commit_stats":null,"previous_names":["hsiangnianian/supervisor.rs","hsiangnianian/supervisors.rs"],"tags_count":null,"template":false,"template_full_name":"HydroRoll-Team/pyo3-project-template","purl":"pkg:github/HsiangNianian/supervisors.rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HsiangNianian%2Fsupervisors.rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HsiangNianian%2Fsupervisors.rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HsiangNianian%2Fsupervisors.rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HsiangNianian%2Fsupervisors.rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HsiangNianian","download_url":"https://codeload.github.com/HsiangNianian/supervisors.rs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HsiangNianian%2Fsupervisors.rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31766482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T15:25:13.801Z","status":"ssl_error","status_checked_at":"2026-04-13T15:25:09.162Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["a2a","agent","ai","deerflow","fc","langchain","langgraph","llm","mcp","rag","skills"],"created_at":"2026-04-13T19:02:25.200Z","updated_at":"2026-04-13T19:02:29.879Z","avatar_url":"https://github.com/HsiangNianian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# supervisors.rs\n\n**A composable multi-agent framework powered by Rust and Python.**\n\nBuild, orchestrate, and scale intelligent agents with a high-performance\nRust core and a flexible Python API.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)\n[![Rust](https://img.shields.io/badge/Rust-stable-orange.svg)](https://www.rust-lang.org/)\n[![Docs](https://readthedocs.org/projects/supervisors-rs/badge/?version=latest)](https://supervisors.hydroroll.team/)\n\n[Getting Started](#getting-started) |\n[Agent Types](#agent-types) |\n[Examples](#examples) |\n[Extensions](#extensions) |\n[API Reference](#api-reference) |\n[Contributing](#contributing)\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\n**supervisors.rs** is a cross-language agent framework designed for building\nproduction-grade AI agent systems.  The core is written in Rust for\nperformance and safety, while the Python API provides ergonomic abstractions\nfor rapid development.\n\nThe framework supports four fundamental agent patterns that can be used\nindependently or composed together to solve complex, real-world problems:\n\n| Pattern | Description | Use Case |\n|---------|-------------|----------|\n| **Loop Agent** | LLM + iterative reasoning loop | ReAct agents, chain-of-thought, self-refinement |\n| **Pipeline Agent** | Sequential stage-based processing | ETL, data transformation, multi-step workflows |\n| **Supervisors + SubAgents** | Hierarchical delegation | Task routing, modular decomposition, microservices |\n| **Multi-Agent** | Collaborative peer agents | Research teams, debate, consensus-building |\n\nAll four patterns are composable -- a `SupervisorsAgent` can manage\n`MultiAgent` teams as sub-agents, a `LoopAgent` can embed pipeline logic,\nand any agent type can be registered on the same `Supervisors` instance.\n\n---\n\n## Getting Started\n\n### Installation\n\nBuild and install with [maturin](https://github.com/PyO3/maturin):\n\n```bash\npip install maturin\nmaturin develop          # editable install for development\n```\n\n### Quick Start\n\n```python\nfrom supervisors import Agent, Supervisor, Message\n\nclass GreeterAgent(Agent):\n    def handle_message(self, msg: Message) -\u003e None:\n        print(f\"Hello from '{self.name}'! You said: {msg.content}\")\n\nsup = Supervisor()\ngreeter = GreeterAgent(\"greeter\")\ngreeter.register(sup)\n\nsup.send(Message(\"user\", \"greeter\", \"Hi there!\"))\nsup.run_once()\n# Output: Hello from 'greeter'! You said: Hi there!\n```\n\n---\n\n## Agent Types\n\n### Loop Agent\n\nThe `LoopAgent` runs an iterative reasoning loop over each incoming message.\nOverride the `step()` method to define per-iteration logic.\n\n```python\nfrom supervisors import LoopAgent, Message\n\nclass ReasoningAgent(LoopAgent):\n    def step(self, state):\n        state[\"count\"] = state.get(\"count\", 0) + 1\n        if state[\"count\"] \u003e= 3:\n            state[\"done\"] = True\n            state[\"result\"] = \"Reasoning complete.\"\n        return state\n\nagent = ReasoningAgent(\"reasoner\", max_iterations=10)\nstate = agent.run_loop(Message(\"user\", \"reasoner\", \"Think about X\"))\nprint(state[\"result\"])\n```\n\n### Pipeline Agent\n\nThe `PipelineAgent` processes messages through an ordered sequence of\nstage functions.\n\n```python\nfrom supervisors import PipelineAgent, Message\n\ndef parse(ctx):\n    ctx[\"tokens\"] = ctx[\"input\"].split()\n    return ctx\n\ndef analyse(ctx):\n    ctx[\"count\"] = len(ctx[\"tokens\"])\n    return ctx\n\nagent = PipelineAgent(\"analyser\", stages=[parse, analyse])\nresult = agent.run_pipeline(Message(\"user\", \"analyser\", \"hello world\"))\nprint(result[\"count\"])  # 2\n```\n\n### Supervisor + SubAgents\n\nThe `SupervisorAgent` routes incoming messages to specialised sub-agents\nbased on a routing function.\n\n```python\nfrom supervisors import Agent, SupervisorAgent, Message, Supervisor\n\nclass Worker(Agent):\n    def handle_message(self, msg):\n        print(f\"[{self.name}] handling: {msg.content}\")\n\nsup = Supervisor()\nmanager = SupervisorAgent(\n    \"manager\",\n    router=lambda msg: \"worker_a\" if \"urgent\" in msg.content else \"worker_b\",\n)\nmanager.add_sub_agent(Worker(\"worker_a\"))\nmanager.add_sub_agent(Worker(\"worker_b\"))\nmanager.register(sup)\n\nsup.send(Message(\"user\", \"manager\", \"urgent: fix production\"))\nsup.run_once()\n# Output: [worker_a] handling: urgent: fix production\n```\n\n### Multi-Agent\n\nThe `MultiAgent` coordinates a group of peer agents that collaborate\nto solve problems.\n\n```python\nfrom supervisors import Agent, MultiAgent, Message, Supervisor\n\nclass Researcher(Agent):\n    def handle_message(self, msg):\n        print(f\"[{self.name}] researching: {msg.content}\")\n\nsup = Supervisor()\nteam = MultiAgent(\n    \"research_team\",\n    members=[Researcher(\"alice\"), Researcher(\"bob\")],\n    max_rounds=5,\n)\nteam.register(sup)\n\nsup.send(Message(\"user\", \"research_team\", \"Investigate topic X\"))\nsup.run_once()\n```\n\n### Composing Agents\n\nThe real power emerges when you combine patterns.  For example, a\n`SupervisorAgent` can manage `MultiAgent` teams as sub-agents:\n\n```python\nfrom supervisors import (\n    Agent, MultiAgent, SupervisorAgent, Message, Supervisor,\n)\n\nclass Specialist(Agent):\n    def handle_message(self, msg):\n        print(f\"[{self.name}] working on: {msg.content}\")\n\n# Build a collaborative team.\nteam = MultiAgent(\"dev_team\", members=[\n    Specialist(\"frontend\"),\n    Specialist(\"backend\"),\n])\n\n# Wrap it in a hierarchical supervisor.\nmanager = SupervisorAgent(\"manager\", router=lambda msg: \"dev_team\")\nmanager.add_sub_agent(team)\n\nsup = Supervisor()\nmanager.register(sup)\nsup.send(Message(\"cto\", \"manager\", \"Build feature X\"))\nsup.run_once()\n```\n\n---\n\n## Examples\n\nEach example is a self-contained project in the `examples/` directory:\n\n| Example | Pattern | Description |\n|---------|---------|-------------|\n| [`loop/`](examples/loop/) | Loop Agent | Customer support with iterative reasoning |\n| [`pipeline/`](examples/pipeline/) | Pipeline Agent | Log processing with sequential stages |\n| [`supervisor_subagent/`](examples/supervisor_subagent/) | Supervisor + SubAgents | Content moderation with routing |\n| [`multi_agent/`](examples/multi_agent/) | Multi-Agent | Collaborative research team |\n| [`composite/`](examples/composite/) | Supervisor + Multi-Agent | DevOps incident response system |\n| [`a2a/`](examples/a2a/) | A2A + ReAct | Multi-agent chat with OpenAI (requires API key) |\n\nRun any example:\n\n```bash\ncd examples/loop\npython main.py\n```\n\n---\n\n## Extensions\n\nExtensions add capabilities to any agent via the plugin system.  Load\nextensions with `agent.use(extension)`:\n\n### RAG (Retrieval-Augmented Generation)\n\n```python\nfrom supervisors.ext.rag import RAGExtension\n\nclass MyRAG(RAGExtension):\n    def __init__(self):\n        super().__init__(auto_retrieve=True, top_k=5)\n        self._store = []\n\n    def retrieve(self, query, top_k=None):\n        return [d for d in self._store if query.lower() in d.lower()]\n\n    def add_documents(self, docs, **kwargs):\n        self._store.extend(docs)\n\nagent.use(MyRAG())\n```\n\n### Function Calling\n\n```python\nfrom supervisors.ext.function_calling import FunctionCallingExtension\n\nfc = FunctionCallingExtension()\n\n@fc.tool(description=\"Add two numbers\")\ndef add(a: int, b: int) -\u003e int:\n    return a + b\n\nagent.use(fc)\nresult = fc.call_tool(\"add\", a=1, b=2)  # returns 3\n```\n\n### MCP (Model Context Protocol)\n\n```python\nfrom supervisors.ext.mcp import MCPExtension\n\nmcp = MCPExtension(server_url=\"http://localhost:8080\")\n\n@mcp.mcp_tool(description=\"Reverse a string\")\ndef reverse(text: str) -\u003e str:\n    return text[::-1]\n\nagent.use(mcp)\n```\n\n### Skills\n\n```python\nfrom supervisors.ext.skills import SkillsExtension\n\nskills = SkillsExtension()\n\n@skills.skill\ndef summarise(agent, msg):\n    return f\"Summary: {msg.content[:50]}...\"\n\nagent.use(skills)\n```\n\n### A2A (Agent-to-Agent)\n\nBeyond the built-in A2A messaging (`agent.send()`), the A2A extension\nadds broadcast, discovery, and request/reply patterns:\n\n```python\nfrom supervisors.ext.a2a import A2AExtension\n\na2a = A2AExtension()\nagent.use(a2a)\n\na2a.broadcast(agent, \"Hello everyone!\")\nnames = a2a.discover_agents(agent)\n```\n\n---\n\n## API Reference\n\n### Core Types\n\n| Type | Description |\n|------|-------------|\n| `Message(sender, recipient, content)` | A message exchanged between agents.  Supports metadata via `set_meta`/`get_meta`. |\n| `Supervisor()` | Manages agents and routes messages.  Backed by a tokio async runtime. |\n| `Agent(name)` | Base class for all agents.  Subclass and override `handle_message`. |\n| `LoopAgent(name, max_iterations=10)` | Agent with iterative reasoning loop.  Override `step()`. |\n| `PipelineAgent(name, stages=[])` | Agent with sequential processing stages. |\n| `SupervisorAgent(name, router=None)` | Hierarchical agent that delegates to sub-agents. |\n| `MultiAgent(name, members=[], max_rounds=10)` | Collaborative group of peer agents. |\n| `Extension` | Base class for agent extension plugins. |\n\n### Supervisor Methods\n\n| Method | Description |\n|--------|-------------|\n| `register(name, handler)` | Register an agent with a message handler. |\n| `unregister(name) -\u003e bool` | Remove an agent. Returns `True` if it existed. |\n| `send(msg)` | Enqueue a message for delivery. |\n| `run_once() -\u003e int` | Deliver all pending messages.  Returns count processed. |\n| `dispatch_async() -\u003e int` | Concurrent dispatch via tokio. |\n| `agent_names() -\u003e list[str]` | Names of all registered agents. |\n| `agent_count() -\u003e int` | Number of registered agents. |\n| `pending_count(name) -\u003e int or None` | Queued messages for an agent. |\n\n### Agent Methods\n\n| Method | Description |\n|--------|-------------|\n| `handle_message(msg)` | Override to define agent behaviour. |\n| `register(supervisor)` | Register with a supervisor. |\n| `unregister() -\u003e bool` | Remove from supervisor. |\n| `send(recipient, content)` | Send a message to another agent (A2A). |\n| `use(extension) -\u003e Agent` | Load an extension plugin. |\n| `remove_extension(name) -\u003e bool` | Remove an extension. |\n\n---\n\n## Architecture\n\n```\n+-------------------------------------------+\n|              Python Layer                 |\n|                                           |\n|  LoopAgent   PipelineAgent               |\n|  SupervisorAgent   MultiAgent            |\n|  Agent + Extensions (RAG, MCP, ...)      |\n+-------------------------------------------+\n|            Rust Core (PyO3)               |\n|                                           |\n|  Message    Supervisor    ToolRegistry    |\n|  (tokio async runtime for concurrency)   |\n+-------------------------------------------+\n```\n\nThe Rust core provides:\n- **Message routing** with fault-tolerant delivery\n- **Async dispatch** via tokio for concurrent agent execution\n- **Tool registry** for high-performance tool specification storage\n\nThe Python layer provides:\n- **Four composable agent patterns** for any business scenario\n- **Extension plugin system** for modular capabilities\n- **Rich lifecycle hooks** for logging, metrics, and customisation\n\n---\n\n## Contributing\n\nContributions are welcome! Please read the [contributing guidelines](CONTRIBUTING.md)\nbefore submitting a pull request.\n\n```bash\n# Development setup\ngit clone https://github.com/HsiangNianian/supervisors.rs.git\ncd supervisors.rs\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install maturin pytest\nmaturin develop --skip-install\npip install -e . --no-build-isolation\n\n# Run tests\npython -m pytest tests/ -v\n```\n\n---\n\n## License\n\n[AGPLv3](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhsiangnianian%2Fsupervisors.rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhsiangnianian%2Fsupervisors.rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhsiangnianian%2Fsupervisors.rs/lists"}