Multi-Agent AI Collaboration Architecture

Multi-Agent Collaboration Overview

A four-layer division of work with Codex as the core coordinator

1

Codex - Primary Coordinator

Decomposes tasks, schedules resources, generates images, edits files, validates outputs, and prepares final delivery while retaining core project decisions.

2

Antigravity IDE - Parallel Coordinator

Coordinates long-running work, video or subtitle analysis, parallel subtask decomposition, and visible IDE-based progress.

3

Gemini CLI - Cloud Advisor

Provides advanced reasoning, web-search context, cross-tool synthesis, and a fallback when parallel IDE coordination is unavailable.

4

Ollama - Local Draft Executor

Runs local GPU or NPU inference for low-risk drafts, summaries, rewrites, translations, and classifications. The example default is gemma3-tw-edu:4b.

Architecture Relationship Map

graph TB subgraph User["User Layer"] U[User Request] end subgraph Core["Codex Core"] C1[Task Decomposition] --> C2[Resource Scheduling] C2 --> C3[Validation and Delivery] C1 -.-> C4[Image Generation] C2 -.-> C5[File Editing] end subgraph Agents["External Agent Layer"] A1[Antigravity IDE
Parallel Coordination] A2[Gemini CLI
Cloud Reasoning] A3[Ollama
Local Drafting] end subgraph Skills["Skill Package Layer"] S1[external-agent-orchestrator] S2[skill-registry.yaml] S3[dispatch-task.ps1] S4[detect-tools.ps1] S5[log-event.ps1] end U --> C1 C1 -->|long-running / media / parallel| A1 C1 -->|research / planning / review| A2 C1 -->|draft / summary / translation| A3 C1 --> S1 S1 --> S2 S1 --> S3 S3 --> S4 S3 --> S5 style Core fill:#dbeafe,stroke:#1e40af style Agents fill:#fef3c7,stroke:#92400e style Skills fill:#d1fae5,stroke:#065f46 style User fill:#e9d5ff,stroke:#6b21a8

Tool Detection and Routing

Automatic detection with detect-tools.ps1 and policy-based dispatch with dispatch-task.ps1

Tool Detection Flow

flowchart TD A[Start detect-tools.ps1] --> B{Check PATH} B -->|found| C[available=true via=PATH] B -->|not found| D{Check fallback paths} D -->|found| E[available=true via=fallback] D -->|not found| F[available=false] C --> G[Output JSON] E --> G F --> G G --> H[Return to dispatch-task.ps1]

Automatic Routing Logic

flowchart TD Task[Task Description] --> KW{Keyword Match} KW -->|image / asset| CodexOnly[Codex only] KW -->|video / subtitle| VR{Antigravity available?} VR -->|yes| AG1[Antigravity + Gemini] VR -->|no| GM1[Gemini fallback] KW -->|parallel / long-running| AR{Antigravity available?} AR -->|yes| AG2[Antigravity + Gemini] AR -->|no| GM2[Gemini fallback] KW -->|local / translation| OR{Ollama available?} OR -->|yes| OL[Ollama] OR -->|no| Def{Antigravity available?} Def -->|yes| AG3[Antigravity] Def -->|no| GM3{Gemini available?} GM3 -->|yes| GM4[Gemini] GM3 -->|no| OL2{Ollama available?} OL2 -->|yes| OL3[Ollama] OL2 -->|no| Err[Error: no tool available] style CodexOnly fill:#dbeafe,stroke:#1e40af style VR fill:#fef3c7,stroke:#92400e style AR fill:#fef3c7,stroke:#92400e style OR fill:#d1fae5,stroke:#065f46

Dispatch Template System

@(
  "research" = @{ targets=@("gemini","ollama","antigravity"); model="gemma4:e4b"
    gemini="Lead researcher: compare options and recommend"; ollama="Local analyst: draft summaries and lists"; antigravity="Decomposition assistant: parallel subtasks" }
  "agent-collab" = @{ targets=@("antigravity","gemini","ollama")
    gemini="Cloud advisor: complex reasoning"; ollama="Local executor: summary and translation"; antigravity="IDE coordinator: long-running work" }
  "translation" = @{ targets=@("ollama") }
  "video-analysis" = @{ targets=@("antigravity","gemini") }
  "subtitle" = @{ targets=@("antigravity","gemini") }
)

