63 lines
19 KiB
JavaScript
63 lines
19 KiB
JavaScript
import{c as a,Q as e,j as n,m as i}from"./chunks/framework.BPKcPtvA.js";const k=JSON.parse('{"title":"Reference Architecture: Production Multi-Agent Stack","description":"","frontmatter":{},"headers":[],"relativePath":"modules/reference-stack.md","filePath":"modules/reference-stack.md","lastUpdated":null}'),t={name:"modules/reference-stack.md"};function l(o,s,p,r,d,h){return e(),n("div",null,[...s[0]||(s[0]=[i(`<h1 id="reference-architecture-production-multi-agent-stack" tabindex="-1">Reference Architecture: Production Multi-Agent Stack <a class="header-anchor" href="#reference-architecture-production-multi-agent-stack" aria-label="Permalink to "Reference Architecture: Production Multi-Agent Stack""></a></h1><p>This document documents a real production multi-agent deployment. Use it as a reference for Module 5 (Production Patterns) and Module 4 (Multi-Agent Orchestration).</p><h2 id="architecture-overview" tabindex="-1">Architecture Overview <a class="header-anchor" href="#architecture-overview" aria-label="Permalink to "Architecture Overview""></a></h2><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>┌──────────────────────────────────────────────────────────────────┐</span></span>
|
||
<span class="line"><span>│ agent-mux (Tauri UI) │</span></span>
|
||
<span class="line"><span>│ Meta-agent control plane + dashboard │</span></span>
|
||
<span class="line"><span>│ Spawns, monitors, kills agents. Human interface. │</span></span>
|
||
<span class="line"><span>└─────────────────────────┬────────────────────────────────────────┘</span></span>
|
||
<span class="line"><span> │ orchestrates via sidecar</span></span>
|
||
<span class="line"><span> ▼</span></span>
|
||
<span class="line"><span>┌──────────────────────────────────────────────────────────────────┐</span></span>
|
||
<span class="line"><span>│ mprocs (process monitor) │</span></span>
|
||
<span class="line"><span>│ mprocs -c ~/mprocs-teams.yaml │</span></span>
|
||
<span class="line"><span>│ Launches and supervises all agent processes │</span></span>
|
||
<span class="line"><span>├──────────────┬──────────────┬──────────────┬─────────────────────┤</span></span>
|
||
<span class="line"><span>│ claude-lead │ gemini │ opencode │ sidecar │</span></span>
|
||
<span class="line"><span>│ (primary) │ (backup) │ (OSS alt) │ (agent-mux proxy) │</span></span>
|
||
<span class="line"><span>└──────────────┴──────────────┴──────────────┴─────────────────────┘</span></span>
|
||
<span class="line"><span> │ each agent runs inside</span></span>
|
||
<span class="line"><span> ▼</span></span>
|
||
<span class="line"><span>┌──────────────────────────────────────────────────────────────────┐</span></span>
|
||
<span class="line"><span>│ psmux (tmux session manager) │</span></span>
|
||
<span class="line"><span>│ tmux.exe at ~/.cargo/bin/tmux │</span></span>
|
||
<span class="line"><span>│ Claude Code --teammate-mode tmux │</span></span>
|
||
<span class="line"><span>├─────────┬─────────┬─────────┬─────────┬─────────┬───────────────┤</span></span>
|
||
<span class="line"><span>│ pane 1 │ pane 2 │ pane 3 │ pane 4 │ pane 5 │ ... │</span></span>
|
||
<span class="line"><span>│ (lead) │ (worker)│(review) │(verify) │ (sidecar)│ │</span></span>
|
||
<span class="line"><span>└─────────┴─────────┴─────────┴─────────┴─────────┴───────────────┘</span></span>
|
||
<span class="line"><span> │ each task isolated by</span></span>
|
||
<span class="line"><span> ▼</span></span>
|
||
<span class="line"><span>┌──────────────────────────────────────────────────────────────────┐</span></span>
|
||
<span class="line"><span>│ dmux (git worktree isolation) │</span></span>
|
||
<span class="line"><span>│ Each agent task gets its own isolated worktree │</span></span>
|
||
<span class="line"><span>│ dmux runs inside a tmux session with agent-teams │</span></span>
|
||
<span class="line"><span>└──────────────────────────────────────────────────────────────────┘</span></span></code></pre></div><h2 id="layer-by-layer-breakdown" tabindex="-1">Layer-by-Layer Breakdown <a class="header-anchor" href="#layer-by-layer-breakdown" aria-label="Permalink to "Layer-by-Layer Breakdown""></a></h2><h3 id="layer-1-meta-control-plane-agent-mux" tabindex="-1">Layer 1: Meta-Control Plane (agent-mux) <a class="header-anchor" href="#layer-1-meta-control-plane-agent-mux" aria-label="Permalink to "Layer 1: Meta-Control Plane (agent-mux)""></a></h3><ul><li><strong>What</strong>: Tauri desktop application</li><li><strong>Function</strong>: UI for spawning, monitoring, and killing agents</li><li><strong>Communication</strong>: Sidecar process (RPC over IPC)</li><li><strong>Key features</strong>: <ul><li>Start/stop individual agents</li><li>View live output from all agents</li><li>Cost tracking per session</li><li>Session history and replay</li></ul></li></ul><h3 id="layer-2-process-orchestrator-mprocs" tabindex="-1">Layer 2: Process Orchestrator (mprocs) <a class="header-anchor" href="#layer-2-process-orchestrator-mprocs" aria-label="Permalink to "Layer 2: Process Orchestrator (mprocs)""></a></h3><ul><li><strong>Config</strong>: <code>~/mprocs-teams.yaml</code></li><li><strong>Function</strong>: Launches all agent processes, supervises them</li><li><strong>Processes</strong>: <ul><li><code>claude-lead</code>: Claude Code (primary agent)</li><li><code>gemini</code>: Gemini CLI (backup/alternative model)</li><li><code>opencode</code>: OpenCode CLI (open-source alternative)</li><li><code>qwen</code>: Qwen model (specialist/fast tasks)</li><li><code>sidecar</code>: agent-mux IPC proxy</li><li><code>agent-mux</code>: Tauri UI process</li></ul></li></ul><h3 id="layer-3-session-management-psmux" tabindex="-1">Layer 3: Session Management (psmux) <a class="header-anchor" href="#layer-3-session-management-psmux" aria-label="Permalink to "Layer 3: Session Management (psmux)""></a></h3><ul><li><strong>Binary</strong>: <code>tmux.exe</code> at <code>~/.cargo/bin/tmux</code></li><li><strong>Function</strong>: Terminal multiplexer for agent sessions</li><li><strong>Key feature</strong>: <code>Claude Code --teammate-mode tmux</code> — Claude's native multi-agent split-pane mode</li><li><strong>Team spawns</strong>: Each <code>--teammate-mode</code> invocation creates split panes, each running a separate Claude session</li></ul><h3 id="layer-4-work-isolation-dmux" tabindex="-1">Layer 4: Work Isolation (dmux) <a class="header-anchor" href="#layer-4-work-isolation-dmux" aria-label="Permalink to "Layer 4: Work Isolation (dmux)""></a></h3><ul><li><strong>Function</strong>: Git worktree isolation per task</li><li><strong>Requirement</strong>: Must run inside a tmux session (start agent-teams first, then dmux)</li><li><strong>Benefit</strong>: Each task gets an isolated filesystem. No cross-task contamination. Easy rollback (delete worktree).</li></ul><h2 id="tool-specific-configurations" tabindex="-1">Tool-Specific Configurations <a class="header-anchor" href="#tool-specific-configurations" aria-label="Permalink to "Tool-Specific Configurations""></a></h2><h3 id="claude-code" tabindex="-1">Claude Code <a class="header-anchor" href="#claude-code" aria-label="Permalink to "Claude Code""></a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Launch with teammate mode (multi-agent)</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claude</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --teammate-mode</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tmux</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Headless mode (for CI/CD)</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claude</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -p</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "prompt"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --allowedTools</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "Read Write Edit Bash"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --print</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># With custom hooks</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claude</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --hooks</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .claude/hooks/</span></span></code></pre></div><h3 id="pi-coding-agent" tabindex="-1">Pi Coding Agent <a class="header-anchor" href="#pi-coding-agent" aria-label="Permalink to "Pi Coding Agent""></a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Launch with extensions</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pi</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -e</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> extensions/damage-control.ts</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -e</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> extensions/tilldone.ts</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -e</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> extensions/minimal.ts</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># RPC mode (programmatic control)</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pi</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --mode</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rpc</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># With custom skills</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pi</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --skills-dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .pi/skills/</span></span></code></pre></div><h3 id="opencode" tabindex="-1">OpenCode <a class="header-anchor" href="#opencode" aria-label="Permalink to "OpenCode""></a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Using Go model (via proxy)</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">opencode</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --model</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> opencode-go/deepseek-v4-flash</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Headless execution</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">opencode</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "prompt"</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># With config from shared ~/.grok/config.toml</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">opencode</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --config</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ~/.grok/config.toml</span></span></code></pre></div><h3 id="openclaw" tabindex="-1">OpenClaw <a class="header-anchor" href="#openclaw" aria-label="Permalink to "OpenClaw""></a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Always-on employee mode</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claw</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> start</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --daemon</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># One-shot task execution</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claw</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> do</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "task description"</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Heartbeat schedule</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claw</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> schedule</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --cron</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "0 */6 * * *"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --task</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "daily-report"</span></span></code></pre></div><h2 id="cost-analysis" tabindex="-1">Cost Analysis <a class="header-anchor" href="#cost-analysis" aria-label="Permalink to "Cost Analysis""></a></h2><table tabindex="0"><thead><tr><th>Tool</th><th>Best For</th><th>Est. Cost/Task</th><th>Autonomy Level</th></tr></thead><tbody><tr><td>Claude Code</td><td>Complex multi-step tasks</td><td>$0.05-$0.30</td><td>High (with hooks)</td></tr><tr><td>Pi Agent</td><td>Custom workflows, safety-critical</td><td>$0.02-$0.15</td><td>Very high (extensible)</td></tr><tr><td>OpenCode</td><td>OSS-compatible, budget tasks</td><td>$0.01-$0.05</td><td>Medium</td></tr><tr><td>Gemini</td><td>High-volume, simple tasks</td><td>$0.002-$0.01</td><td>Low</td></tr><tr><td>OpenClaw</td><td>Scheduled, always-on tasks</td><td>$0.01-$0.10</td><td>Autonomous</td></tr></tbody></table><h2 id="key-production-patterns" tabindex="-1">Key Production Patterns <a class="header-anchor" href="#key-production-patterns" aria-label="Permalink to "Key Production Patterns""></a></h2><ol><li><p><strong>Model heterogeneity</strong>: Different models for different roles. Claude for complex reasoning, Gemini for fast/cheap tasks, Qwen as specialist.</p></li><li><p><strong>Tool heterogeneity</strong>: Not one agent CLI, but five. Each has different strengths. The stack uses each where it excels.</p></li><li><p><strong>Defense in depth</strong>: psmux isolates sessions. dmux isolates files. damage-control restricts commands. mprocs restarts failed processes.</p></li><li><p><strong>Observability</strong>: agent-mux shows live status. mprocs logs output. Session history enables replay debugging.</p></li><li><p><strong>No single point of failure</strong>: If Claude Code fails, Pi or OpenCode can take over. The mprocs supervisor restarts crashed processes.</p></li></ol><h2 id="what-this-stack-proves" tabindex="-1">What This Stack Proves <a class="header-anchor" href="#what-this-stack-proves" aria-label="Permalink to "What This Stack Proves""></a></h2><p>This architecture demonstrates every concept taught in Modules 1-7:</p><table tabindex="0"><thead><tr><th>Concept</th><th>Where It Appears</th></tr></thead><tbody><tr><td>Agent loop</td><td>Every tool follows think→act→observe→repeat</td></tr><tr><td>Tool design</td><td>Each tool provides different tools (read, write, bash, search)</td></tr><tr><td>Security</td><td>damage-control, psmux isolation, dmux isolation</td></tr><tr><td>Multi-agent</td><td>teammate-mode, mprocs launching 5 agents</td></tr><tr><td>Production</td><td>mprocs supervision, cost tracking, worktree isolation</td></tr><tr><td>Economics</td><td>Cascade routing across 5 tools by task type</td></tr><tr><td>Advanced</td><td>agent-mux as meta-agent controlling other agents</td></tr></tbody></table>`,29)])])}const u=a(t,[["render",l]]);export{k as __pageData,u as default};
|