System Overview
High-level topology of the home lab — agent roles, component boundaries, and how they connect.
Purpose
This page describes the high-level topology of the multi-agent home lab: what the primary components are, what each one is responsible for, and how they relate to each other.
Status: Implemented (architecture concept and primary workflow)
Agent roles
The system is organized around four logical agents and a user:
| Component | Role | Status |
|---|---|---|
| User | Initiates goals, requests, and decisions | — |
| Orchestration Agent | Planning, coordination, memory, review | Implemented |
| Code Execution Agent | Code generation and implementation | In use |
| Research Agent | Structured background research missions | Implemented |
| Media Agent | Entertainment automation and media playback | Implemented |
User
The user is the initiating actor. All goals, requests, and final decisions originate here. The Orchestration Agent acts as the primary interface between user intent and system execution.
Orchestration Agent
The Orchestration Agent is the control and coordination component. It:
- Receives goals and requests from the user
- Designs solutions and plans implementation work
- Prepares prompts and tasks for the Code Execution Agent
- Reviews and verifies the Code Execution Agent's output
- Delegates research tasks to the Research Agent
- Delegates media requests to the Media Agent
- Maintains memory and documentation
- Does not execute code directly
Code Execution Agent
The Code Execution Agent is the implementation execution layer. It receives explicitly scoped prompts from the Orchestration Agent, writes or modifies code, and returns output. It does not interact with git, does not push to remote repositories, and does not make production changes independently.
Research Agent
The Research Agent executes structured research missions in the background. It uses a file-based task queue and a multi-phase DAG pipeline to produce typed artifact files and a final Markdown report for each mission.
Media Agent
The Media Agent handles local entertainment automation. It searches for media titles, evaluates availability on supported streaming platforms, and initiates playback to connected devices.
Architecture note
Some capabilities of the Research Agent and Media Agent were initially prototyped in a shared runtime. The architecture models them as separate logical agents because their responsibilities, tools, and risk profiles are different.
System diagram
Design principles
Separation of responsibilities. Each agent has a bounded scope. The Orchestration Agent coordinates; the Code Execution Agent implements; the Research Agent researches; the Media Agent manages entertainment.
User as final authority. Git operations, deployments, and significant decisions require explicit user action. The Orchestration Agent coordinates and prepares; the user approves and executes final steps.
Local-first operation. All primary agents run locally. External APIs are used for search, media, and AI model access, but core orchestration and data storage are local.
File-based task queues. The Research Agent uses file-based task input and output. This keeps the interface simple, debuggable, and independent of a running service.
Supporting tools
The lab includes several supporting tools under active development:
- Utility scripts supporting orchestration workflows
- Media discovery utilities used by the Media Agent
- Reusable project scaffolding templates
Related pages
→ Agentic Architecture — broader local agentic architecture case study → Data Flow — how requests, tasks, and artifacts move through the system → Orchestration Agent — orchestration agent details → Research Agent — research agent details → Media Agent — media agent details