Fallback Strategy

✓ If Antigravity is unavailable, fall back to Gemini CLI
✓ If both video or subtitle routes are unavailable, stop rather than routing the task to Ollama
✓ If an explicitly requested tool is unavailable, log the error and stop
✓ If only one tool is available, reserve it for the highest-value stage and let Codex integrate
✓ For current-information or high-risk tasks, log the exception and escalate

Skill Package and Version Management

Central registration, dependency declarations, and SHA-256 verification through skill-registry.yaml

Skill Registry Structure

schema_version: 1
audited_at: "2026-07-23"
policy: "Codex owns implementation and validation; Ollama is a reviewed low-risk draft option."
skills:
  - name: external-agent-orchestrator
    short_description: "Auditable cross-tool coordination"
    applies_to: "Cross-tool, long-running, or evidence-logged work"
    excludes: "Ordinary simple questions"
    dependencies: ollama-simple-answer-review
    version: "2"
  - name: crossref-apa-bibliography
    dependencies: documents, spreadsheets
    version: "1"
  - name: journal-manuscript-writer
    dependencies: crossref-apa-bibliography, documents, pdf
    version: "1"
  - name: ena-network-figure
    dependencies: journal-manuscript-writer
    version: "1"
  - name: pd-survey-analysis-report
    dependencies: spreadsheets, documents, ena-network-figure
    version: "1"

Dependency Map (arrows point to dependencies)

graph TD subgraph Core[Core Coordination] EAO[external-agent-orchestrator v2] OSAR[ollama-simple-answer-review v2] end subgraph Research[Literature and Research] CAB[crossref-apa-bibliography v1] CIPD[crossref-indigenous-proposal-docx v1] end subgraph Writing[Writing and Publication] JMW[journal-manuscript-writer v1] ENA[ena-network-figure v1] end subgraph Analysis[Analysis and Reports] PDS[pd-survey-analysis-report v1] end subgraph Media[Media Processing] CHAV[create-html-animation-video v1] EYVS[edit-youtube-vertical-shorts v1] VAP[video-automation-pipeline v1] end subgraph Teaching[Teaching Materials] TPTS[textbook-photo-to-teaching-slides v1] PFTS[photo-folder-to-slides v1] end EAO --> OSAR OSAR --> EAO CIPD --> CAB JMW --> CAB ENA --> JMW PDS --> ENA CHAV --> VAP EYVS --> CHAV EYVS --> VAP VAP --> CHAV VAP --> EYVS style EAO fill:#dbeafe,stroke:#1e40af style JMW fill:#fef3c7,stroke:#92400e style PDS fill:#d1fae5,stroke:#065f46 style VAP fill:#e9d5ff,stroke:#6b21a8

Version Control and Validation

Git Version Control

• Use a dedicated Git repository or monorepo
• Apply semantic versioning
• Record breaking changes in CHANGELOG.md

SHA-256 Verification

• Calculate hashes with quick_validate.py
• Compare with the registry value
• Block damaged or mismatched packages

Dependency Resolution

1. Topologically sort the dependency graph
2. Load dependency-free foundational skills first
3. Report circular dependencies

Implementation Examples and Good Practices

Practical dispatch, structured logging, and bilingual report production with dispatch-task.ps1

Example 1: Research Dispatch

powershell -ExecutionPolicy Bypass -File ".\scripts\dispatch-task.ps1" 
  -Task "Compare three RAG architectures and recommend an option" 
  -Template research -Target auto 
  -ContextFiles @("docs/rag-options.md") 
  -OutputRoot "C:\Projects\outputs\rag-research"

Output: .external-agent-orchestrator/logs/runs/20260728-XXXXX/ contains request.txt, gemini.md, ollama.md, antigravity-launch.md, and manifest.json

