Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/agent-fleet-orchestration

agent-fleet-orchestration

Verified

The Cianfhoghlaim 12-agent fleet orchestration pattern in `agents/meaisinfhoghlaim/`. Covers 5 frameworks (Custom/ADK/Agno/Pipecat/CopilotKit), the 12 specialist agents (root, curriculum, translation, corpus, research, education_research, bunchloch_research, geospatial, statistics, curriculum_comparison, agui_curriculum, mcp_curriculum), the LiteLLM routing keyword map, the Letta memory layer, the RisingWave event streaming layer, the Langfuse + MLflow observability stack, the OpenClaw channel-fanout gateway (WebChat + Telegram + Slack + Discord + WhatsApp + Teams), the Firecrawl MCP external search surface (per the 2026-08-14-firecrawl-mcp-ccc-dual-search-v1 change), and the British-Isles Education pipeline use case. Use when adding a new agent, debugging routing, wiring Langfuse traces, integrating Letta, or asking 'how do I orchestrate the 12-agent fleet for the LC subjects?'

Agent Fleet Orchestration

Purpose

The agents/ directory houses a 12-agent fleet that spans 5 frameworks. This is genuinely novel — there is no other skill that documents the 12-agent × 5-framework pattern, the LiteLLM routing keyword map, the Letta memory layer, or the cross-quadrant observability contract. The google-adk and agno skills are framework-specific; the agentic-frontend-frameworks skill covers the AG-UI protocol. This skill covers the orchestration of the 12 agents into a single fleet.

v7 flattening migration notes (added 2026-07-19)

Per openspec/changes/2026-07-14-fix-foundation-v7-flattening-and-baml-drift-v1:

  • The 12-agent fleet is now under cianfhoghlaim.meaisinfhoghlaim.agents.* (NOT cianfhoghlaim.agents.meaisinfhoghlaim.* which was the pre-v7 layout)
  • The 5 sub-frameworks are: ADK (Google), Agno, Pydantic-AI, Custom, Pipecat
  • The routing keyword map canonical seed lives at agents/routing_keywords.py
  • Each subject agent's wire metadata is at agents/tuatha/wiring.py:SubjectAgentWiring (NOT in the agent module itself, but in the central wiring file)
  • For new agents: register them in agents/routing_keywords.py, add SubjectAgentWiring entry in wiring.py, then create the L5 CelticAgentOpsComponent config in orchestration/components/layer5_agent_ops.py

When to use this skill

Use when you need to:

  • "Add a new agent to the fleet (the 13th agent)"
  • "Debug a routing keyword misclassification"
  • "Wire Langfuse traces to a new agent"
  • "Integrate the agent with the Letta memory layer"
  • "Understand the cross-quadrant observability contract"
  • "Wire the agent to the RisingWave event stream"

The 12 agents (the fleet)

AgentFrameworkSpecialityLangfuse trace tag
root_agentCustomThe query router + orchestratoragent.root
curriculum_agentADKThe 5-nation curriculum search (NCCA + CfE + CfW + CCEA + SQA)agent.curriculum
translation_agentADKThe 6-Celtic-language translationagent.translation
corpus_agentADKThe Dúchas + Gaois + UD + Canúint + Téarma corpus searchagent.corpus
research_agentADKThe long-form research + citationsagent.research
education_research_agentAgnoThe cross-nation education policy research (LoopAgent)agent.education_research
bunchloch_research_agentAgnoThe M4 MacBook-local research (SequentialAgent)agent.bunchloch_research
geospatial_agentADKThe LSOA / Data Zone spatial analysisagent.geospatial
statistics_agentADKThe education metrics + benchmarkingagent.statistics
curriculum_comparison_agentADKThe cross-nation curriculum mappingagent.curriculum_comparison
agui_curriculum_agentAgnoThe AG-UI streaming curriculum agent (CopilotKit consumer)agent.agui_curriculum
mcp_curriculum_agentADKThe MCP-server-bridged curriculum agent (for external clients)agent.mcp_curriculum

The 12 agents are registered in agents/__init__.py (the canonical home for the agent registry).

The 5 frameworks (the runtime)

