{"slug": "how-to-build-a-supervisor-agent-architecture-without-frameworks", "title": "How to Build a Supervisor Agent Architecture Without Frameworks", "summary": "This article explains how to build a supervisor-based multi-agent architecture in pure Python without using external frameworks. It describes the \"Supervisor Pattern,\" where a central orchestrator coordinates specialized executors (tools, workflows, or agents) that all follow a shared execution interface, solving the problem of a single agent becoming an overloaded monolith. The author provides code examples for creating a standardized `Executable` abstract class and implementing focused components like a search tool, file analysis tool, research agent, and coding agent.", "body_md": "A few days ago, I wrote about building an agentic pipeline from scratch in pure Python. The idea was intentionally simple: receive a task, invoke tools, and generate a response.\n\nThat architecture works surprisingly well for linear workflows. But real-world AI systems become complicated much faster than most tutorials suggest.\n\nEventually, one agent is no longer enough. A single reasoning loop starts accumulating too many responsibilities. The prompt grows uncontrollably, tool definitions pile up, execution logic becomes tangled, and debugging turns into a nightmare. What started as a clean “AI agent” slowly becomes a monolith trying to do everything at once.\n\nThis is where the Supervisor Pattern becomes useful.\n\nInstead of relying on one giant agent, we introduce a central orchestrator responsible for coordinating specialized executors. Some executors may be tools, others may be reusable workflows, and others may be autonomous agents focused on a specific domain.\n\nConceptually, this is much closer to how modern AI systems operate internally. Systems like GitHub Copilot, Claude, and many enterprise AI platforms are not simply “one prompt talking to one model.” A significant part of the engineering complexity comes from orchestration: deciding what should execute, when it should execute, and how results should be combined.\n\nIn this article, we will build a simplified supervisor-based multi-agent architecture entirely in pure Python without relying on orchestration frameworks.\n\n## From Single Agents to Execution Runtimes\n\nMost beginner agent tutorials follow roughly the same structure. A user sends a task, the agent reasons about it, invokes tools when necessary, and eventually produces an answer.\n\nAt small scale, this works well enough.\n\nBut imagine a more realistic request:\n\n```\nResearch vector databases,\ngenerate implementation examples,\nanalyze project files,\nand review the generated solution.\n```\n\nA single agent now has to:\n\n- reason about research,\n- inspect files,\n- generate code,\n- review output,\n- manage tools,\n- maintain context,\n- and orchestrate execution order.\n\nThe problem is not necessarily model capability. The problem is architecture.\n\nAt some point, the “agent” stops being just a reasoning unit and accidentally becomes a workflow engine.\n\nThe Supervisor Pattern solves this by separating orchestration from execution.\n\nInstead of one overloaded agent, we create specialized executors coordinated by a supervisor.\n\nThe architecture looks like this:\n\n```\n                    Supervisor\n                         |\n        +----------------+----------------+\n        |                |                |\n     Tools            Skills           Agents\n        |                |                |\n   File Search      Ticket Workflow   Coding Agent\n   Web Search       Log Analysis      Research Agent\n```\n\nThe important idea here is that the supervisor does not care whether it is invoking a tool, a workflow, or another agent. Everything follows the same execution contract.\n\n## Creating a Common Execution Interface\n\nOne of the simplest but most important architectural decisions is standardizing how execution works.\n\nInstead of creating separate orchestration logic for tools, agents, and workflows, we can define a shared interface:\n\n``` python\nfrom abc import ABC, abstractmethod\n\nclass Executable(ABC):\n\n    @abstractmethod\n    async def execute(self, task: str, context: dict):\n        pass\n```\n\nThis abstraction becomes surprisingly powerful.\n\nA search tool can implement it. A coding agent can implement it. A reusable workflow can implement it. To the supervisor, everything becomes just another executable component.\n\nThat greatly simplifies orchestration.\n\n## Building Specialized Executors\n\nNow let’s create a few executors with different responsibilities.\n\nWe will start with a simple search tool:\n\n``` python\nclass SearchTool(Executable):\n\n    async def execute(self, task, context):\n\n        return f\"\"\"\n        Searching documentation for:\n        {task}\n        \"\"\"\n```\n\nThen a file analysis tool:\n\n``` python\nclass FileAnalysisTool(Executable):\n\n    async def execute(self, task, context):\n\n        return f\"\"\"\n        Analyzing project files for:\n        {task}\n        \"\"\"\n```\n\nThese tools are intentionally small and focused. They represent atomic capabilities.\n\nNow we can create specialized agents.\n\nA research agent:\n\n``` python\nclass ResearchAgent(Executable):\n\n    async def execute(self, task, context):\n\n        return f\"\"\"\n        Research findings for:\n        {task}\n        \"\"\"\n```\n\nA coding agent:\n\n``` python\nclass CodingAgent(Executable):\n\n    async def execute(self, task, context):\n\n        return f\"\"\"\n        Generated implementation for:\n        {task}\n        \"\"\"\n```\n\nAnd finally, a review agent:\n\n``` python\nclass ReviewAgent(Executable):\n\n    async def execute(self, task, context):\n\n        return f\"\"\"\n        Code review completed for:\n        {task}\n        \"\"\"\n```\n\nThis separation of concerns is one of the biggest advantages of supervisor architectures. Each executor remains isolated and focused, which makes the overall system easier to scale and debug.\n\n## Dynamic Registration\n\nHardcoding dependencies quickly becomes painful as the number of executors grows.\n\nInstead, we can create a registry capable of dynamically storing and discovering executors at runtime.\n\n``` python\nclass Registry:\n\n    def __init__(self):\n\n        self.executables = {}\n\n    def register(\n        self,\n        name,\n        description,\n        executable_type,\n        instance\n    ):\n\n        self.executables[name] = {\n            \"description\": description,\n            \"type\": executable_type,\n            \"instance\": instance\n        }\n\n    def get(self, name):\n\n        return self.executables[name]\n\n    def list(self):\n\n        return self.executables\n```\n\nNow we can register everything dynamically:\n\n```\nregistry = Registry()\n\nregistry.register(\n    \"search_tool\",\n    \"Searches technical documentation\",\n    \"tool\",\n    SearchTool()\n)\n\nregistry.register(\n    \"file_analysis_tool\",\n    \"Analyzes project files\",\n    \"tool\",\n    FileAnalysisTool()\n)\n\nregistry.register(\n    \"research_agent\",\n    \"Performs research tasks\",\n    \"agent\",\n    ResearchAgent()\n)\n\nregistry.register(\n    \"coding_agent\",\n    \"Generates code\",\n    \"agent\",\n    CodingAgent()\n)\n\nregistry.register(\n    \"review_agent\",\n    \"Reviews implementations\",\n    \"agent\",\n    ReviewAgent()\n)\n```\n\nAt this point, the system starts feeling much more like a runtime instead of a simple chatbot wrapper.\n\n## Building the Supervisor\n\nThe supervisor is the heart of the architecture.\n\nIts responsibility is not necessarily to solve the task directly, but rather to decide which executors should participate in solving it.\n\nWe will start with a very simple planner:\n\n``` python\nclass Supervisor:\n\n    def __init__(self, registry):\n\n        self.registry = registry\n\n    async def plan(self, task):\n\n        selected = []\n\n        lower_task = task.lower()\n\n        if \"research\" in lower_task:\n            selected.append(\"research_agent\")\n\n        if \"implement\" in lower_task:\n            selected.append(\"coding_agent\")\n\n        if \"review\" in lower_task:\n            selected.append(\"review_agent\")\n\n        if \"search\" in lower_task:\n            selected.append(\"search_tool\")\n\n        return selected\n```\n\nThis planner is intentionally primitive. In production systems, this planning phase is often delegated to an LLM that returns structured execution plans.\n\nBut even this simplified version already demonstrates the architecture.\n\nThe supervisor receives a goal and decides dynamically which executors should participate.\n\n## Parallel Execution\n\nNow comes the most interesting part.\n\nInstead of executing everything sequentially, the supervisor can orchestrate independent tasks concurrently.\n\n``` python\nimport asyncio\n\nclass Supervisor:\n\n    def __init__(self, registry):\n\n        self.registry = registry\n\n    async def plan(self, task):\n\n        selected = []\n\n        lower_task = task.lower()\n\n        if \"research\" in lower_task:\n            selected.append(\"research_agent\")\n\n        if \"implement\" in lower_task:\n            selected.append(\"coding_agent\")\n\n        if \"review\" in lower_task:\n            selected.append(\"review_agent\")\n\n        if \"search\" in lower_task:\n            selected.append(\"search_tool\")\n\n        return selected\n\n    async def execute(self, task, context):\n\n        selected = await self.plan(task)\n\n        executions = []\n\n        for name in selected:\n\n            executable = self.registry.get(name)[\"instance\"]\n\n            executions.append(\n                executable.execute(task, context)\n            )\n\n        results = await asyncio.gather(*executions)\n\n        return results\n```\n\nThis changes the nature of the system completely.\n\nWe are no longer building a linear tool-calling loop. We are building an orchestration runtime capable of coordinating distributed execution.\n\nThat distinction matters a lot.\n\n## Running the System\n\nNow we can execute the entire pipeline:\n\n``` python\nasync def main():\n\n    supervisor = Supervisor(registry)\n\n    result = await supervisor.execute(\n        \"\"\"\n        Research vector databases,\n        search implementation examples,\n        implement a prototype,\n        and review the generated code\n        \"\"\",\n        {}\n    )\n\n    for item in result:\n        print(item)\n\nasyncio.run(main())\n```\n\nThe interesting part is not the mock outputs themselves. The interesting part is the orchestration model emerging underneath.\n\nThe supervisor analyzes the task, dynamically selects executors, parallelizes execution, and aggregates results back into a unified workflow.\n\nThat is much closer to how modern AI systems actually operate internally.\n\n## The Architectural Shift\n\nAt this point, the system has evolved far beyond a simple “AI chatbot.”\n\nThe supervisor is acting simultaneously as:\n\n- planner,\n- router,\n- scheduler,\n- orchestrator.\n\nThis is also why many production AI systems are significantly more complicated than “send prompt, receive response.”\n\nA large portion of the engineering complexity comes from:\n\n- orchestration,\n- execution management,\n- concurrency,\n- state propagation,\n- retries,\n- failure isolation,\n- observability.\n\nThe model itself is only one piece of the system.\n\n## Moving Toward LLM-Based Planning\n\nOur planner currently uses simple rule matching:\n\n```\nif \"review\" in task:\n    selected.append(\"review_agent\")\n```\n\nBut modern systems usually replace this with an LLM planner capable of generating structured execution plans.\n\nSomething like:\n\n```\nprompt = f\"\"\"\nTask:\n{task}\n\nAvailable executors:\n- research_agent\n- coding_agent\n- review_agent\n- search_tool\n\nReturn the executors required.\n\"\"\"\n```\n\nThe LLM might return:\n\n```\n{\n  \"executors\": [\n    \"research_agent\",\n    \"coding_agent\",\n    \"review_agent\"\n  ],\n  \"parallel\": true\n}\n```\n\nAt that point, the runtime becomes significantly more autonomous.\n\nThe supervisor is no longer following hardcoded execution paths. It is dynamically constructing execution graphs at runtime.\n\n## Production Realities\n\nThis is where things become genuinely difficult.\n\nOnce agents can invoke tools, workflows, and even other agents,\n\nthe runtime itself becomes the primary engineering challenge.\n\nYou suddenly need to think about:\n\n- recursion protection,\n- concurrency limits,\n- cancellation,\n- retries,\n- structured outputs,\n- tracing,\n- execution graphs,\n- timeout management.\n\nFor example, agents invoking agents can accidentally create infinite loops:\n\n``` php\nSupervisor -> ResearchAgent\nResearchAgent -> Supervisor\nSupervisor -> ResearchAgent\n```\n\nYou quickly realize that the difficult part of AI systems is often not model invocation.\n\n*The difficult part is building reliable orchestration around the model.*\n\n## Final Thoughts\n\nOnce you understand the Supervisor Pattern, you stop thinking about AI agents as isolated chatbots.\n\nYou start thinking in terms of execution runtimes, orchestration graphs, distributed reasoning, and autonomous workflows.\n\nThat shift in perspective changes everything.\n\nAnd interestingly, none of this requires a framework.\n\nUnderneath most orchestration libraries, the core execution model is still surprisingly simple:\n\n```\nawait executable.execute(task, context)\n```\n\nEverything else is architecture layered on top.", "url": "https://wpnews.pro/news/how-to-build-a-supervisor-agent-architecture-without-frameworks", "canonical_source": "https://dev.to/rafaeltedesco/how-to-build-a-supervisor-agent-architecture-without-frameworks-3g83", "published_at": "2026-05-23 02:31:03+00:00", "updated_at": "2026-05-23 03:04:27.526727+00:00", "lang": "en", "topics": ["artificial-intelligence", "machine-learning", "large-language-models", "developer-tools", "enterprise-software"], "entities": ["GitHub Copilot", "Claude"], "alternates": {"html": "https://wpnews.pro/news/how-to-build-a-supervisor-agent-architecture-without-frameworks", "markdown": "https://wpnews.pro/news/how-to-build-a-supervisor-agent-architecture-without-frameworks.md", "text": "https://wpnews.pro/news/how-to-build-a-supervisor-agent-architecture-without-frameworks.txt", "jsonld": "https://wpnews.pro/news/how-to-build-a-supervisor-agent-architecture-without-frameworks.jsonld"}}