Example 2: Multi-Agent Collaboration

powershell -ExecutionPolicy Bypass -File ".\scripts\dispatch-task.ps1" 
  -Task "Design an architecture document for a teaching website" 
  -Template agent-collab -Target all 
  -ContextFiles @(
    "skills/external-agent-orchestrator/SKILL.md",
    "skills/external-agent-orchestrator/scripts/dispatch-task.ps1",
    "skills/skill-registry.yaml"
  ) 
  -OutputRoot "C:\Projects\opencodex\teaching-site"

Log Format (JSONL)

{
  "timestamp": "2026-07-28T07:05:38.329+08:00",
  "actor": "ollama",
  "event": "run-complete",
  "status": "ok",
  "summary": "Ollama dispatch completed with model gemma3-tw-edu:4b.",
  "task": "Teaching website architecture design",
  "outputs": ["\outputs\\ollama.md"],
  "cwd": ""
}

Good-Practice Checklist

Before Dispatch

☐ Run detect-tools.ps1 to confirm tool availability
☐ Select a template based on task type
☐ Prepare ContextFiles using explicit paths
☐ Set OutputRoot to a project-specific directory

During and After Execution

☐ Call log-event.ps1 at each critical step
☐ Retain manifest.json for audit tracing
☐ Produce bilingual HTML or DOCX process reports
☐ Visually inspect diagrams before delivery

Visual Workflow Diagrams (Mermaid)

The complete dispatch lifecycle, tool-selection decision tree, and skill dependency topology

Open bilingual SVG gallery

Dispatch Lifecycle

sequenceDiagram participant U as User participant C as Codex participant D as detect-tools participant P as dispatch-task participant L as log-event participant T as Target Tool participant M as manifest U->>C: Submit task C->>D: Detect tools D-->>C: JSON tool map C->>P: Invoke dispatch P->>L: tool-selection P->>P: Resolve template P->>P: Create run directory P->>P: Write request.txt loop Each target P->>L: run-start P->>T: Run tool T-->>P: Result P->>L: run-complete/failure P->>P: Store output end P->>M: Generate manifest P->>L: artifact-created M-->>C: Run manifest C->>U: Deliver artifacts

Tool-Selection Decision Tree

flowchart TD S([Start]) --> TM{Template selected?} TM -->|yes| UT[Use template targets] TM -->|no| AT[Analyze keywords] AT --> IK{Image keywords?} IK -->|yes| CO[Codex only] IK -->|no| VK{Video keywords?} VK -->|yes| CA1{Antigravity?} CA1 -->|yes| TA1[Antigravity + Gemini] CA1 -->|no| CG1[Gemini] VK -->|no| PK{Parallel keywords?} PK -->|yes| CA2{Antigravity?} CA2 -->|yes| TA2[Antigravity + Gemini] CA2 -->|no| CG2[Gemini] CG2 -->|no| CO1{Ollama?} CO1 -->|yes| TO1[Ollama] CO1 -->|no| ER2[Error] PK -->|no| LK{Local keywords?} LK -->|yes| CO2{Ollama?} CO2 -->|yes| TO2[Ollama] CO2 -->|no| CA3{Antigravity?} CA3 -->|yes| TA3[Antigravity] CA3 -->|no| CG3{Gemini?} CG3 -->|yes| TG3[Gemini] CG3 -->|no| ER3[Error] LK -->|no| DR{Default route} DR --> CA4{Antigravity?} CA4 -->|yes| TA4[Antigravity] CA4 -->|no| CG4{Gemini?} CG4 -->|yes| TG4[Gemini] CG4 -->|no| CO3{Ollama?} CO3 -->|yes| TO3[Ollama] CO3 -->|no| ER4[Error] style CO fill:#dbeafe,stroke:#1e40af style TA1 fill:#fef3c7,stroke:#92400e style TA2 fill:#fef3c7,stroke:#92400e style TO1 fill:#d1fae5,stroke:#065f46 style TO2 fill:#d1fae5,stroke:#065f46 style ER2 fill:#fee2e2,stroke:#dc2626 style ER3 fill:#fee2e2,stroke:#dc2626 style ER4 fill:#fee2e2,stroke:#dc2626

