# 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*
