@polymorphism-tech/morph-spec 6.0.0 → 7.1.0

package/framework/standards/ai-agents/modalities-vision.md

@@ -0,0 +1,201 @@
+# Modalities — Vision (Image to Text)
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** vision, image to text, OCR, image analysis, multimodal input, image agent, PDF analysis
+> **Read by Claude in:** implement (quando o agente recebe imagem ou PDF)
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar vision
+
+Use vision quando o input real é uma imagem ou documento visual e o modelo precisa interpretar o conteúdo visual:
+
+- **OCR não-estruturado:** formulários digitalizados, notas escritas à mão, recibos
+- **Análise de imagem:** descrever screenshots, detectar objetos, moderar conteúdo visual
+- **Extração de dados de documentos:** invoices, laudos, contratos em PDF/imagem — combine com `RunAsync<T>` para saída tipada (ver §Exemplo)
+- **Multimodal Q&A:** usuário envia foto + pergunta
+
+**Não se aplica** quando o input já é texto extraído. Se você já tem o texto do documento (via OCR determinístico, parser de PDF, etc.), envie o texto diretamente para um agente de chat — vision é desnecessário e mais caro.
+
+**Escolha do modelo:** nem todo provider suporta visão. Use o alias `"vision"` no Model Registry — o projeto configura ali o modelo capaz (ex: `gpt-4o`, `gemini-2.5-flash`). Veja `ai-agents-providers-model-registry`.
+
+---
+
+## A API
+
+Vision em MAF usa `ChatMessage` multimodal — a mesma abstração `IChatClient`/`AIAgent`, mas com conteúdo misto no payload da mensagem.
+
+```csharp
+using Microsoft.Extensions.AI;
+
+// Constrói um ChatMessage com texto + imagem
+ChatMessage message = new(ChatRole.User, [
+    new TextContent("O que aparece nesta imagem?"),
+    new UriContent(new Uri("https://example.com/foto.jpg"), "image/jpeg")
+]);
+
+AgentResponse response = await agent.RunAsync(message);
+```
+
+O `IChatClient` (e portanto `AIAgent`) aceita `IEnumerable<ChatMessage>` — você passa a lista diretamente para `RunAsync`.
+
+**Referência de tipos (namespace `Microsoft.Extensions.AI`):**
+
+| Tipo | Uso |
+|------|-----|
+| `TextContent` | Parte textual da mensagem |
+| `UriContent(uri, mediaType)` | Imagem referenciada por URL pública |
+| `DataContent.LoadFromAsync(path)` | Carrega imagem de arquivo/stream (helper canônico) |
+| `new DataContent(binaryData, mediaType)` | Imagem embutida a partir de bytes já em memória |
+
+---
+
+## Exemplo C# completo
+
+Agente de visão que recebe URL de imagem e retorna descrição. Para extração de dados tipados de um documento, combine com `RunAsync<T>` (ver comentário inline).
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+public sealed class VisionAgent
+{
+    private readonly AIAgent _agent;
+
+    public VisionAgent(ModelRegistry modelRegistry)
+    {
+        _agent = modelRegistry.GetChatClient("vision").AsAIAgent(new ChatClientAgentOptions
+        {
+            Name = "VisionAgent",
+            ChatOptions = new()
+            {
+                Instructions = """
+                    You are an image analysis expert.
+                    Describe the image content clearly and extract any visible text or structured data.
+                    """
+            }
+        });
+    }
+
+    /// <summary>Analisa uma imagem por URL pública e retorna descrição em texto.</summary>
+    public async Task<string> AnalyzeImageUrlAsync(Uri imageUri, string question, CancellationToken ct = default)
+    {
+        ChatMessage message = new(ChatRole.User, [
+            new TextContent(question),
+            new UriContent(imageUri, "image/jpeg")
+        ]);
+
+        AgentResponse response = await _agent.RunAsync(message, cancellationToken: ct);
+        return response.Text;
+    }
+
+    /// <summary>
+    /// Analisa imagem a partir de um arquivo local ou caminho de upload.
+    /// Usa DataContent.LoadFromAsync — padrão canônico MAF para carregar imagem de arquivo.
+    /// Para extrair dados tipados, use RunAsync&lt;T&gt; em vez de RunAsync:
+    ///   AgentResponse&lt;InvoiceData&gt; r = await _agent.RunAsync&lt;InvoiceData&gt;(message);
+    ///   return r.Result;
+    /// Veja ai-agents-structured-output para o padrão completo.
+    /// </summary>
+    public async Task<string> AnalyzeImageFileAsync(string filePath, string question, CancellationToken ct = default)
+    {
+        DataContent imageContent = await DataContent.LoadFromAsync(filePath);
+        ChatMessage message = new(ChatRole.User, [
+            new TextContent(question),
+            imageContent
+        ]);
+
+        AgentResponse response = await _agent.RunAsync(message, cancellationToken: ct);
+        return response.Text;
+    }
+
+    /// <summary>
+    /// Analisa imagem a partir de bytes já em memória (ex: upload de usuário já lido).
+    /// Use AnalyzeImageFileAsync quando tiver o caminho do arquivo — é o padrão preferido.
+    /// </summary>
+    public async Task<string> AnalyzeImageBytesAsync(BinaryData imageData, string mediaType, string question, CancellationToken ct = default)
+    {
+        ChatMessage message = new(ChatRole.User, [
+            new TextContent(question),
+            new DataContent(imageData, mediaType)
+        ]);
+
+        AgentResponse response = await _agent.RunAsync(message, cancellationToken: ct);
+        return response.Text;
+    }
+}
+```
+
+**Consumo:**
+
+```csharp
+var agent = new VisionAgent(modelRegistry);
+
+// Por URL pública
+string desc = await agent.AnalyzeImageUrlAsync(
+    new Uri("https://cdn.example.com/invoice-2024.jpg"),
+    "Extraia os campos: número da nota, valor total e data de emissão.");
+
+// Por arquivo local — padrão canônico com DataContent.LoadFromAsync
+string desc2 = await agent.AnalyzeImageFileAsync(
+    "nota-fiscal.png",
+    "Liste todos os itens e valores desta nota fiscal.");
+
+// Por bytes em memória (ex: upload já lido de IFormFile)
+BinaryData data = await BinaryData.FromStreamAsync(formFile.OpenReadStream());
+string desc3 = await agent.AnalyzeImageBytesAsync(data, "image/png",
+    "Descreva o conteúdo da imagem enviada.");
+```
+
+---
+
+## DataContent vs UriContent
+
+| Critério | `UriContent` | `DataContent` |
+|----------|-------------|---------------|
+| Imagem publicamente acessível | Sim — envie a URL | — |
+| Imagem privada / upload de usuário | — | Sim — bytes inline (base64 internamente) |
+| Payload de rede | Pequeno (só a URI) | Grande (bytes encodados) |
+| Disponibilidade | O modelo faz HTTP GET na URI; precisa estar acessível | Autossuficiente, sem dependência externa |
+| Formatos suportados | `image/jpeg`, `image/png`, `image/webp`, `image/gif` (por provider) | Idem |
+
+**Trade-off prático:** para imagens geradas internamente ou uploads de usuário, prefira `DataContent` — a URL temporária pode expirar antes do modelo fazer o GET. Para imagens em CDN estável, `UriContent` economiza largura de banda.
+
+**PDF:** o MAF Sample confirma que o OpenAI Chat Client suporta PDF via URI/Data content. Verifique se o provider configurado suporta `application/pdf` antes de usar.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é errado | Jeito certo |
+|--------------|-----------------|-------------|
+| Enviar imagem para modelo sem suporte a vision | A call falha em runtime com erro de provider | Use alias `"vision"` no Model Registry — aponte para modelo com suporte confirmado |
+| Enviar imagem em resolução original sem resize | Tokens de imagem são cobrados por resolução; imagens 4K em contextos que não precisam de detalhe desperdiçam custo e context window | Redimensione para resolução adequada à tarefa (ex: 800px para OCR de texto) |
+| Usar vision quando OCR determinístico bastaria | Vision é probabilístico e mais caro; para extração de texto de PDF com layout fixo, um parser PDF é mais confiável e barato | Só use vision quando o layout é variável ou a imagem é não-estruturada |
+| Retornar `response.Text` e parsear regex para dados estruturados | Não-determinístico; quebra com mudança de modelo | Combine com `RunAsync<T>` e um `sealed record` — veja `ai-agents-structured-output` |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Alias `"vision"` existe em `model-registry.json` e aponta para modelo com suporte a visão confirmado
+- [ ] `ChatMessage` usa `UriContent` para imagens por URL ou `DataContent` para bytes — nenhum encoding manual de base64 no código do agente
+- [ ] Para extração de dados tipados, usa `RunAsync<T>` com `sealed record` (não parseia `response.Text`)
+- [ ] Imagens privadas / uploads de usuário usam `DataContent`, não `UriContent` com URL temporária
+- [ ] Validação de regras de negócio existe após `RunAsync<T>` quando aplicável
+
+---
+
+## References
+
+- `ai-agents-setup` — packages, DI, e setup mínimo de agente
+- `ai-agents-providers-model-registry` — como registrar e resolver modelos por alias
+- `ai-agents-structured-output` — `RunAsync<T>` para extração tipada de dados de documentos
+- Microsoft Agent Framework multimodal sample: https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/02-agents/Agents/Agent_Step10_UsingImages/README.md
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/modalities-vision.md v1.0 (2026-05-19)*

package/framework/standards/ai-agents/multi-agent-patterns.md

@@ -0,0 +1,155 @@
+# Multi-Agent Patterns — Composing agents
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** multi-agent, agent as tool, agent composition, sequential agents, handoff, sub-agent, agent orchestration
+> **Read by Claude in:** plan (quando ai-agents-sweet-spot indica multi-agent) + implement
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Quando multi-agent (e quando não)
+
+Leia `ai-agents-sweet-spot` antes de continuar. O default é **single agent**.
+
+Multi-agent só se justifica quando:
+
+1. Existem **tópicos genuinamente distintos** que um único prompt não gerencia bem (ex: classificar *e* redigir com especialização independente).
+2. Há um **handoff claro** entre responsabilidades — não apenas "dividir o código em dois agents".
+3. Um Agent-as-Tool não resolve (o sub-agent precisa ser invocado *várias vezes* ou em paralelo).
+
+> "Em dúvida → single agent. Escalate quando dói, não antes."
+
+---
+
+## Agent-as-Tool (padrão recomendado)
+
+**O padrão mais simples de composição.** O agent pai decide *quando* chamar o agent filho — exatamente como chama qualquer outra tool. Não é um Workflow; sem edges, sem builders.
+
+### Caso canônico: classifier + drafter (suporte)
+
+Um `ClassifierAgent` categoriza o ticket. Um `DrafterAgent` recebe a categoria e escreve a resposta. O Drafter não precisa saber de classificação — só recebe a categoria como contexto.
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// --- 1. Agents via Model Registry alias (nunca hardcode modelo ou provider) ---
+IChatClient chatClient = _modelRegistry.GetChatClient("text-default");
+
+AIAgent classifierAgent = chatClient.AsAIAgent(
+    instructions: "Classify the support ticket into one of: billing, technical, general. Reply with only the category.",
+    name: "ClassifierAgent");
+
+// --- 2. Expõe o classifier como tool usando .AsAIFunction() ---
+AIFunction classifierTool = classifierAgent.AsAIFunction();
+
+// --- 3. Drafter recebe o classifier como tool ---
+AIAgent drafterAgent = chatClient.AsAIAgent(
+    instructions: """
+        You are a support reply writer. When you receive a ticket:
+        1. Call ClassifierAgent to get the category.
+        2. Write a concise, professional reply appropriate for that category.
+        """,
+    name: "DrafterAgent",
+    tools: [classifierTool]);
+
+// --- 4. Executa --- o Drafter chama o Classifier automaticamente quando necessário ---
+AgentResponse response = await drafterAgent.RunAsync(ticketText);
+string reply = response.Text;
+```
+
+**Key points:**
+- `agent.AsAIFunction()` — método direto para expor um `AIAgent` local como tool.
+- Use `AIFunctionFactory.Create(...)` quando precisar sobrescrever o nome/descrição da tool ou encapsular lógica adicional ao chamar o agent.
+- O agent pai decide *se* e *quando* invocar o filho — o LLM controla o fluxo.
+- Ambos os agents usam o mesmo alias do Model Registry; podem usar aliases distintos se o caso de uso justificar.
+
+---
+
+## Sequential (cadeia fixa)
+
+Quando a ordem é fixa A→B→C e cada etapa depende da anterior.
+
+**Na maioria dos casos, C# imperativo é mais simples que um Workflow:**
+
+```csharp
+// classifierAgent, drafterAgent, reviewerAgent — each built from _modelRegistry.GetChatClient(...) as shown above
+// Sem Workflow, sem builders — só chamadas encadeadas
+AgentResponse classified = await classifierAgent.RunAsync(ticketText);
+AgentResponse drafted    = await drafterAgent.RunAsync(classified.Text);
+AgentResponse reviewed   = await reviewerAgent.RunAsync(drafted.Text);
+string finalReply = reviewed.Text;
+```
+
+Use `AgentWorkflowBuilder.BuildSequential(agent1, agent2, ...)` quando precisar de **streaming de eventos** entre as etapas da cadeia (ex: exibir progresso passo a passo no front-end). Ver `ai-agents-workflows`.
+
+---
+
+## Handoff (roteamento dinâmico)
+
+Um agent de triagem decide qual especialista assume o controle com base no contexto. Útil quando há N especialistas e a decisão de roteamento é complexa demais para uma tool simples.
+
+Para handoff baseado em Workflow: `AgentWorkflowBuilder.CreateHandoffBuilderWith(triageAgent).WithHandoffs(...)`. Ver `ai-agents-workflows` para o padrão completo.
+
+> Para roteamento simples (2-3 caminhos), considere Agent-as-Tool com um agent por caminho antes de ir para Handoff Workflow.
+
+---
+
+## Decision tree
+
+```
+Tenho múltiplos agents — qual padrão usar?
+
+├─ Fan-in/out genuíno sobre N inputs (paralelo)?
+│   └─ Workflow (ai-agents-workflows)
+│
+├─ Ordem fixa A→B→C, cada etapa depende da anterior?
+│   ├─ Preciso de streaming de eventos entre etapas?
+│   │   └─ SIM → AgentWorkflowBuilder.BuildSequential (ai-agents-workflows)
+│   └─ NÃO → chamadas encadeadas imperativas em C#
+│
+├─ Sub-task consultada sob demanda pelo agent pai?
+│   └─ Agent-as-Tool (agent.AsAIFunction())  ← padrão mais comum
+│
+└─ Roteamento por intenção, especialistas distintos?
+    └─ Handoff (AgentWorkflowBuilder.CreateHandoffBuilderWith)
+```
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por que é errado | O que fazer |
+|---|---|---|
+| Usar multi-agent quando um único agent resolve | Adiciona latência, custo e superfície de erro sem ganho | Single agent com tools. Ver `ai-agents-sweet-spot`. |
+| Usar Workflow quando Agent-as-Tool basta | Workflow traz edges, builders, streaming — complexidade desnecessária | `agent.AsAIFunction()` primeiro |
+| Passar histórico de conversa bruto entre agents | Output do LLM é não-determinístico; o outro agent não sabe o que fazer com histórico livre | Structured Output entre agents. Ver `ai-agents-structured-output`. |
+| Nesting profundo (agent A chama B chama C chama D) | Dificulta debug, amplifica latência, falhas em cascata | Achate a composição: Agent-as-Tool com o agent folha direto no pai. |
+| Agents com responsabilidades sobrepostas | Nenhum dos dois sabe quando agir; o LLM fica confuso | Fronteiras claras de responsabilidade; documente em `decisions.md`. |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Foi verificado em `decisions.md` que single agent não resolve?
+- [ ] O padrão escolhido é o mais simples que atende ao requisito? (Tool < Sequential imperativo < Workflow)
+- [ ] `agent.AsAIFunction()` usado para composição local (não `AIFunctionFactory.Create` desnecessariamente)?
+- [ ] Agents usando alias do Model Registry — nenhum model string hardcoded?
+- [ ] Structured Output entre agents onde o output de um é input do outro?
+- [ ] Nesting máximo de 2 níveis (pai → filho) sem cascata profunda?
+
+---
+
+## References
+
+- `ai-agents-sweet-spot` — single agent é o default; leia antes deste documento
+- `ai-agents-workflows` — Workflow (fan-in/out, Sequential com streaming, Handoff completo)
+- `ai-agents-setup` — pacotes, DI, `AsAIAgent`
+- `ai-agents-structured-output` — output tipado entre agents
+- `ai-agents-providers-model-registry` — Model Registry alias pattern
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/multi-agent-patterns.md v1.0 (2026-05-19)*