Skill Dependency Topology

graph LR subgraph L0[Layer 0: Core and foundational skills] EAO[EAO] OSAR[OSAR] BKN[BKN] HZT[HZT] ERG[ERG] HP[HP] end subgraph L1[Layer 1: Applied skills] CAB[CAB] CHAV[CHAV] EYVS[EYVS] TPTS[TPTS] PFTS[PFTS] PDS[PDS] VAP[VAP] end subgraph L2[Layer 2: Research and writing] CIPD[CIPD] JMW[JMW] end subgraph L3[Layer 3: Analytical extensions] ENA[ENA] end EAO --> OSAR OSAR --> EAO CIPD --> CAB JMW --> CAB ENA --> JMW PDS --> ENA CHAV --> VAP EYVS --> CHAV EYVS --> VAP VAP --> CHAV VAP --> EYVS classDef l0 fill:#dbeafe,stroke:#1e40af classDef l1 fill:#fef3c7,stroke:#92400e classDef l2 fill:#e9d5ff,stroke:#6b21a8 classDef l3 fill:#d1fae5,stroke:#065f46 class EAO,OSAR,BKN,HZT,ERG,HP l0 class CAB,CHAV,EYVS,TPTS,PFTS,PDS,VAP l1 class CIPD,JMW l2 class ENA l3

Reading note: resolve cycles before loading

The current registry declares bidirectional dependencies between external-agent-orchestrator and ollama-simple-answer-review, as well as among several media skills. The diagrams retain these links as audit signals. If the loader requires a strict directed acyclic graph, revise the registry before topological sorting.

Reference Files and Configuration

A practical reference for project files and key configuration fields

Core File List

File Path	Purpose	Key Content
skills/external-agent-orchestrator/SKILL.md	Primary skill file	Routing policy, logging rules, report production, and dispatch templates
skills/external-agent-orchestrator/scripts/detect-tools.ps1	Tool detection	PATH and fallback resolution with JSON output
skills/external-agent-orchestrator/scripts/dispatch-task.ps1	Task dispatch	Templates, automatic routing, manifest generation, and dry runs
skills/external-agent-orchestrator/scripts/log-event.ps1	Structured logging	JSONL records, retry-safe writes, and actor/event/status fields
skills/external-agent-orchestrator/scripts/read-log.ps1	Log reader	Tail, JSON, table output, and filters
skills/skill-registry.yaml	Skill registry	Version, dependencies, inclusion and exclusion scope, and policy
.external-agent-orchestrator/logs/agent-events.jsonl	Event log	Append-only records of dispatch events
.external-agent-orchestrator/logs/runs/	Run artifacts	A separate directory and manifest.json for each dispatch

Environment Path Configuration

SKILL_ROOT = "<user-home>\.codex\skills\external-agent-orchestrator"
PROJECT_STATE = "<project-root>\.external-agent-orchestrator"
EVENT_LOG = "<project-root>\.external-agent-orchestrator\logs\agent-events.jsonl"
RUNS_ROOT = "<project-root>\.external-agent-orchestrator\logs\runs"

gemini: <user-profile>\AppData\Roaming\npm\gemini.ps1
ollama: <user-profile>\AppData\Local\Programs\Ollama\ollama.exe
antigravity: <install-root>\Antigravity IDE\bin\antigravity-ide.cmd

Ollama Model List

Model	Size	Purpose	Notes
gemma3-tw-edu:4b	3.3 GB	Teaching and Traditional Chinese	Example default ✓
gemma4:e4b	9.6 GB	High-quality general use	dispatch-task fallback
gemma3n:e4b	7.5 GB	Architecture experiments
qwen3:4b	2.5 GB	Chinese and multilingual	Lightweight alternative
minicpm-v:latest	5.5 GB	Vision model	Multimodal tasks

Multi-Agent AI Collaboration Architecture An implementation guide based on external-agent-orchestrator Skill v2