FrameworkImplementationUsed by
Customagents/root_agent.py (the query router + LiteLLM)root_agent
ADKgoogle.adk.agents.LlmAgent (via cianfhoghlaim.agents.adk.*)curriculum_agent, translation_agent, corpus_agent, research_agent, geospatial_agent, statistics_agent, curriculum_comparison_agent, mcp_curriculum_agent
Agnoagents/agno/team.py (the EducationTeam)education_research_agent, bunchloch_research_agent, agui_curriculum_agent
Pipecatagents/voice_agent.py (the real-time audio transport)(the voice agent is not in the 12 above; it's a separate voice channel)
CopilotKitagents/adk/agui_curriculum_agent.py (the AG-UI consumer)(the CopilotKit consumer is the front-end; it's not an agent)

The 5 frameworks share the LiteLLM gateway at litellm.cianfhoghlaim.ie:4000 as the single LLM proxy.

The LiteLLM routing keyword map (the 12-bucket)

The root_agent does a keyword-based classification of the user query and routes to one of the 12 agents. The keyword map:

AgentKeywords (in priority order)
curriculum_agent"curriculum", "spec", "learning outcome", "ncca", "cfe", "cfw", "ccea", "sqa", "leaving cert", "gcse", "a-level"
translation_agent"translate", "gaeilge", "irish", "scottish gaelic", "welsh", "cymraeg", "brezhoneg", "cornish", "manx"
corpus_agent"corpus", "duchas", "gaois", "tearma", "logainm", "canuint", "foclóir"
research_agent"research", "paper", "cite", "doi", "arxiv"
education_research_agent"policy", "report", "oecd", "european commission", "unesco"
bunchloch_research_agent"m4", "macbook", "local model", "federated", "on-device"
geospatial_agent"geospatial", "lsoa", "data zone", "map", "school location"
statistics_agent"statistics", "metric", "benchmark", "performance", "kpi"
curriculum_comparison_agent"compare", "cross-nation", "side-by-side", "uk vs ireland"
agui_curriculum_agent"ag-ui", "streaming", "copilot", "react"
mcp_curriculum_agent"mcp", "model context protocol", "tool"
default(no keyword match) → root_agent itself

The 12-bucket map is in agents/root_agent.py:ROUTING_KEYWORDS.

The OpenClaw channel-fanout gateway (the inbound surface)

OpenClaw (the infrastructure/stacks/openclaw/ stack at openclaw.cianfhoghlaim.ie:18789) sits inbound to the fleet — it is the channel-fanout gateway that delivers user messages from 6 external channels into the 12-agent fleet:

ChannelProtocolDefault routing (configurable in openclaw.json)
WebChatHTTP POST /api/messagescurriculum_agent (the canonical default)
TelegramBot API long-pollcurriculum_agent
SlackEvents API + Socket Moderesearch_agent
DiscordDiscord Gatewaymythology_narrator (Tuatha-side)
WhatsAppWhatsApp Business Cloud API webhookcurriculum_agent
Microsoft TeamsBot Framework (port 3978)research_agent

OpenClaw's 3-layer auth:

  1. Pangolin Traefik middleware (tinyauth + secure-headers) on openclaw.cianfhoghlaim.ie — Pocket ID OIDC
  2. Per-channel allow_from ACLs in openclaw.json (empty by default → all senders must pair)
  3. DM policy pairing — each new sender must be approved via POST /api/pairing/approve with the OPENCLAW_GATEWAY_TOKEN

OpenClaw v1 uses the OpenCode Go single-key LLM provider chain (not LiteLLM); LiteLLM is a documented future-path triggered by an env-flag swap. The v1 LLM chain is:

primary:  OpenCode Go gateway (https://opencode.ai/zen/go/v1) — single OPENCODE_GO_API_KEY
fallback: minimax-coding-plan/minimax-m3 — MINIMAX_API_KEY

OpenClaw's trace contract:

  • Langfuse at langfuse.cianfhoghlaim.ie:3000 via OTLP/HTTP (OTEL_EXPORTER_OTLP_ENDPOINT), with service.name=openclaw-gateway and a channel=<name> span attribute
  • LiteLLM is NOT yet wired (in-flight openspec change litellm-minimax-vendor-derisking); once that lands, swap OpenClaw's provider to litellm.cianfhoghlaim.ie:4000 via an env-var override

The full contract is in openspec/changes/add-openclaw-stack-and-channel-fanout/specs/meaisinfhoghlaim-agent-frameworks/spec.md.

The Letta memory layer (the cross-agent state)

Every agent in the fleet reads + writes to the Letta memory layer at letta.cianfhoghlaim.ie:8283 (the long-term agent memory). The contract:

  • Per-agent memory: letta.get_memory(agent_id=...) returns a Memory object with the agent's conversation history + user preferences + learning state
  • Per-user memory: letta.get_user_memory(user_id=...) returns a UserMemory object with the user's learning progress + skill tree + quest history
  • Per-quest memory: letta.get_quest_memory(quest_id=...) returns a QuestMemory object with the quest state + collected achievements

The 3 memory types are documented in agents/letta_client.py:MemoryType.

The RisingWave event stream (the cross-agent events)

Every agent in the fleet publishes events to the RisingWave stream at risingwave.cianfhoghlaim.ie:4566 (the Kafka-compatible event bus). The contract:

  • Topic: agent.events (1 topic for the whole fleet)
  • Schema: {"agent_id": str, "event_type": str, "user_id": str, "timestamp": int, "payload": dict}
  • Event types: agent.started, agent.completed, agent.failed, agent.routed, tool.called, tool.completed, memory.read, memory.written, citation.found

The RisingWave connector is in agents/risingwave_publisher.py:RisingWavePublisher.

The Langfuse + MLflow observability stack (the 2 traces)

Every agent in the fleet is wrapped in 2 traces:

  1. Langfuse (langfuse.cianfhoghlaim.ie:3000) — the per-request LLM cost + latency + prompt version
  2. MLflow (mlflow.cianfhoghlaim.ie:5000) — the per-experiment prompt comparison + hyperparameter sweep

The 2 traces are emitted from agents/_shared/observability/tracing.py via the langfuse_trace + mlflow_log decorators.

The cross-quadrant observability contract

The agent fleet integrates with the broader Cianfhoghlaim observability stack:

  • Oideachais reads the agent traces via the FastAPI middleware at web/apps/cianfhoghlaim-web/src/middleware/agui/streaming.py
  • Tuatha consumes the agent output via the TanStack Start CopilotKit component
  • Croílár mirrors the agent state via the Convex subscriptions
  • Spaces expose a subset of agents via the HF Space demos

The contract is documented in agents/_shared/observability/cross_quadrant.py.

Worked example: add the 13th agent (the 4-Framework Hybrid)

  1. Add the agent to meaisinfoghlaim/agents/__init__.py:

    from .hybrid_curriculum_agent import hybrid_curriculum_agent
    __all__ += ["hybrid_curriculum_agent"]
    
  2. Create agents/hybrid_curriculum_agent.py that wraps both the ADK curriculum_agent and the Agno education_research_agent (the "4-Framework Hybrid").

  3. Add the routing keyword to agents/root_agent.py:ROUTING_KEYWORDS:

    "hybrid_curriculum_agent": ["hybrid", "4-framework", "all frameworks"],
    
  4. Add the Langfuse trace tag (agent.hybrid_curriculum) + the MLflow experiment name.

  5. Add the Letta memory type (HybridCurriculumMemory).

  6. Add the RisingWave event type (agent.hybrid.completed).

  7. Add a test in agents/meaisinfhoghlaim/tests/test_agents.py that exercises the routing + the Letta memory + the RisingWave event.

Common failure modes

SymptomCauseFix
root_agent routes to the wrong agentThe keyword list is ambiguousAdd more keywords to the correct bucket
An agent can't find the user's memoryThe Letta client lost the connectionCheck the Letta server is up + the API key is correct
Langfuse traces are missingThe @langfuse_trace decorator was forgottenAdd the decorator to the new agent
MLflow shows 2 competing experimentsThe agent was registered twicePick one MLflow experiment name per agent
RisingWave events are droppedThe publisher buffer is fullIncrease buffer_size in risingwave_publisher.py
The cross-quadrant mirror is staleThe Convex subscription disconnectedRestart the Convex WebSocket

Cross-references

  • .agents/skills/google-adk/SKILL.md — the ADK framework patterns
  • .agents/skills/agno/SKILL.md — the Agno framework patterns
  • .agents/skills/agentic-frontend-frameworks/SKILL.md — the AG-UI + CopilotKit consumer
  • .agents/skills/agent-observability/SKILL.md — the Langfuse + MLflow + RAGAS + Logfire stack
  • .agents/skills/agent-memory-systems/SKILL.md — the Letta + Graphiti + Cognee + LanceDB + FalkorDB memory stack
  • .agents/skills/infrastructure-stacks/SKILL.md — the openclaw stack (6-file GOLD_STANDARD + arm1-oci deploy)
  • .agents/skills/INDEXING_AND_COGNITION.md §8 — the OpenCode agent + skill + MCP registry (7 agents, 10 MCPs, 13 model-layer agents; canonical home for opencode.json structure)
  • agents/__init__.py — the 12-agent registry
  • agents/root_agent.py — the query router + LiteLLM
  • agents/letta_client.py — the Letta memory layer
  • agents/risingwave_publisher.py — the RisingWave event stream
  • agents/_shared/observability/tracing.py — the Langfuse + MLflow traces
  • infrastructure/stacks/openclaw/config/openclaw.json — the channel + routing config
  • infrastructure/komodo/procedures/deploy-openclaw-arm1-oci.toml — the 5-stage arm1-oci deploy

Email triage agent (2026-06-29)

The new email_triage ADK agent (on the oideachais stack, port 7778) extends the agent fleet with 4 read-only tools that operate against the new leabharlann_inbox_* Dagster assets + the cianfhoghlaim_inbox_messages LanceDB table:

  • classify_email_thread(thread_id: str) -> EmailClassificationResult — wraps the BAML ClassifyEmail function
  • summarise_thread(thread_id: str, max_chars: int = 500) -> str — wraps BAML ExtractEmailThread
  • link_thread_to_research(thread_id: str, k: int = 5) -> list[ResearchLink] — wraps BAML LinkEmailToResearch against the top-k LanceDB neighbours
  • find_loose_threads(account: str, days_idle_min: int = 7) -> list[ThreadSummary] — queries DuckLake for threads where the user has not replied in ≥ N days, sorted by urgency

The agent is not registered in this skill's "12-agent registry" (it is an oideachais ADK agent, not a meaisínfhoghlaim agent). The full pipeline (BAML + Dagster + marimo + cognify + openclaw) is documented in .agents/skills/cianfhoghlaim-email-triage/SKILL.md.


Hermes autonomous runtime (added 2026-06-30)

The agent-platform group is now 3 vertices (was 2):

  1. OpenClaw — channel-fanout gateway (8 messaging channels + WebChat)
  2. OpenChamber — browser IDE (OpenCode UI)
  3. Hermes — autonomous long-running agent runtime (NousResearch/hermes-agent v0.17.0)

The Hermes stack lives at bonneagar/stacks/hermes/ and is deployed on bunchloch (MacBook M4 Max, 32 GB headroom). The 3 vertices share the same litellm LLM chokepoint (the M3 plan) and the same Langfuse observability destination.

The Hermes 3-layer auth model (matches OpenClaw's):

  1. Pangolin TinyAuth (Pocket ID OIDC) at Traefik
  2. users.allowlist in config/hermes.yaml (Pocket ID subject allowlist, populated from day one with the operator's subject)
  3. channels.<name>.allow_from per channel

The hermes claw migrate path (which retires OpenClaw) is NOT used in v1. The 3 vertices coexist.

Migrated from (2026-07-06 spec-and-plans-consolidation)

  • openspec/specs/author-archive-ui-grounding/spec.md (the BAML UiType enum with 10 values: SEARCH_BOX / FORM / DASHBOARD / MAP / LOGIN_WALL / FILE_DOWNLOAD / CAROUSEL / TIMELINE / OTHER / NONE) was deleted on 2026-07-06 by the 2026-07-06-drift-cleanup-and-v4-alignment change. The UiType enum now lives at baml/agent_fleet/ui_types.baml (canonical); UI grounding hints are surfaced by the browser-agent tool calls.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall