@polymorphism-tech/morph-spec 7.0.0 → 7.1.1

package/framework/standards/ai-agents/agent-session.md

@@ -0,0 +1,160 @@
+# Agent Session — Conversation state and chat reducers
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** agent session, chat history, conversation state, chat reducer, history truncation, AgentThread
+> **Read by Claude in:** implement
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar AgentSession
+
+Use `AgentSession` quando o agente é **conversacional** — há uma UI de chat que mantém histórico entre turnos do usuário.
+
+**Use AgentSession quando:**
+- Existe uma interface de chat (web, mobile, CLI interativo)
+- O agente precisa lembrar o que foi dito nos turnos anteriores da mesma conversa
+- Há perguntas de follow-up ("e agora?", "altere o segundo ponto", "lembra do que disse sobre X?")
+
+**NÃO use AgentSession quando:**
+- O agente é one-shot (gerador, executor, classificador) — recebe uma entrada, devolve uma saída, fim
+- Agentes stateless em pipeline multi-agent — cada chamada é independente
+- Jobs de batch/background — não há conversa; histórico não faz sentido
+
+> "Add Memory/Session because agents need state" é um anti-pattern de `sweet-spot.md`.
+> Só adicione quando uma UI de chat real existe.
+
+---
+
+## A API
+
+**Pacote:** `Microsoft.Agents.AI` (base; já requerido por `ai-agents-setup`).
+
+**Tipos confirmados via context7:**
+- `AgentSession` — container leve de estado de conversa; obtido via `agent.CreateSessionAsync()`
+- `AgentThread` — equivalente para agentes persistentes (PersistentAgentsClient); use `agent.GetNewThread()`
+- `ChatClientAgentOptions` — aceita `ChatHistoryProvider` e `AIContextProviders`
+- `InMemoryChatHistoryProvider` — implementação embutida de histórico em memória
+- `AgentResponse` — tipo retornado por `AIAgent.RunAsync` (non-generic); acesse o texto via `.Text`
+
+```csharp
+// Construção do agente com histórico em memória
+AIAgent agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new() { Instructions = "You are a helpful assistant." },
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(),
+    });
+```
+
+---
+
+## Exemplo C# — agente conversacional com session persistente entre turnos
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// ── 1. Registrar o agente conversacional no DI ──
+// Program.cs
+builder.Services.AddSingleton<AIAgent>(sp =>
+{
+    var registry = sp.GetRequiredService<ModelRegistry>();
+    return registry.GetChatClient("text-default")
+        .AsAIAgent(new ChatClientAgentOptions
+        {
+            ChatOptions = new() { Instructions = "You are a helpful customer support assistant." },
+            // InMemoryChatHistoryProvider: histórico vive em memória, por session.
+            // Seguro registrar como parte do singleton AIAgent: cada AgentSession criada via
+            // agent.CreateSessionAsync() isola o histórico de sua conversa — conversas distintas
+            // não compartilham estado. O provider em si é stateless; o estado fica na session.
+            // Para persistência entre restarts, substitua por um provider customizado (ex: DB).
+            ChatHistoryProvider = new InMemoryChatHistoryProvider(),
+        });
+});
+
+// ── 2. Criar uma session por conversa (ex: por conexão SignalR / por request de "start chat") ──
+// ChatController.cs ou ChatHub.cs
+public class ChatService(AIAgent _agent)
+{
+    // Uma session por conversa ativa — armazene no escopo do usuário (cache, memória da conexão)
+    public async Task<AgentSession> StartConversationAsync()
+        => await _agent.CreateSessionAsync();
+
+    // Cada mensagem do usuário passa a mesma session
+    public async Task<string> SendMessageAsync(AgentSession session, string userMessage)
+    {
+        AgentResponse response = await _agent.RunAsync(userMessage, session);
+        return response.Text;
+    }
+}
+
+// ── 3. Uso no controller/hub ──
+// Primeiro turno
+AgentSession session = await chatService.StartConversationAsync();
+string reply1 = await chatService.SendMessageAsync(session, "Meu pedido #1234 está atrasado.");
+// reply1: "Vou verificar o pedido #1234 para você..."
+
+// Segundo turno — o agente lembra do contexto anterior
+string reply2 = await chatService.SendMessageAsync(session, "E quando foi despachado?");
+// reply2: "O pedido #1234 foi despachado em..."  ← contexto mantido pela session
+```
+
+---
+
+## History management
+
+O histórico cresce a cada turno. Quando estoura o context window do modelo, as chamadas falham ou truncam silenciosamente.
+
+### Estratégias
+
+| Estratégia | Quando usar | Como implementar |
+|------------|-------------|------------------|
+| **Sliding window** | Conversas longas com contexto recente suficiente | Limitar `InMemoryChatHistoryProvider` a N mensagens mais recentes |
+| **Token budget** | Modelos com context window pequeno | Contar tokens acumulados; truncar quando ultrapassa threshold |
+| **Summarization** | Histórico precisa de contexto antigo comprimido | Agente periódico que resume N turnos anteriores em uma mensagem única |
+
+> **Custom history management:** Para o caso comum, `InMemoryChatHistoryProvider` cobre a
+> necessidade de histórico em memória por sessão. Se o projeto exigir truncation customizada
+> (ex: sliding window limitando a N mensagens mais recentes ou por token budget), o mecanismo
+> de extensão correto — seja subclasse de `ChatHistoryProvider`, um `IChatReducer`, ou outro
+> ponto de override — deve ser verificado contra a versão instalada de `Microsoft.Agents.AI`.
+> Consulte a documentação MAF atual antes de implementar um provider customizado, pois a API
+> exata de extensão não foi confirmada na versão GA e pode variar entre releases.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema |
+|-------------|----------|
+| Adicionar session em agente one-shot (gerador, executor) | Complexidade desnecessária; estado nunca é usado |
+| Histórico ilimitado sem truncation | Context window estoura; custo aumenta linearmente com a conversa |
+| Compartilhar uma `AgentSession` entre múltiplos usuários | Histórico de um usuário vaza para outro |
+| Usar `InMemoryChatHistoryProvider` sem criar uma `AgentSession` por conversa | Sem `AgentSession` por conversa, o histórico é compartilhado entre todos os usuários; a isolation depende de `AgentSession` — sempre crie uma session por conversa via `agent.CreateSessionAsync()` |
+| Usar `AgentThread` (PersistentAgentsClient) sem necessidade | `AgentThread` requer hosted agent service; prefira `AgentSession` com direct model |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `AgentSession` usada somente em agentes conversacionais com UI de chat real
+- [ ] `InMemoryChatHistoryProvider` (ou equivalente) registrado em `ChatClientAgentOptions`
+- [ ] Uma `AgentSession` por conversa/usuário — nunca compartilhada
+- [ ] Estratégia de truncation definida (sliding window, token budget ou summarization)
+- [ ] Agentes one-shot (gerador, executor, classificador) **não** recebem session
+
+---
+
+## References
+
+- `ai-agents-setup` — packages e DI base
+- `ai-agents-sweet-spot` — decisão de quando adicionar estado ao agente
+- `ai-agents-middleware-patterns` (Onda 2) — pipeline de contexto e middleware
+- MAF Conversations docs: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/agent-session.md v1.0 (2026-05-19)*

package/framework/standards/ai-agents/batching.md

@@ -0,0 +1,193 @@
+# Batching — Bulk prompt processing
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** batching, batch api, bulk prompts, batch processing, async batch
+> **Read by Claude in:** plan/implement
+
+**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.* (fluxo da Batch API confirmado pela REST API; nomes de tipos/métodos .NET marcados `// VERIFY:` — ver seção A API). Last-verified: 2026-05-19.
+
+---
+
+## Quando usar batch
+
+Use a Batch API quando você tem **N prompts independentes sem necessidade de resposta imediata**:
+
+- Relatório mensal que agrega análise de N documentos/itens
+- Reprocessamento de dados históricos com LLM (re-classificação, re-extração)
+- Geração em massa de sumários, traduções ou avaliações offline
+- Pipeline noturno de enriquecimento de dados
+
+**Vantagens:**
+- **Desconto de custo significativo** — OpenAI Batch API custa 50% menos que completions síncronas
+- **SLA relaxado** — resultados em até 24 h; adequado para trabalho assíncrono
+- **Rate limits separados** — não compete com a cota síncrona da aplicação
+
+> Regra prática: se o usuário não está esperando o resultado na tela, considere batch.
+
+---
+
+## A API
+
+> **AVISO:** Batch API é **OpenAI-specific**. O `IChatClient` do MAF não expõe batch.
+> Obtenha o `OpenAIClient` direto via configuração (mesma chave/modelo que o Model Registry usa)
+> em vez de `_modelRegistry.GetChatClient(alias)`.
+
+O fluxo tem 4 etapas: **upload do arquivo JSONL → submissão do batch → poll de status → download dos resultados**.
+
+> ### ⚠️ Status de verificação da API .NET
+>
+> O fluxo abaixo é o **padrão correto da OpenAI Batch API** (confirmado pela REST API e pelos
+> docs oficiais). O que **não** foi confirmável via context7 são os nomes exatos de tipos/métodos
+> do **OpenAI .NET SDK 2.\*** para batch — o context7 retornou apenas as APIs de Assistants/Files.
+>
+> **Confirmado:** `openAIClient.GetOpenAIFileClient()` → `OpenAIFileClient`; upload de arquivo
+> via `UploadFileAsync(stream, filename, FileUploadPurpose.*)`.
+>
+> **A confirmar contra o pacote `OpenAI` 2.\* instalado** (todos marcados `// VERIFY:` no código):
+> nome do método que retorna o batch client (`GetBatchClient()`), namespace do batch
+> (`OpenAI.Batch`), assinatura de `CreateBatchAsync`, nomes de `GetBatchAsync`/`DownloadFileAsync`,
+> tipo/valores do status, e o valor de `FileUploadPurpose` para batch.
+> **Antes de codar:** abra o pacote no IntelliSense ou no [openai-dotnet](https://github.com/openai/openai-dotnet) e confirme cada `// VERIFY:`.
+
+---
+
+## Exemplo C# completo
+
+```csharp
+using OpenAI;
+using OpenAI.Batch;   // VERIFY namespace — confirme contra o pacote OpenAI 2.* instalado
+using OpenAI.Files;
+using System.ClientModel;
+using System.Text;
+using System.Text.Json;
+
+// ── 1. Construir o cliente OpenAI direto (mesma config que o Model Registry usa) ──
+var apiKey = configuration["OpenAI:ApiKey"]!;
+var openAIClient = new OpenAIClient(new ApiKeyCredential(apiKey));
+var fileClient = openAIClient.GetOpenAIFileClient();   // confirmado
+var batchClient = openAIClient.GetBatchClient();   // VERIFY método — pode ser GetOpenAIBatchClient()
+
+// ── 2. Montar o arquivo JSONL com N requests independentes ──
+var items = new[] { "Item A", "Item B", "Item C" }; // substitua pela sua coleção
+var jsonlBuilder = new StringBuilder();
+foreach (var item in items)
+{
+    var request = new
+    {
+        custom_id = $"req-{Guid.CreateVersion7()}",
+        method = "POST",
+        url = "/v1/chat/completions",
+        body = new
+        {
+            model = configuration["OpenAI:Model"] ?? "gpt-4o-mini",
+            messages = new[]
+            {
+                new { role = "user", content = $"Analyze this item and return a JSON summary: {item}" }
+            },
+            max_tokens = 256
+        }
+    };
+    jsonlBuilder.AppendLine(JsonSerializer.Serialize(request));
+}
+
+// ── 3. Upload do arquivo JSONL ──
+var jsonlBytes = Encoding.UTF8.GetBytes(jsonlBuilder.ToString());
+using var jsonlStream = new MemoryStream(jsonlBytes);
+// VERIFY valor do enum — FileUploadPurpose.Batch (confirme; o SDK 2.* expõe outros purposes)
+OpenAIFile batchFile = await fileClient.UploadFileAsync(
+    jsonlStream, "batch_requests.jsonl", FileUploadPurpose.Batch);
+
+// ── 4. Submeter o batch ──
+// VERIFY assinatura de CreateBatchAsync — provável (fileId, endpoint, completionWindow)
+var batch = await batchClient.CreateBatchAsync(
+    batchFile.Id,
+    endpoint: "/v1/chat/completions",
+    completionWindow: "24h");
+
+// ── 5. Poll de status (em background job / Hangfire / Worker) ──
+OpenAIBatch? completedBatch = null;   // VERIFY nome do tipo de retorno
+do
+{
+    await Task.Delay(TimeSpan.FromSeconds(30)); // poll interval para batch — não interativo
+    completedBatch = await batchClient.GetBatchAsync(batch.Id);   // VERIFY nome do método
+} while (completedBatch?.Status is not ("completed" or "failed" or "cancelled"));   // VERIFY tipo/valores do Status
+
+// ── 6. Recuperar e processar resultados ──
+if (completedBatch?.OutputFileId is { } outputFileId)
+{
+    var resultFile = await fileClient.DownloadFileAsync(outputFileId);   // VERIFY nome do método
+    using var reader = new StreamReader(resultFile.Value.ToStream());
+    string? line;
+    while ((line = await reader.ReadLineAsync()) is not null)
+    {
+        using var doc = JsonDocument.Parse(line);
+        var customId = doc.RootElement.GetProperty("custom_id").GetString();
+        var content = doc.RootElement
+            .GetProperty("response")
+            .GetProperty("body")
+            .GetProperty("choices")[0]
+            .GetProperty("message")
+            .GetProperty("content")
+            .GetString();
+        // processe content...
+    }
+}
+
+// ── 7. Tratar falhas de itens individuais ──
+if (completedBatch?.ErrorFileId is { } errorFileId)
+{
+    var errorFile = await fileClient.DownloadFileAsync(errorFileId);   // VERIFY nome do método
+    // log itens que falharam; retente individualmente se necessário
+}
+```
+
+> O poll de status (`do...while`) deve rodar num **background job** (Hangfire, Worker Service),
+> não em uma requisição HTTP. O usuário não espera; o resultado é entregue via event/webhook/DB.
+
+---
+
+## Quando NÃO usar
+
+| Situação | Por quê não usar batch |
+|----------|------------------------|
+| Resposta interativa — usuário aguarda na tela | Latência de batch (minutos a horas) é inaceitável |
+| Volume baixo (< ~20 requests/dia) | Overhead de JSONL + poll não compensa |
+| Requests com dependência entre si | Batch é para prompts **independentes** |
+| Provider não-OpenAI (Anthropic, Google) | Batch API é OpenAI-specific; use completions síncronas |
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema |
+|-------------|----------|
+| Usar batch para requests síncronos de usuário | Alta latência — batch pode demorar horas |
+| Não tratar `error_file_id` | Itens que falharam são silenciados; reprocessamento nunca acontece |
+| Poll com `Task.Delay(1s)` em loop | Abuso de rate limits; use intervalo ≥ 30 s para batch |
+| Assumir que todos os itens do batch concluem | Batch pode ter falhas parciais; itere o arquivo de erros |
+| Incluir prompt com dados do usuário sem sanitização | Prompt injection em batch; aplique `ai-agents-middleware-patterns` |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Batch é usado somente para prompts independentes, sem usuário aguardando resposta
+- [ ] O poll de status roda em background job (Worker/Hangfire), não em request HTTP
+- [ ] `error_file_id` é verificado e erros de itens individuais são logados/retentados
+- [ ] Nenhum `Guid.NewGuid()` — custom_id usa `Guid.CreateVersion7()`
+- [ ] Provider é OpenAI; cada `// VERIFY:` da API .NET de batch confirmado contra o pacote instalado antes de codar
+
+---
+
+## References
+
+- `ai-agents-setup` — setup do agente MAF e packages
+- `ai-agents-service-tier-flex` — otimização de custo para jobs async
+- `ai-agents-providers-model-registry` — configuração provider-agnostic
+- OpenAI Batch API: https://platform.openai.com/docs/guides/batch
+- OpenAI .NET SDK `OpenAI.Batch`: https://github.com/openai/openai-dotnet
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/batching.md v1.0 (2026-05-19)*

package/framework/standards/ai-agents/context-providers.md

@@ -0,0 +1,188 @@
+# Context Providers — Dynamic context injection
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** context provider, dynamic context, context injection, AIContextProvider, memory provider
+> **Read by Claude in:** implement
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar Context Provider
+
+Use um `AIContextProvider` quando o agente precisa de **contexto dinâmico computado a cada chamada** — informação que varia por request, sessão ou tenant, sem poluir as instructions estáticas do agente.
+
+**Exemplos de uso correto:**
+- Data/hora atual injetada nas instructions ("Today is Monday, 2026-05-19")
+- Perfil do tenant/usuário logado (nome, plano, preferências de idioma)
+- Estado de sistema em tempo real (saldo de conta, status de pedido)
+- Contexto de segurança (permissões do usuário para o turno atual)
+
+**Distinção crítica:**
+
+| Mecanismo | Quando usar |
+|-----------|-------------|
+| **Context Provider** | Contexto **determinístico/computado** — sempre injetado, independe da entrada do usuário |
+| **Tool** | O agente **decide chamar** baseado na entrada; retorno é dinâmico mas acionado pelo LLM |
+| **RAG** | Busca por **similaridade** em base de conhecimento; o contexto varia com o que foi perguntado |
+
+> Regra prática: se você sabe exatamente *o que* injetar antes de chamar o LLM, use Context Provider.
+> Se precisa do LLM para decidir *se* e *como* buscar, use Tool ou RAG.
+
+---
+
+## A API
+
+**Pacote:** `Microsoft.Agents.AI` + `Microsoft.Agents.AI.Hosting` (para o builder).
+
+**Tipos confirmados via context7:**
+
+```
+AIContextProvider     — classe base abstrata (sealed override ProvideAIContextAsync + StoreAIContextAsync)
+AIContext             — objeto retornado; contém Messages, Instructions, etc.
+InvokingContext       — contexto disponível no before-run hook (acesso à session, mensagens atuais)
+InvokedContext        — contexto disponível no after-run hook (request + response messages)
+ProviderSessionState<T> — helper tipado para armazenar estado por provider na AgentSession
+ChatClientAgentOptions.AIContextProviders — lista de providers passados na construção do agente
+.UseAIContextProviders(...) — extension method via builder (Microsoft.Agents.AI.Hosting)
+```
+
+**Método a sobrescrever:**
+
+```csharp
+// ProvideAIContextAsync  → chamado ANTES do LLM (before-run hook) — injeta contexto
+// StoreAIContextAsync    → chamado APÓS o LLM (after-run hook) — persiste estado se necessário
+```
+
+---
+
+## Exemplo C# — context provider que injeta data atual e perfil do tenant
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// ── 1. Definir o provider ──
+public sealed class TenantContextProvider : AIContextProvider
+{
+    private readonly ITenantService _tenantService;
+    private readonly ITenantContext _tenantContext;
+
+    // ITenantContext deve ser implementado via IHttpContextAccessor ou AsyncLocal
+    // para resolver o tenant atual em runtime — não registre como instância estática.
+    // O AIAgent é singleton, então o provider também é singleton; o tenant corrente
+    // é lido de forma ambient (IHttpContextAccessor/AsyncLocal) a cada chamada.
+    public TenantContextProvider(ITenantService tenantService, ITenantContext tenantContext)
+    {
+        _tenantService = tenantService;
+        _tenantContext = tenantContext;
+    }
+
+    // Sobrescreva: injetado ANTES de cada chamada ao LLM
+    protected override async ValueTask<AIContext> ProvideAIContextAsync(
+        InvokingContext context,
+        CancellationToken cancellationToken = default)
+    {
+        // Tenant resolvido via serviço injetado (ambient context, ex: IHttpContextAccessor)
+        var tenantId = _tenantContext.TenantId ?? "unknown";
+        var tenant = await _tenantService.GetTenantAsync(tenantId, cancellationToken);
+
+        var instructions = $"""
+            Today is {DateTimeOffset.UtcNow:yyyy-MM-dd HH:mm} UTC.
+            Tenant: {tenant.Name} (plan: {tenant.Plan}, language: {tenant.Language}).
+            Always respond in {tenant.Language}.
+            """;
+
+        return new AIContext
+        {
+            // Injeta como instrução adicional — não como mensagem do usuário
+            Instructions = instructions,
+        };
+    }
+
+    // Sobrescreva (opcional): chamado APÓS o LLM — use para persistir estado derivado da resposta
+    protected override ValueTask StoreAIContextAsync(
+        InvokedContext context,
+        CancellationToken cancellationToken = default)
+        => ValueTask.CompletedTask; // stateless provider — nada a persistir
+}
+
+// ── 2. Registrar o agente com o provider no DI ──
+// Program.cs
+builder.Services.AddSingleton<AIAgent>(sp =>
+{
+    var registry      = sp.GetRequiredService<ModelRegistry>();
+    var tenantSvc     = sp.GetRequiredService<ITenantService>();
+    var tenantContext = sp.GetRequiredService<ITenantContext>();
+
+    return registry.GetChatClient("text-default")
+        .AsAIAgent(new ChatClientAgentOptions
+        {
+            ChatOptions = new() { Instructions = "You are a helpful assistant." },
+            AIContextProviders = [new TenantContextProvider(tenantSvc, tenantContext)],
+        });
+});
+
+// ── Alternativa: builder/middleware (útil para adicionar providers a agente existente) ──
+// var enrichedAgent = existingAgent
+//     .AsBuilder()
+//     .UseAIContextProviders(new TenantContextProvider(tenantSvc))
+//     .Build();
+
+// ── 3. Uso normal — provider é invocado automaticamente a cada RunAsync ──
+AgentSession session = await agent.CreateSessionAsync();
+AgentResponse response = await agent.RunAsync("Quais são meus benefícios do plano?", session);
+Console.WriteLine(response.Text);
+// O agente já sabe a data, o nome do tenant e o idioma — sem código extra no caller
+```
+
+---
+
+## Context Provider vs Tools vs RAG
+
+| Mecanismo | Quem decide chamar | Quando é acionado | Exemplo |
+|-----------|-------------------|-------------------|---------|
+| **Context Provider** | Framework (sempre) | Antes de cada chamada ao LLM | Data/hora, perfil do tenant |
+| **Tool** | O LLM (quando achar necessário) | Quando o LLM decide invocar | Consultar saldo, buscar pedido |
+| **RAG** | Framework + similaridade semântica | Antes do LLM, busca por embedding | Documentos de ajuda, base de conhecimento |
+
+> Se você está em dúvida entre Context Provider e Tool:
+> - Pergunta: "O agente *sempre* precisa dessa informação nesse contexto?" → Context Provider
+> - Pergunta: "O agente *pode ou não* precisar dependendo do que o usuário pediu?" → Tool
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema |
+|-------------|----------|
+| Context Provider para o que uma tool resolve | Injeta contexto desnecessário a cada chamada; desperdiça tokens |
+| Injetar contexto gigante a cada chamada | Aumenta custo e pode esgotar context window; prefira tools para contexto on-demand |
+| Provider com side-effects de escrita em `ProvideAIContextAsync` | Hook before-run deve ser read-only; use `StoreAIContextAsync` para escrita |
+| Compartilhar estado mutável entre providers sem `ProviderSessionState<T>` | Race condition entre providers; use o helper tipado |
+| Usar Context Provider para lógica de negócio complexa | Providers devem ser leves e rápidos; lógica pesada vai em tools |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] O provider herda da classe base abstrata `AIContextProvider` (não implementa uma interface genérica)
+- [ ] `ProvideAIContextAsync` é read-only — sem writes a banco ou estado global
+- [ ] `StoreAIContextAsync` usado somente quando o provider precisa persistir estado
+- [ ] Provider registrado em `ChatClientAgentOptions.AIContextProviders` ou via `.UseAIContextProviders()`
+- [ ] Contexto injetado é **determinístico** — se depende de busca por similaridade, é RAG, não provider
+
+---
+
+## References
+
+- `ai-agents-setup` — packages e DI base
+- `ai-agents-rag-custom-pgvector` (Onda 2) — busca por similaridade (distinto de context provider)
+- `ai-agents-multi-agent-patterns` (Onda 2) — composição de agentes
+- MAF Context Providers docs: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/context-providers
+- MAF Agent Pipeline docs: https://learn.microsoft.com/en-us/agent-framework/agents/agent-pipeline
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/context-providers.md v1.0 (2026-05-19)*