多智能体协调器

┌──────────────────────────────────────────────────────────────────┐
│                     HTTP Server (FastAPI)                         │
│  /chat  /chat/enriched  /mcp  /agents  /skills  /workflows       │
│  /workiq/*  /inspector                                           │
└──────────────────────────┬───────────────────────────────────────┘
                           │
            ┌──────────────▼──────────────┐
            │      WorkIQ Pre-Router      │ ← (optional enrichment)
            │  ┌──────────────────────┐   │
            │  │ Phase 0: workiq ask  │   │  Query M365 context
            │  │ Phase 1: HITL select │   │  User picks content
            │  │ Phase 2: extract kw  │   │  Keyword hints
            │  │ Phase 2b: HITL hints │   │  User accepts keywords
            │  └──────────┬───────────┘   │
            └─────────────┼───────────────┘
                          │  routing hints
                 ┌────────▼────────┐
                 │   Orchestrator   │ ← Intent Router (keyword + LLM)
                 │     Engine       │   + WorkIQ enrichment hints
                 └────────┬────────┘
                          │  ALWAYS first
                 ┌────────▼────────┐
                 │   Plan Agent    │ ← Top-level coordinator
                 │  (Coordinator)  │    Analyzes, strategizes,
                 │                 │    identifies sub-agents
                 └────────┬────────┘
                          │  HITL: user accepts plan suggestions
                 ┌────────▼────────┐
                 │  Sub-Plan Agent │ ← Resource planner
                 │  (Specialist)   │    Plans prerequisite infra
                 │                 │    "minimum viable resources"
                 └────────┬────────┘
                          │  HITL: user accepts resource plan
        ┌─────────┬───────┼───────┐
        ▼         ▼       ▼       ▼  (max 3 specialists)
   ┌──────────┐ ┌─────────┐ ┌─────────────────┐
   │   Log    │ │  Code   │ │   Remediation   │
   │ Analysis │ │Research │ └─────────────────┘
   └──────────┘ └─────────┘
        ▼              ▼              ▼
   ┌──────────┐ ┌──────────┐ ┌────────────────┐
   │Knowledge │ │  Data    │ │   Security     │
   │  Base    │ │ Analysis │ │   Sentinel     │
   └──────────┘ └──────────┘ └────────────────┘
                      │
                 ┌────▼───────┐
                 │  WorkIQ    │ ← M365 organisational context
                 │  (HITL)    │   2-phase human-in-the-loop
                 └────────────┘

   ─── Standard Flow (/chat) ──────────────────────────
   User Message
     → Intent Router (keyword + LLM)
       → Plan Agent (ALWAYS first — produces strategy)
         → HITL: user accepts plan suggestions & keywords
           → Sub-Plan Agent (resource deployment plan)
             → HITL: user accepts resources & brief
               → Task Agents (parallel fan-out, max 3 specialists)
                 → Aggregated Response
   ────────────────────────────────────────────────────

   ─── Enriched Flow (/chat/enriched) ─────────────────
   User Message
     → WorkIQ query (M365 context)
       → HITL Phase 1: user selects content sections
         → Keyword extraction from selected content
           → HITL Phase 2: user accepts/rejects keywords
             → Intent Router (keyword + hints + LLM)
               → Plan Agent → HITL → Sub-Plan → HITL
                 → Task Agents → Aggregated Response
   ────────────────────────────────────────────────────

┌─────────────────┐  ┌─────────────────┐  ┌──────────────────┐
│  Forge Loader   │  │  Context Budget  │  │  Contribution    │
│  (Agent YAML)   │  │  Manager         │  │  Manager (CRUD)  │
└─────────────────┘  └─────────────────┘  └──────────────────┘
┌─────────────────┐  ┌─────────────────┐  ┌──────────────────┐
│  MCP Server     │  │  Agent Catalog  │  │  Workflow Engine  │
│  (Skills Dist.) │  │  (Registry)     │  │  (Bundling)       │
└─────────────────┘  └─────────────────┘  └──────────────────┘

from src.registry.catalog import AgentCatalog, AgentRegistration, CatalogEntry

catalog = AgentCatalog(storage_path=Path(".forge_catalog"))

# Register an agent
catalog.register_agent(AgentRegistration(
    agent_type="log_analysis",
    name="Log Analysis Agent",
    description="Expert in parsing and diagnosing application logs",
    version="1.0.0",
    skills=["analyze_logs"],
    tags=["logs", "errors", "debugging"],
))

# List all active agents
for agent in catalog.list_agents(status="active"):
    print(f"{agent.name} — {agent.description} (skills: {agent.skills})")

# Search agents by tag
security_agents = catalog.list_agents(tag="security")

# Track agent metrics (latency, errors)
catalog.update_agent_metrics("log_analysis", latency_ms=145.2, is_error=False)

# Unregister an agent
catalog.unregister_agent("my_old_agent")

# Add a skill to the catalog
catalog.add_to_catalog(CatalogEntry(
    skill_name="analyze_dependencies",
    description="Analyze project dependencies for vulnerabilities",
    agent_type="security_sentinel",
    version="1.0.0",
    tags=["security", "dependencies"],
))

# Install / uninstall skills
catalog.install_skill("analyze_dependencies")
catalog.uninstall_skill("analyze_dependencies")

# Search the skill catalog
results = catalog.search_catalog(query="security", installed_only=True)

# Bulk-populate from ForgeLoader skills
catalog.populate_from_skills(forge_registry.skills)

# List all registered agents with capabilities
GET /agents

# List all available skills
GET /skills

# Full system status including catalog stats
GET /health

forge/
├── _registry.yaml              # Master registry of all agents
├── _context_window.yaml        # Global token budget configuration
├── plan/                       # Plan Agent (coordinator)
│   ├── agent.yaml              #   Manifest: id, subagents, context_budget
│   ├── prompts/                #   System & strategy prompts (.md)
│   ├── skills/                 #   plan_task, identify_agents, build_strategy
│   ├── instructions/           #   routing_rules, coordination
│   └── workflows/              #   plan_and_execute.yaml
├── agents/                     # 9 agent directories (sub_plan + 8 specialists)
│   ├── sub_plan/               #   Sub-Plan Agent (resource planner + dual HITL)
│   ├── log_analysis/           #   agent.yaml + prompts/ + skills/ + instructions/
│   ├── code_research/
│   ├── remediation/
│   ├── knowledge_base/
│   ├── data_analysis/
│   ├── security_sentinel/
│   └── workiq/                 #   WorkIQ agent (M365 context + HITL selection)
├── shared/                     # Cross-agent resources
│   ├── prompts/                #   error_handling.md, output_format.md
│   ├── instructions/           #   quality_standards.md, security_baseline.md
│   └── workflows/              #   code_review.yaml, incident_response.yaml
└── contrib/                    # Dynamic contributions (CRUD via API)
    ├── audit_log.yaml          #   Timestamped audit trail
    ├── agents/                 #   Community-contributed agents
    ├── skills/                 #   Community-contributed skills
    └── workflows/              #   Community-contributed workflows

id: plan_agent
name: Plan Agent
type: coordinator          # coordinator | specialist
description: >
  Top-level coordinator that analyzes every incoming request,
  produces a strategic execution plan, and identifies which
  specialist sub-agents should be invoked downstream.
version: "1.0.0"
context_budget:
  max_input_tokens: 24000
  max_output_tokens: 8000
  strategy: priority       # priority | sliding_window | summarize
subagents:
  - log_analysis
  - code_research
  - remediation
  - knowledge_base
  - data_analysis
  - security_sentinel
prompts:
  system: system.md
skills:
  - plan_task.yaml
  - identify_agents.yaml
  - build_strategy.yaml
instructions:
  - routing_rules.md
  - coordination.md

Orchestration run (128K budget)
  ├── Plan Agent           →  ~8K tokens
  ├── Sub-Plan Agent       →  ~5K tokens
  ├── Log Analysis         → ~15K tokens
  ├── Code Research        → ~20K tokens   ← cumulative: 48K ✅
  ├── Security Sentinel    → ~18K tokens   ← cumulative: 66K ✅
  ├── Knowledge Base       → ~30K tokens   ← cumulative: 96K ✅
  ├── Data Analysis        → ~25K tokens   ← cumulative: 121K ⚠️ WARNING!
  │   └─ GovernanceGuardian triggers HITL
  │   └─ Human accepts decomposition
  │   └─ Remaining work spawns sub-agent with fresh 128K context
  └── [Spawned sub-agent]  → fresh 128K window

from src.forge.contributions import ContributionManager

contrib = ContributionManager("forge")

# Create a new agent
contrib.create_agent("my_agent", manifest={...}, system_prompt="...", author="team-x")

# Add a skill
contrib.create_skill("my_skill", skill_def={...}, author="team-x")

# All changes are audit-logged in forge/contrib/audit_log.yaml

# 1. Clone and install
cd ProtoForge
pip install -e ".[dev]"

# 2. Configure
cp .env.example .env
# Edit .env with your credentials

# 2b. Azure AI Foundry (recommended) — requires Azure CLI
az login
# Set AZURE_AI_FOUNDRY_ENDPOINT in .env (e.g. https://your-resource.openai.azure.com/)
# Set AZURE_AI_FOUNDRY_MODEL (e.g. gpt-5.2-chat)
# Set AUTH_METHOD=azure_default

# 3. Run the server
protoforge serve
# → http://localhost:8080/inspector (Agent Inspector)

# 4. Or use interactive chat
protoforge chat

# 5. Check status
protoforge status

// POST /mcp
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

// Response: all agent skills as MCP tools

# forge/plan/skills/plan_task.yaml
name: plan_task
description: "Break down a complex task into actionable steps"
agent_type: plan
parameters:
  - name: task_description
    type: string
    description: "The task to plan"
    required: true

# forge/shared/workflows/incident_response.yaml
name: incident_response
description: "Full incident response: logs → code → security → diagnose → fix"
steps:
  - name: analyze_logs
    agent_type: log_analysis
    prompt_template: "Analyze logs for incident: {incident_description}"
  - name: research_code
    agent_type: code_research
    depends_on: [analyze_logs]
  - name: security_check
    agent_type: security_sentinel
    depends_on: [analyze_logs]
  - name: diagnose
    agent_type: knowledge_base
    depends_on: [research_code, security_check]
  - name: generate_fix
    agent_type: remediation
    depends_on: [diagnose]

User query ("find the Teams discussion about the outage")
  → Phase 0: WorkIQ CLI (`workiq ask "..."`) — returns ranked sections
    → Phase 1 (HITL): user selects relevant content sections
      → Phase 2: extract routing keywords from selected content
        → Phase 2b (HITL): user accepts/rejects keyword hints
          → Phase 3: enriched Intent Router (message + accepted keywords)
            → Plan Agent → Sub-Agents → Aggregated Response

curl -X POST http://localhost:8080/workiq/query \
  -H "X-API-Key: $CONTROL_PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "latest standup notes from Teams"}'

{
  "response": "Teams: Daily Standup ...",
  "request_id": "abc123",
  "sections": [
    {"index": 0, "preview": "Teams: Daily Standup ...", "source": "https://..."},
    {"index": 1, "preview": "Teams: Standup Recap ...", "source": "https://..."},
    {"index": 2, "preview": "Email: Standup Summary ...", "source": "https://..."}
  ],
  "pending_selections": [
    {
      "request_id": "abc123",
      "options": [
        {"index": 0, "preview": "...", "source": "https://..."},
        {"index": 1, "preview": "...", "source": "https://..."}
      ]
    }
  ]
}

# Check pending selections
curl -H "X-API-Key: $CONTROL_PLANE_API_KEY" http://localhost:8080/workiq/pending

# Select sections
curl -X POST http://localhost:8080/workiq/select \
  -H "X-API-Key: $CONTROL_PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "abc123", "selected_indices": [0, 1]}'

curl -H "X-API-Key: $CONTROL_PLANE_API_KEY" http://localhost:8080/workiq/routing-hints

{
  "pending": [
    {
      "request_id": "hint-456",
      "hints": [
        {"index": 0, "agent_id": "log_analysis", "keyword": "error", "matched_text": "...deploy error in the auth..."},
        {"index": 1, "agent_id": "security_sentinel", "keyword": "security", "matched_text": "...security review needed..."}
      ]
    }
  ]
}

curl -X POST http://localhost:8080/workiq/accept-hints \
  -H "X-API-Key: $CONTROL_PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "hint-456", "accepted_indices": [0]}'

{
  "request_id": "hint-456",
  "accepted_hints": [{"agent_id": "log_analysis", "keyword": "error"}],
  "status": "resolved"
}

curl -X POST http://localhost:8080/chat/enriched \
  -H "X-API-Key: $CONTROL_PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What did the team discuss about the production outage?"}'

# Install Work IQ CLI globally
npm install -g @microsoft/workiq

# Accept the EULA (one-time)
workiq --acceptEula

# Verify
workiq --version

# Install dev dependencies
pip install -e ".[dev]"

# Run tests (485 tests, 12 files)
pytest

# Run live integration tests (requires az login + Azure endpoint)
pytest -m live -v

# Run only mocked tests (no Azure required)
pytest -m "not live"

# Run with coverage
pytest --cov=src

# Lint (ruff, line-length 120)
ruff check src/

# Type check
mypy src/

ProtoForge/
├── pyproject.toml              # Project config & dependencies
├── GUIDE.md                    # Developer guide (architecture, extending, ADRs)
├── README.md                   # This file
├── forge/                      # ★ Declarative agent ecosystem
│   ├── _registry.yaml          #   Master agent registry
│   ├── _context_window.yaml    #   Token budget configuration
│   ├── plan/                   #   Plan Agent (coordinator)
│   │   ├── agent.yaml
│   │   ├── prompts/
│   │   ├── skills/
│   │   ├── instructions/
│   │   └── workflows/
│   ├── agents/                 #   9 agent directories (sub_plan + 8 specialists)
│   │   ├── sub_plan/
│   │   ├── log_analysis/
│   │   ├── code_research/
│   │   ├── remediation/
│   │   ├── knowledge_base/
│   │   ├── data_analysis/
│   │   ├── security_sentinel/
│   │   ├── github_tracker/     #   GitHub issue/PR tracking
│   │   └── workiq/             #   WorkIQ (M365 context + HITL)
│   ├── shared/                 #   Cross-agent prompts, instructions, workflows
│   │   ├── prompts/
│   │   ├── instructions/
│   │   └── workflows/
│   └── contrib/                #   Dynamic contributions (CRUD + audit)
│       ├── audit_log.yaml
│       └── README.md
├── src/
│   ├── main.py                 # Entry point & bootstrap
│   ├── config.py               # Settings (pydantic-settings + ForgeConfig)
│   ├── server.py               # FastAPI app factory + route wiring
│   ├── server_routes/          # Modular FastAPI route groups (37 endpoints)
│   ├── agents/                 # 10 agent types (8 dedicated files + GenericAgent handles 2)
│   │   ├── base.py             #   BaseAgent + BaseAgent.from_manifest()
│   │   ├── generic.py          #   GenericAgent (used by code_research & data_analysis)
│   │   ├── plan_agent.py
│   │   ├── sub_plan_agent.py   #   Sub-Plan Agent (resource planner + dual HITL)
│   │   ├── log_analysis_agent.py
│   │   ├── remediation_agent.py
│   │   ├── knowledge_base_agent.py
│   │   ├── security_sentinel_agent.py
│   │   ├── github_tracker_agent.py  #   GitHub Tracker (issues, PRs, milestones)
│   │   └── workiq_agent.py     #   WorkIQ agent (M365 2-phase HITL)
│   ├── forge/                  # ★ Forge runtime modules
│   │   ├── loader.py           #   ForgeLoader — discovers forge/ tree
│   │   ├── context_budget.py   #   ContextBudgetManager — token budgets
│   │   └── contributions.py    #   ContributionManager — CRUD + audit
│   ├── llm/                    # ★ LLM client (Azure AI Foundry + OpenAI)
│   │   ├── __init__.py         #   Exports LLMClient, get_llm_client
│   │   └── client.py           #   Async LLM client, singleton, multi-provider
│   ├── governance/             # ★ Always-on governance enforcement
│   │   ├── guardian.py         #   GovernanceGuardian — 3-pillar enforcement
│   │   └── selector.py         #   GovernanceSelector — HITL gates for violations
│   ├── orchestrator/           # Core orchestration engine
│   │   ├── engine.py           #   Plan-first dispatch + Sub-Plan pipeline
│   │   ├── router.py           #   Intent Router (keyword + LLM + enrichment)
│   │   ├── context.py          #   Shared conversation context
│   │   └── plan_selector.py    #   Dual HITL selector (Plan + Sub-Plan review)
│   ├── mcp/                    # MCP protocol server
│   │   ├── server.py           #   MCP request handler
│   │   ├── protocol.py         #   MCP message types
│   │   └── skills.py           #   YAML skill loader
│   ├── workiq/                 # WorkIQ integration (M365 context)
│   │   ├── client.py           #   Async subprocess wrapper for `workiq ask`
│   │   └── selector.py         #   2-phase HITL selector (content + keywords)
│   └── registry/               # ★ Agent Catalog & workflows
│       ├── catalog.py          #   AgentCatalog — registration, search, metrics
│       └── workflows.py        #   Workflow bundling & execution
└── tests/
    ├── test_copilot_customization.py  # 15 tests — budget math, identity, model enforcement
    ├── test_forge.py           # 36 tests — loader, context budget, contributions
    ├── test_github_tracker.py  # 82 tests — GitHub Tracker agent, all operations
    ├── test_governance.py      # 162 tests — guardian, selector, enforcement hooks
    ├── test_llm.py             # 30 tests — LLM client, all providers, degradation, agent paths
    ├── test_llm_live.py        # 13 tests — live Azure OpenAI integration (requires az login)
    ├── test_mcp.py             #  7 tests — protocol, server, skills
    ├── test_orchestrator.py    # 17 tests — engine, fan-out, aggregation
    ├── test_registry.py        # 11 tests — catalog, workflows
    ├── test_router.py          # 22 tests — keywords, enriched routing, hints
    ├── test_sub_plan.py        # 32 tests — sub-plan agent, plan selector, pipeline
    └── test_workiq.py          # 58 tests — client, selector, agent, enrichment