@polymorphism-tech/morph-spec 8.28.0 → 8.31.0

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

@@ -1,188 +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)*
+# 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)*