@polymorphism-tech/morph-spec 2.2.0 → 2.4.0

package/content/.claude/skills/specialists/ai-system-architect.md

@@ -1,604 +1,192 @@
-# AI System Architect
-
-Especialista em arquitetura de sistemas agênticos, orquestração multi-agente e design patterns de IA.
-
-## Responsabilidades
-
-1. **Desenhar arquiteturas agênticas** complexas e escaláveis
-2. **Definir padrões de orquestração** (workflows, comunicação inter-agentes)
-3. **Implementar pipelines RAG** (Retrieval-Augmented Generation)
-4. **Avaliar estratégias** de chunking, embedding e retrieval
-5. **Selecionar padrões adequados** dos 20 padrões de design agêntico
-
-## Triggers
-
-Keywords: `orchestration`, `multi-agent`, `workflow`, `agent-to-agent`, `a2a`, `system design`, `reflection`, `planning`, `memory`, `rag`, `vector search`, `chunking`, `embedding`, `retrieval`, `agentic`, `reasoning`, `chain-of-thought`, `tree-of-thought`
-
-## 20 Padrões de Design Agêntico
-
-> Baseado no framework de padrões de design para agentes de IA
-
-### 1. Prompt Chaining (Encadeamento de Prompts)
-**Uso:** Processos multi-step com validação entre etapas
-
-**Quando usar:**
-- Transformação de dados complexos
-- Pipelines mistos (GenAI + código determinístico)
-- Processamento de documentos
-
-**Trade-offs:**
-- ✅ Modular, múltiplos pontos de validação
-- ⚠️ Context explosion, error propagation
-- 💡 Ideal: 3-5 steps
-
-### 2. Routing (Roteamento)
-**Uso:** Direcionar requisições ao agente especialista correto
-
-**Quando usar:**
-- Múltiplos domínios ou especializações
-- Prevenção de misfires (agente usando tool errada)
-
-**Trade-offs:**
-- ✅ Especialização, escalabilidade
-- ⚠️ Roteamento incorreto possível
-- 💡 Adicionar "manager agent" para casos ambíguos
-
-### 3. Parallelization (Paralelização)
-**Uso:** Dividir trabalho grande em chunks independentes processados simultaneamente
-
-**Quando usar:**
-- Processamento de dados em larga escala
-- Operações time-sensitive
-- Web scraping multi-página
-
-**Trade-offs:**
-- ✅ Especialização, reduz tempo total
-- ⚠️ Complexidade de coordenação
-- 💡 Azure Durable Functions (Fan-out/Fan-in)
-
-### 4. Reflection (Reflexão)
-**Uso:** Gerar draft → crítica → refinamento até atingir padrões de qualidade
-
-**Quando usar:**
-- Controle de qualidade rigoroso
-- Tarefas criativas com resultado controlado
-
-**Trade-offs:**
-- ✅ Foco em qualidade, melhoria iterativa
-- ⚠️ Custo elevado (múltiplas chamadas)
-- 💡 Limitar a 3 iterações
-
-### 5. Tool Use (Uso de Ferramentas)
-**Uso:** Agente descobre, verifica permissões e chama ferramentas externas
-
-**Quando usar:**
-- Workflow multi-step
-- Necessidade de dados externos
-- Integração com sistemas
-
-**Trade-offs:**
-- ✅ Melhoria de qualidade, redução de erros
-- ⚠️ Misfire propagation
-- 💡 Microsoft Agent Framework: `[AgentTool]` attribute
-
-### 6. Planning (Planejamento)
-**Uso:** Criar plano step-by-step antes de executar
-
-**Quando usar:**
-- Workflows orientados a objetivos
-- Project management
-- Desenvolvimento de software
-
-**Trade-offs:**
-- ✅ Execução estratégica, menos alucinação
-- ⚠️ Setup complexo, coordenação de múltiplos agentes
-- 💡 "Planejar e planejar e planejar até estar pronto"
-
-### 7. Multi-Agent Collaboration (Colaboração Multi-Agente)
-**Uso:** Múltiplos agentes especializados coordenados por gerente central
-
-**Estruturas de coordenação:**
-- **Boss structure** — um agente gerencia todos
-- **Democratic** — todos iguais (difícil de calibrar)
-- **Bulletin board** — comunicação via posts compartilhados
-
-**Quando usar:**
-- Refinamento iterativo
-- Desenvolvimento de produto/software
-- Múltiplas fases e tickets
-
-**Trade-offs:**
-- ✅ Especialização, processamento paralelo
-- ⚠️ Setup e testes extensivos
-- 💡 Microsoft Agent Framework Workflows
-
-### 8. Memory Management (Gestão de Memória)
-**Uso:** Classificar informação como memória de curto prazo, episódica ou conhecimento de longo prazo
-
-**Tipos de memória:**
-- **Short-term** — duração da sessão
-- **Episodic** — eventos específicos
-- **Long-term/Knowledge** — informação permanente
-
-**Quando usar:**
-- Continuidade conversacional
-- Experiências personalizadas
-- Plataformas educacionais
-
-**Trade-offs:**
-- ✅ Preservação de contexto
-- ⚠️ Riscos de segurança/privacidade
-- 💡 Agent Framework: Threads para persistência
-
-### 9. Learning and Adaptation (Aprendizado e Adaptação)
-**Uso:** Coletar feedback, limpar dados, atualizar prompts/políticas
-
-**Quando usar:**
-- Serviços que requerem feedback loop
-- Sistemas que precisam melhorar continuamente
-
-**Trade-offs:**
-- ✅ Melhoria contínua
-- ⚠️ Pode aprender coisa errada
-- 💡 A/B testing + monitoring
-
-### 10. Goal Setting and Monitoring (Definição e Monitoramento de Objetivos)
-**Uso:** Definir objetivos SMART com deadlines, monitorar métricas
-
-**Quando usar:**
-- Projetos complexos
-- Operações autônomas
-- Execução estratégica
-
-**Trade-offs:**
-- ✅ Eficiência de recursos
-- ⚠️ Conflitos de objetivos
-- 💡 Application Insights para monitoring
-
-### 11. Exception Handling and Recovery (Tratamento de Exceções)
-**Uso:** Capturar erros em workflows agênticos, retry com exponential backoff
-
-**Quando usar:**
-- Sistemas em produção
-- Quality assurance
-- Erros críticos
-
-**Trade-offs:**
-- ✅ Visibilidade de performance, múltiplos fallbacks
-- ⚠️ Infraestrutura complexa
-- 💡 Azure Durable Functions: automatic retry
-
-### 12. Human-in-the-Loop (Humano no Loop)
-**Uso:** Intervenção humana para decisões de alto risco
-
-**Quando usar:**
-- Decisões de alto risco
-- Compliance regulatório
-- Edge cases
-
-**Trade-offs:**
-- ✅ Mais confiança no sistema
-- ⚠️ Latência adicional
-- 💡 Review queue + prioritização
-
-### 13. Knowledge Retrieval / RAG (Recuperação de Conhecimento)
-**Uso:** Indexar documentos com chunking e embeddings pesquisáveis
-
-**Pipeline RAG:**
-```
-Extração → Staging → Chunking → Embedding → Indexação → Retrieval
-```
-
-**Estratégias de chunking:**
-- Fixed size chunks
-- Markdown Header Splitter
-- Semantic boundaries
-- Token-based
-
-**Quando usar:**
-- Necessidades de conhecimento documental
-- Dados privados/proprietários
-
-**Trade-offs:**
-- ✅ Accuracy, escalabilidade
-- ⚠️ Infraestrutura para construir e manter
-- 💡 Azure AI Search + Semantic Kernel
-
-### 14. Inter-Agent Communication (Comunicação Inter-Agentes)
-**Uso:** Agentes comunicam via sistema de mensagens estruturado
-
-**Protocolos:**
-- **A2A (Agent-to-Agent)** — spec padronizada
-- **Agent Cards** — metadados compartilhados
-
-**Quando usar:**
-- Sistemas enterprise complexos
-- Orquestração distribuída
-
-**Trade-offs:**
-- ✅ Fault isolation
-- ⚠️ Complexidade extrema
-- 💡 Avaliar se realmente necessário (geralmente não)
-
-### 15. Resource-Aware Optimization (Otimização Consciente de Recursos)
-**Uso:** Rotear tarefas para modelos apropriados baseado em complexidade/custo
-
-**Estratégia:**
-- Tarefas simples → gpt-4o-mini
-- Tarefas complexas → gpt-4o
-- Tarefas de raciocínio → o1-mini
-
-**Quando usar:**
-- Operações cost-sensitive
-- Processamento de alto volume
-
-**Trade-offs:**
-- ✅ Redução de custos
-- ⚠️ Tuning de complexidade
-- 💡 Router agent classifica complexidade
-
-### 16. Reasoning Techniques (Técnicas de Raciocínio)
-**Métodos disponíveis:**
-
-#### Chain of Thought (Sequencial)
-```
-Step 1 → Think → Reason → Conclude → Step 2 → ...
-```
-
-#### Tree of Thought (Branching)
-```
-Problem → Generate Branches → Explore → Prune Dead Branches
-```
-
-#### Self-Consistency
-```
-Generate Multiple Solutions → Score → Select Best
-```
-
-#### Adversarial/Debate
-```
-Proponent Agent ↔ Opponent Agent → Exchange Arguments
-```
-
-**Quando usar:**
-- Problemas muito complexos
-- Raciocínio matemático
-- Planejamento estratégico em escala
-
-**Trade-offs:**
-- ✅ Processo exaustivo e robusto
-- ⚠️ Alto consumo de tokens, latência
-- 💡 9 em 10 vezes não é necessário
-
-### 17. Evaluation and Monitoring (Avaliação e Monitoramento)
-**Uso:** Quality gates, golden tests, monitoramento contínuo de drift
-
-**Métricas:**
-- Accuracy
-- Performance SLAs
-- Compliance
-- Drift detection
-
-**Quando usar:**
-- Sistemas production-grade
-- Enterprise, SaaS
-- Healthcare, finance
-
-**Trade-offs:**
-- ✅ Confiabilidade
-- ⚠️ Alert fatigue
-- 💡 Application Insights + Azure Monitor
-
-### 18. Guardrails and Safety Patterns (Guardrails e Segurança)
-**Uso:** Verificar inputs para conteúdo prejudicial, PII, injeções
-
-**Checks:**
-- PII Detection → Redact/Mask
-- Injection Detection → Filter/Block
-- Malicious Content → Filter/Block
-- Risk Classification → Human-in-Loop se high
-
-**Quando usar:**
-- Sistemas public-facing
-- Quando PR está em jogo
-- Input de texto aberto
-
-**Trade-offs:**
-- ✅ Mitigação de risco, proteção de marca
-- ⚠️ Falsos positivos, fricção
-- 💡 Estratégia de prompts pré-definidos > texto livre
-
-### 19. Prioritization (Priorização)
-**Uso:** Pontuar tarefas baseado em valor, risco, esforço, urgência
-
-**Fórmula:**
-```
-Priority = (Value × Effort) × Urgency / Risk
-```
-
-**Quando usar:**
-- Ambientes dinâmicos
-- Task management
-- Customer service
-
-**Trade-offs:**
-- ✅ Adaptabilidade, transparência
-- ⚠️ Context switching
-- 💡 Dependency graph + reassessment
-
-### 20. Exploration and Discovery (Exploração e Descoberta)
-**Uso:** Explorar amplamente espaço de conhecimento, identificar padrões, focar em áreas promissoras
-
-**Fluxo:**
-```
-Research Goal → Explore Sources → Compile → Map Knowledge Space →
-Cluster Themes → Target Exploration → Synthesize Insights
-```
-
-**Quando usar:**
-- Projetos de pesquisa
-- Análise competitiva detalhada
-- R&D
-
-**Trade-offs:**
-- ✅ Innovation enablement
-- ⚠️ Time-sensitive, resource-heavy
-- 💡 Perplexity Deep Research, Claude Deep Research
-
----
-
-## Frameworks de Categorização de Agentes
-
-### Framework TACO (KPMG)
-
-| Categoria | Descrição | Autonomia |
-|-----------|-----------|-----------|
-| **Taskers** | Executam tarefas individuais bem definidas | Humano no loop |
-| **Automators** | Gerenciam tarefas complexas multi-sistema | Automação |
-| **Collaborators** | Companheiros de IA adaptativos | Objetivos multidimensionais |
-| **Orchestrators** | Sistemas transformativos | Coordenação de múltiplos agentes |
-
-### Framework Funcional (7 tipos)
-
-1. **Simple Reflex Agents** — regras predefinidas
-2. **Model-Based Reflex Agents** — avaliação de consequências
-3. **Goal-Based Agents** — planejamento de sequências de ações
-4. **Learning Agents** — melhoram com experiência
-5. **Utility-Based Agents** — gerenciam trade-offs entre objetivos
-6. **Hierarchical Agents** — desconstroem tarefas em subtarefas
-7. **Multi-Agent Systems** — especialização e colaboração
-
----
-
-## Pipeline RAG com Stack Microsoft
-
-> "Dominar o processo de geração de informação"
-
-### Arquitetura
-```
-┌─────────────────────────────────────────────────────────────┐
-│              PIPELINE RAG - STACK MICROSOFT                 │
-└─────────────────────────────────────────────────────────────┘
-    │
-    ├─→ EXTRAÇÃO: HttpClient → Azure Blob Storage (staging)
-    │
-    ├─→ PROCESSAMENTO: Semantic Kernel → Chunking Strategies
-    │
-    ├─→ EMBEDDING: Azure OpenAI text-embedding-3-small
-    │
-    ├─→ INDEXAÇÃO: Azure AI Search (vector store com HNSW)
-    │
-    ├─→ AVALIAÇÃO: Cosine Similarity → Ranking de Estratégias
-    │
-    └─→ DEPLOY: Azure Durable Functions (orquestração)
-```
-
-### Estratégias de Chunking (Semantic Kernel)
-
-1. **Paragraph Splitter** — quebra por parágrafos
-2. **Markdown Header Splitter** — quebra por headers (#, ##, ###)
-3. **Token-based Splitter** — quebra por quantidade de tokens
-4. **Semantic Splitter** — quebra por similaridade semântica
-
-**Princípio:** Testar TODAS as estratégias e rankear por métricas
-
-### Métricas de Avaliação
-
-- **Score médio** de similaridade nos resultados
-- **Token count médio** dos chunks recuperados
-- **Relevância** para queries de teste
-
-### Por Que Staging em Blob Storage?
-
-| Benefício | Explicação |
-|-----------|------------|
-| **Imutabilidade** | Dados originais nunca são alterados |
-| **Versionamento** | Blob Storage suporta versioning nativo |
-| **Custo baixo** | Storage é muito mais barato que compute |
-| **Fallback** | Bug no processamento não perde dados |
-| **Auditoria** | Rastreamento completo de origem |
-
-### Integração com Microsoft Agent Framework
-
-```csharp
-// Tool de busca semântica
-[AgentTool("search_knowledge")]
-public async Task<SearchResult[]> SearchKnowledgeAsync(
-    [Description("Query de busca")] string query,
-    CancellationToken ct = default)
-{
-    // 1. Gerar embedding da query
-    var queryEmbedding = await _embeddings.GenerateAsync(query, ct);
-
-    // 2. Buscar no Azure AI Search (vector search)
-    var results = await _searchClient.SearchAsync<KnowledgeChunk>(
-        query,
-        new SearchOptions
-        {
-            VectorSearch = new VectorSearchOptions
-            {
-                Queries = { new VectorizedQuery(queryEmbedding) { KNearestNeighborsCount = 5 } }
-            }
-        },
-        ct
-    );
-
-    return results.Value.GetResults().ToArray();
-}
-```
-
----
-
-## Microsoft Agent Framework: Orquestração
-
-### Agentes Especializados Pequenos > Agente Monolítico Grande
-
-**Exemplo: Projeto Lucy (Home Assistant)**
-```
-Orchestration Agent
-    ├─→ Light Agent (196 lights)
-    ├─→ Music Agent (Spotify/local)
-    ├─→ Climate Agent (HVAC)
-    └─→ ...
-```
-
-**Vantagens:**
-- Cada agente conhece apenas seu domínio
-- Modelos menores = mais barato, mais rápido
-- Busca semântica para entity matching (embeddings)
-
-### Workflows com Microsoft.Agents.AI.Workflows
-
-```csharp
-// Criar workflow sequencial
-var workflowBuilder = new AgentWorkflowBuilder()
-    .AddStep(researchAgent)
-    .AddStep(analysisAgent)
-    .AddStep(writerAgent);
-
-var orchestrationAgent = workflowBuilder.Build();
-
-// Executar pipeline
-var result = await orchestrationAgent.RunAsync("Create report about AI trends");
-```
-
-### A2A (Agent-to-Agent) Communication
-
-```csharp
-// Expor agentes via A2A spec
-app.MapA2A();  // Endpoints automáticos:
-               // GET /agents → Lista agent cards
-               // POST /message/send → JSON REST
-               // POST /jsonrpc → JSON-RPC
-```
-
----
-
-## Quando NÃO Usar Agent Framework
-
-| Cenário | Recomendação |
-|---------|--------------|
-| Single LLM call resolve | Use Microsoft.Extensions.AI direto |
-| Sem tools necessários | ChatClient simples |
-| Modelo < 3B parâmetros | Tool calling não funciona bem |
-| Apenas summarização/tradução | Não precisa de agente |
-
-## Quando USAR
-
-- Tools/function calling necessários
-- Workflows assíncronos
-- Multi-step processes
-- Orquestração de múltiplos agentes
-- Integração com sistemas externos
-
----
-
-## Mentalidade de Engenharia
-
-| Amador | Profissional |
-|--------|--------------|
-| "Joga lá e Deus abençoa" | "Domino cada etapa do processo" |
-| Uma estratégia de chunking | Testa 5+ estratégias |
-| Sem tracking de dados | Rastreamento completo |
-| Espera cliente reclamar | Application Insights alerts |
-| Código descartável | Class libraries reutilizáveis |
-| Funciona na minha máquina | Durable Functions orquestrando |
-
----
-
-## Combinações de Padrões
-
-| Combinação | Caso de Uso |
-|------------|-------------|
-| Prompt Chaining + Reflection | Geração de conteúdo com qualidade controlada |
-| Routing + Tool Use | Customer service com múltiplas integrações |
-| Planning + Multi-Agent | Projetos complexos de desenvolvimento |
-| Memory + Learning | Assistentes personalizados que evoluem |
-| Parallelization + Exception Handling | Processamento de dados em escala |
-| Resource-Aware + Routing | Otimização de custos em alto volume |
-| Human-in-Loop + Guardrails | Sistemas críticos com compliance |
-
----
-
-## Documentação de Referência
-
-- [20 Padrões de Design Agêntico](../../.wiki/ai/20-agentic-design-patterns.md)
-- [Transformação Agêntica: Frameworks](../../.wiki/ai/transformacao-agentica-frameworks-categorias-agentes-ia-estrategia-organizacional.md)
-- [Microsoft Agent Framework na Prática](../../.wiki/microsoft-agent-framework/dotnet-ai-community-standup-agent-framework-visao-pratica.md)
-- [Pipeline RAG .NET](../../.wiki/microsoft-agent-framework/pipeline-indexacao-rag-dotnet-microsoft-stack.md)
-- [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/)
-- [Azure AI Search](https://learn.microsoft.com/azure/search/)
-- [Semantic Kernel](https://learn.microsoft.com/semantic-kernel/)
-
----
-
-## Checklist de Arquitetura Agêntica
-
-### Design de Sistema
-- [ ] Padrões de design selecionados e justificados
-- [ ] Estrutura de orquestração definida (Boss, Democratic, Bulletin Board)
-- [ ] Agentes especializados mapeados com responsabilidades claras
-- [ ] Comunicação inter-agentes desenhada (A2A se necessário)
-
-### Pipeline RAG (se aplicável)
-- [ ] Fonte de dados identificada e acessível
-- [ ] Staging em Blob Storage configurado
-- [ ] Múltiplas estratégias de chunking testadas
-- [ ] Embeddings gerados via Azure OpenAI
-- [ ] Azure AI Search index configurado (vector + hybrid)
-- [ ] Métricas de avaliação definidas e executadas
-- [ ] Estratégia vencedora selecionada e documentada
-
-### Memória e Estado
-- [ ] Tipo de memória definido (short-term, episodic, long-term)
-- [ ] Threads configuradas para conversações persistentes
-- [ ] Estratégia de compressão de contexto implementada
-- [ ] Metadata tags definidos para retrieval
-
-### Orquestração
-- [ ] Microsoft.Agents.AI.Workflows configurado
-- [ ] Durable Functions para workflows complexos (se necessário)
-- [ ] Fan-out/Fan-in para processamento paralelo
-- [ ] Error handling e retry policies definidos
-
-### Monitoring e Avaliação
-- [ ] Application Insights configurado
-- [ ] Métricas de performance monitoradas (accuracy, latency, cost)
-- [ ] Drift detection implementado
-- [ ] Alertas proativos configurados (Teams/Slack)
-
-### Segurança e Compliance
-- [ ] Guardrails implementados (PII, injection, malicious content)
-- [ ] Human-in-the-Loop para decisões de alto risco
-- [ ] Risk classification implementado
-- [ ] Compliance com regulações (se aplicável)
-
-### Custos
-- [ ] Resource-Aware Optimization implementado
-- [ ] Modelos selecionados por complexidade (gpt-4o-mini vs gpt-4o)
-- [ ] Token usage monitorado
-- [ ] Custos estimados e documentados
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# AI System Architect
+
+Expert in agentic system architecture, multi-agent orchestration, and RAG pipelines.
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** orchestration, multi-agent, rag, vector search, embedding, agentic, memory, reasoning
+
+> **Ref:** `agent-framework-workflows.md` — Workflow patterns with AgentWorkflowBuilder
+> **Ref:** `agent-framework-production.md` — Middleware, A2A, MCP, caching
+> **Ref:** `vector-search-rag.md` — Vector Search + RAG with EF Core 10
+
+## Responsibilities
+
+1. Design scalable agentic architectures
+2. Define orchestration patterns (workflows, inter-agent communication)
+3. Implement RAG pipelines (chunking, embedding, retrieval)
+4. Select patterns from 20 agentic design patterns
+
+---
+
+## 20 Agentic Design Patterns
+
+| # | Pattern | Use Case | When to Use | Key Trade-off |
+|---|---------|----------|-------------|---------------|
+| 1 | **Prompt Chaining** | Multi-step processing | Data transformation, pipelines | Modular vs context explosion |
+| 2 | **Routing** | Direct to specialist | Multiple domains | Specialization vs misrouting |
+| 3 | **Parallelization** | Independent chunks | Large-scale processing | Speed vs coordination complexity |
+| 4 | **Reflection** | Draft → critique → refine | Quality control, creative tasks | Quality vs cost (limit 3 iterations) |
+| 5 | **Tool Use** | External tool calls | Multi-step workflows | Quality vs misfire propagation |
+| 6 | **Planning** | Step-by-step before execute | Goal-oriented workflows | Strategic vs setup complexity |
+| 7 | **Multi-Agent Collaboration** | Specialized agents + manager | Iterative refinement, dev | Specialization vs extensive testing |
+| 8 | **Memory Management** | Short/episodic/long-term | Continuity, personalization | Context preservation vs privacy risk |
+| 9 | **Learning & Adaptation** | Feedback → update prompts | Continuous improvement | Improvement vs learning wrong things |
+| 10 | **Goal Setting & Monitoring** | SMART goals + metrics | Complex projects, autonomous ops | Efficiency vs goal conflicts |
+| 11 | **Exception Handling** | Retry + exponential backoff | Production systems | Visibility vs infra complexity |
+| 12 | **Human-in-the-Loop** | Human review for high-risk | Compliance, edge cases | Trust vs latency |
+| 13 | **Knowledge Retrieval (RAG)** | Chunk + embed + search | Private/proprietary data | Accuracy vs infra to maintain |
+| 14 | **Inter-Agent Communication** | Structured messaging (A2A) | Enterprise, distributed | Fault isolation vs extreme complexity |
+| 15 | **Resource-Aware Optimization** | Route by complexity/cost | Cost-sensitive, high volume | Cost reduction vs tuning effort |
+| 16 | **Reasoning Techniques** | CoT, ToT, Self-Consistency | Complex problems, math | Robust vs token-heavy (rarely needed) |
+| 17 | **Evaluation & Monitoring** | Quality gates, drift detection | Production, enterprise | Reliability vs alert fatigue |
+| 18 | **Guardrails & Safety** | PII, injection, malicious check | Public-facing systems | Risk mitigation vs false positives |
+| 19 | **Prioritization** | Score by value/risk/effort | Dynamic environments, task mgmt | Adaptability vs context switching |
+| 20 | **Exploration & Discovery** | Broad knowledge exploration | Research, competitive analysis | Innovation vs resource-heavy |
+
+### Common Pattern Combinations
+
+| Combination | Use Case |
+|------------|----------|
+| Prompt Chaining + Reflection | Content generation with quality control |
+| Routing + Tool Use | Customer service with integrations |
+| Planning + Multi-Agent | Complex development projects |
+| Memory + Learning | Personalized assistants that evolve |
+| Parallelization + Exception Handling | Data processing at scale |
+| Human-in-Loop + Guardrails | Critical systems with compliance |
+
+---
+
+## Microsoft Agent Framework Orchestration
+
+### Workflow Patterns
+
+```csharp
+// Sequential — pipeline processing
+Workflow sequential = AgentWorkflowBuilder.BuildSequential(researcher, analyst, writer);
+AIAgent seqAgent = await sequential.AsAgentAsync();
+
+// GroupChat — iterative refinement with manager
+Workflow groupChat = AgentWorkflowBuilder
+    .CreateGroupChatBuilderWith(agents =>
+        new AgentWorkflowBuilder.RoundRobinGroupChatManager(agents)
+        { MaximumIterationCount = 3 })
+    .AddParticipants(writer, editor, reviewer)
+    .Build();
+
+// Handoff — dynamic routing
+var handoff = AgentWorkflowBuilder.StartHandoffWith(triageAgent)
+    .WithHandoffs(triageAgent, [specialistA, specialistB])
+    .WithHandoff(specialistA, triageAgent)
+    .WithHandoff(specialistB, triageAgent)
+    .Build();
+```
+
+### A2A Protocol
+
+```csharp
+app.MapA2A(agent, "/a2a/agent-name", agentCard: new()
+{
+    Name = "Agent Name",
+    Description = "What this agent does.",
+    Version = "1.0"
+});
+// Discovery: GET /a2a/agent-name/v1/card
+// Message:   POST /a2a/agent-name/v1/message:stream
+```
+
+### Small Specialized Agents > Monolithic Agent
+
+Design principle: each agent has one clear responsibility, composed via workflows.
+
+---
+
+## RAG Pipeline with Microsoft Stack
+
+### Architecture
+
+```
+Extraction → Staging (Blob) → Chunking → Embedding → Indexing (AI Search) → Retrieval
+```
+
+### Chunking Strategies
+
+| Strategy | Method | Best For |
+|----------|--------|----------|
+| Paragraph Splitter | By paragraphs | General text |
+| Markdown Header Splitter | By headers (#, ##) | Documentation |
+| Token-based Splitter | By token count | Fixed-size chunks |
+| Semantic Splitter | By semantic similarity | Highest quality |
+
+**Principle:** Test ALL strategies and rank by metrics (avg similarity score, token count, relevance).
+
+### Agent Framework Integration
+
+```csharp
+[Description("Searches knowledge base")]
+public async Task<SearchResult[]> SearchKnowledgeAsync(
+    [Description("Search query")] string query, CancellationToken ct = default)
+{
+    var embedding = await _embeddings.GenerateAsync(query, ct);
+    var results = await _searchClient.SearchAsync<KnowledgeChunk>(query,
+        new SearchOptions { VectorSearch = new() {
+            Queries = { new VectorizedQuery(embedding) { KNearestNeighborsCount = 5 } }
+        }}, ct);
+    return results.Value.GetResults().ToArray();
+}
+```
+
+### Why Staging in Blob Storage?
+
+Immutability, versioning, low cost, fallback on processing bugs, audit trail.
+
+### Key Insight
+
+**LLM comes LAST.** 80% of RAG work happens before the model is called (extraction, chunking, embedding, evaluation).
+
+---
+
+## When NOT to Use Agent Framework
+
+| Scenario | Use Instead |
+|----------|------------|
+| Single LLM call resolves | `IChatClient` directly |
+| No tools needed | `ChatClient.GetResponseAsync()` |
+| Model < 3B params | Tool calling unreliable |
+| Just summarization/translation | No agent needed |
+
+---
+
+## Checklist
+
+### System Design
+- [ ] Patterns selected and justified
+- [ ] Orchestration pattern chosen (Sequential/Concurrent/GroupChat/Handoff/Magentic)
+- [ ] Specialized agents mapped with clear responsibilities
+
+### RAG Pipeline (if applicable)
+- [ ] Data source identified and accessible
+- [ ] Staging in Blob Storage configured
+- [ ] Multiple chunking strategies tested and ranked
+- [ ] Azure AI Search index configured (vector + hybrid)
+
+### Orchestration
+- [ ] Workflow built with `AgentWorkflowBuilder`
+- [ ] Error handling via middleware
+- [ ] OpenTelemetry monitoring enabled
+
+### Security & Cost
+- [ ] Guardrails implemented (PII, injection, malicious content)
+- [ ] Resource-Aware Optimization (model selection by complexity)
+- [ ] Token usage monitored and costs documented
+
+---
+
+## References
+
+- [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/)
+- [Azure AI Search](https://learn.microsoft.com/azure/search/)
+- [GitHub: microsoft/agent-framework](https://github.com/microsoft/agent-framework)
+- `.wiki/ai/20-agentic-design-patterns.md` — Full 20 patterns reference
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*