multi-agent-clouddash

Imported from wysh3/multi-agent-clouddash (AGENTS.md). Install upstream with npx skills add wysh3/multi-agent-clouddash. Copyright stays with the author.

Project Context for AI Agents

Project

Multi-Agent Customer Support System for CloudDash (fictional B2B SaaS cloud monitoring platform). Take-home assessment for AI Engineering Intern role.

Stack

• Agent Framework: OpenAI Agents SDK (openai-agents)
• LLM: NVIDIA NIM (free tier) — nvidia/nemotron-3-nano-30b-a3b
• Embeddings: nvidia/nv-embedqa-e5-v5 (1024d, QA-optimized)
• Reranker: nvidia/llama-nemotron-rerank-1b-v2
• Vector Store: ChromaDB
• API: FastAPI + uvicorn
• Config: YAML (agents, providers, routing, guardrails)
• Python: 3.12, uv venv

Architecture

• Triage Agent → routes to Technical Support / Billing / Escalation
• RAG pipeline: Query Rewriter → Hybrid Search (ChromaDB + BM25 + RRF) → Reranker
• Agent handoff with context preservation and audit logging
• YAML-configured agents — new agent = one YAML block + one prompt file
• Guardrails: @input_guardrail (prompt injection) + @output_guardrail (hallucination check, PII)

Directory Layout

• clouddash_agents/ — Agent implementations (triage, technical, billing, escalation) + orchestrator + base factory + tools
• retrieval/ — RAG pipeline (ChromaDB, BM25, hybrid, query rewriter)
• handover/ — Handoff protocol, context packaging, audit logging
• guardrails/ — Input/output guardrail functions
• api/ — FastAPI routes, models, middleware
• cli/ — Terminal chat interface
• config/ — YAML configs + system prompts
• providers/ — LLM/embedding/reranker abstraction
• observability/ — JSON structured logging + Langfuse tracing
• knowledge_base/ — 20 sample articles + ingestion script
• tests/ — pytest + pytest-asyncio (mock LLM, real ChromaDB)

Conventions

• Python 3.12+ with uv for venv management
• All LLM calls mocked in tests (AsyncMock) — no live API calls
• Pydantic models for all data structures (conversation state, handover payloads, agent responses)
• Structured JSON logging with trace_id per conversation
• Custom exception hierarchy under CloudDashError
• Working code over perfect code — functional prototype > over-engineering