@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

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

@@ -0,0 +1,160 @@
+# Agent Archetypes — as quatro formas de agente, e como escolher uma
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** agent archetype, arquetipo de agente, qual forma de agente, conversational agent, one-shot agent, batch agent, vision agent, chat with history
+> **Read by Claude in:** plan (escolher a forma do agente antes de quebrar a feature em tasks)
+
+**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentFactory.cs` e `.../Conversation/ConversationStore.cs` (arquétipos **one-shot em batch** e **chat com histórico** — o conversacional com fases NÃO tem lastro no kit, e `ai-agents-conversational-agent-with-phases` declara isso no próprio cabeçalho). O arquétipo visão + structured output é **verificação documental** — o ai-kit não exercita multimodalidade. Last-verified: 2026-09-08.
+
+---
+
+## Como escolher
+
+`ai-agents-sweet-spot` decide **se** o caso pede um agente ou um workflow. Este standard entra
+depois, e decide **qual forma** o agente tem. A escolha é de **fase de plano**: ela muda o desenho
+das tasks, não uma linha de implementação.
+
+Três perguntas, nesta ordem — a primeira que responder "sim" fecha a escolha:
+
+| # | Pergunta | Se sim |
+|---|---|---|
+| 1 | O agente atende **um interlocutor ao longo do tempo**, e o que ele pode fazer muda conforme o ponto da conversa? | **Conversacional com fases** — e leia `ai-agents-conversational-agent-with-phases` |
+| 2 | O agente é chamado por um **job**, produz um artefato e morre? | **One-shot em batch** |
+| 3 | A entrada é **imagem ou PDF** e a saída precisa ser um objeto tipado? | **Visão com structured output** |
+
+Se a resposta a (1) for sim, a **propriedade do histórico** ainda é uma decisão separada — é o
+quarto arquétipo, e ele não é alternativo ao primeiro (ver `## Lastro de campo por arquétipo`).
+
+**Regra que atravessa os quatro:** o agente referencia **alias**, nunca id de modelo
+(`ai-agents-providers-model-registry`), e a forma escolhida não muda isso.
+
+---
+
+## Conversacional com fases
+
+Agente **único** que atende uma conversa inteira. As quatro propriedades que definem a forma:
+
+- **Fase derivada por turno**, de estado observável, nunca de memória do modelo.
+- **Allow-list de tools por fase** — o agente na fase de triagem não enxerga a tool de fechamento.
+- **Teto de tool calls por turno**, com uma tool isenta quando existe uma ação que sempre pode
+  acontecer.
+- **Dono do próprio histórico** — o agente decide o que entra no contexto do turno.
+
+Multiplicar agentes por fase é o erro clássico aqui: cada fase vira um agente, e a transição entre
+fases vira orquestração que ninguém pediu. A fase é **dado do turno**, não identidade de agente.
+
+O aprofundamento — compositor de turno determinístico, os dois estágios da allow-list, `RequireAny`
+e o teto — está em `ai-agents-conversational-agent-with-phases`, que declara fonte única.
+
+---
+
+## One-shot em batch
+
+Agente **recriado por invocação**. Prompt e alias entram como **parâmetro de método**, nunca como
+estado do objeto; o agente não sobrevive à chamada.
+
+- Sempre dentro de um **job assíncrono**, nunca no caminho de uma requisição HTTP síncrona.
+- Saída tipada com `RunAsync<T>` — quem chama um agente de batch quer um objeto, não um parágrafo.
+- Construir agente é barato: recrie por invocação em vez de guardar um vivo e mutá-lo.
+
+O ai-kit compila exatamente essa forma: `AgentFactory.Create(AgentSpec)` recebe **a spec inteira
+como argumento** e devolve um `AIAgent` novo, sem estado compartilhado entre chamadas.
+
+---
+
+## Visão com structured output
+
+Entrada multimodal (`DataContent`/`UriContent`) + saída tipada na **mesma** chamada. PDF é
+rasterizado e vai **uma chamada por página** — não existe "mandar o PDF inteiro" que não seja isso
+por baixo.
+
+> **Este arquétipo tem ZERO exemplares no acervo.** Ele é forma **projetada**, não destilada. Os
+> dois standards que o sustentam existem separadamente (`ai-agents-modalities-vision` e
+> `ai-agents-structured-output`); o que não existe é um caso de campo que combine os dois numa
+> chamada só. Quem for o primeiro a implementá-lo deve tratar as afirmações desta seção como
+> hipótese a verificar, e voltar aqui com a medição.
+
+Os anti-padrões que o acervo **já cometeu** — duas meias-formas e uma implementação quebrada:
+
+| Meia-forma medida | O que faltou |
+|---|---|
+| Visão **sem** structured — a resposta volta em prosa e alguém a interpreta depois | O parser vira dívida invisível: o formato da prosa é contrato não declarado |
+| Structured **sem** visão — o objeto é tipado, mas a imagem foi descrita antes por outra chamada | Duas chamadas pagas onde uma bastava, e o erro de descrição não é mais rastreável até a origem |
+| Foto entregue como **URL dentro do texto** do prompt, JSON pedido em prosa, e a resposta limpa com strip de code fence | Isto não é o arquétipo: é o que se faz quando ele não é conhecido. `DataContent`/`UriContent` existem para isso, e `ChatResponseFormatJson` para o outro lado |
+
+---
+
+## Chat com histórico
+
+A **conversa** é a fonte de verdade, e a projeção papel → `ChatMessage` acontece **num lugar só**.
+
+- Carregar e anexar histórico é responsabilidade de um tipo dedicado, não do handler.
+- A projeção (quem é `user`, quem é `assistant`, o que vira `system`) é uma função pura, testável
+  sem banco.
+- Duas projeções em dois arquivos é como um histórico começa a divergir de si mesmo.
+
+O ai-kit compila esta forma em `ConversationStore` (um `ChatHistoryProvider` sobre a interface
+mínima `IConversationStore` — `LoadAsync`/`AppendAsync`, sem tipo de banco na assinatura).
+
+---
+
+## Lastro de campo por arquétipo
+
+Esta seção existe porque um catálogo que finge quatro instâncias iguais envelhece mal. O lastro é
+desigual, e saber **onde** ele é fino é parte da informação:
+
+| Arquétipo | Exemplares no acervo | Observação |
+|---|---|---|
+| Conversacional com fases | **1**, em produção | Fonte única; o standard dedicado declara isso no próprio corpo |
+| One-shot em batch | **3** | O mais lastreado dos quatro, e por isso o de menor risco |
+| Visão com structured output | **0** | Forma projetada. Existem duas meias-formas, e uma implementação quebrada |
+| Chat com histórico | **1** | E é **o mesmo agente** do primeiro arquétipo |
+
+**Consequência de forma, e é a razão desta tabela:** o primeiro e o quarto arquétipos **não são
+independentes**. São dois eixos do mesmo agente — *fases* (o que ele pode fazer agora) × *propriedade
+do histórico* (quem decide o que ele lembra). Um agente conversacional que delega o histórico a um
+framework externo continua sendo o primeiro arquétipo, e perdeu o quarto. Escolher "conversacional"
+não escolhe o histórico; escolher "chat com histórico" não escolhe as fases.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é problema | Solução |
+|---|---|---|
+| Um agente por fase da conversa | A transição entre fases vira orquestração que ninguém pediu, e o histórico se fragmenta | Um agente, fase como dado do turno |
+| Agente one-shot guardado como singleton e mutado entre chamadas | Estado vaza entre invocações independentes; um prompt de uma execução aparece na seguinte | Recrie por invocação — a construção é barata |
+| Agente de batch no caminho síncrono de uma requisição | Latência de LLM no p99 do endpoint, sem retry e sem visibilidade | Job assíncrono |
+| Imagem descrita numa chamada e tipada noutra | Duas chamadas pagas, e o erro de descrição deixa de ser rastreável | Uma chamada multimodal com `RunAsync<T>` |
+| Projeção papel → `ChatMessage` em dois arquivos | Os dois divergem, e o bug aparece como "o agente esqueceu" | Uma projeção, pura e testável |
+| Escolher o arquétipo na implementação | A forma muda o desenho das tasks; escolhida depois, ela vira refactor | Escolha na fase de plano, e registre em `decisions.md` |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] O arquétipo escolhido está **nomeado** no `decisions.md` da feature, com a pergunta de
+      `## Como escolher` que o decidiu
+- [ ] Nenhum agente novo por fase de conversa — a fase é dado do turno
+- [ ] Agente one-shot recebe prompt e alias como parâmetro, e não guarda estado entre invocações
+- [ ] Agente de batch roda em job assíncrono
+- [ ] Se há multimodalidade com saída tipada: uma única chamada, com `DataContent`/`UriContent`
+- [ ] A projeção papel → `ChatMessage` existe em exatamente um lugar
+- [ ] O agente referencia alias do registry, nunca id de modelo
+
+---
+
+## References
+
+- `ai-agents-sweet-spot` — decide **se** é agente ou workflow; este standard só entra depois
+- `ai-agents-conversational-agent-with-phases` — o aprofundamento do primeiro arquétipo
+- `ai-agents-agent-spec` — a forma do agente **como dado**, comum aos quatro
+- `ai-agents-providers-model-registry` — alias, e por que o modelo não aparece na spec
+- `ai-agents-structured-output` — `RunAsync<T>` e o schema da saída
+- `ai-agents-modalities-vision` — a metade multimodal do terceiro arquétipo
+- `ai-agents-agent-session` — histórico e reducers, quando o quarto arquétipo cresce
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/agent-archetypes.md v1.0 (2026-09-08)*

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

@@ -1,160 +1,256 @@
-# 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)*
+# Agent Session — de onde vem o histórico de conversa
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** agent session, chat history, conversation state, chat reducer, history truncation, ChatHistoryProvider, conversa própria, multi-tenant
+> **Read by Claude in:** implement
+
+**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Conversation/ConversationStore.cs` (a subclasse de `ChatHistoryProvider`, a invariante de instância única e o teste de duas sessões concorrentes). Nomes de tipo e membros medidos por reflexão sobre `Microsoft.Agents.AI.Abstractions` 1.20.0 em 2026-09-08. Last-verified: 2026-09-08.
+
+---
+
+## O critério — de onde o histórico deve vir
+
+**Primeiro o critério, depois o veredito.** Existem três fontes possíveis de histórico e elas não são intercambiáveis:
+
+| Situação | Fonte de histórico |
+|---|---|
+| A conversa carrega **campos de negócio** além das mensagens (usage por turno, título, dossiê, takeover humano, estado de funil) | **Conversa própria** — tabela/`jsonb` do projeto, exposta por um `ChatHistoryProvider` seu |
+| O histórico precisa ser **visível e manipulável pela aplicação** (retry, remontagem, auditoria, edição, exclusão a pedido do titular) | **Conversa própria** |
+| Multi-tenant com isolamento por chave composta e retenção sob controle do projeto | **Conversa própria** |
+| O histórico é **só** a lista de mensagens, sem campo próprio, e o projeto não precisa lê-lo fora do agente | `AgentSession` + um `ChatHistoryProvider` embutido |
+| Protótipo, CLI, demo, teste | `InMemoryChatHistoryProvider` |
+
+**O veredito da casa: conversa própria como default.** Isso não é preferência — é a aplicação do critério acima aos projetos que existem. GHLBrain, MORPH_OS e ProspectPRO caem todos nas três primeiras linhas.
+
+### Os três fundamentos, cada um citável
+
+1. **ADR D3 do GHLBrain.** O estado da conversa vive em `conv_checkpoints`; `ToolAgentRunner.cs:126-130` roda *"sem AgentThread/sessão"* — porque o **retry depende de o histórico ser visível e manipulável**: para repetir uma volta que falhou é preciso remontar as mensagens, e não dá para remontar o que está dentro de um objeto opaco. Registrado em `docs/specs/elevacao-9/brutos/scan-ghlbrain.md:58` e `:599`.
+2. **Doc oficial de self-hosting** (learn.microsoft.com/en-us/agent-framework/hosting/self-hosting/, `ms.date` 2026-08-17), verbatim: *"MAF doesn't include a general-purpose durable session store"*. Produção exige implementação própria. A mesma página recomenda, em conversa longa, um `ChatHistoryProvider` externo **com mensagens por linha** em vez de reescrever a sessão inteira a cada turno.
+3. **Padrão do canal** (Rasmus, parte 06 — "Conversations"): objeto de conversa próprio do domínio, com **um** mapper para `ChatMessage`. A conversa é entidade de negócio; o formato do provedor é detalhe de transporte.
+
+### Ligação com a Responses API
+
+Com `store: true` (o default da Responses API) **o histórico foge para o provedor** e passa a existir em dois lugares. Quem usa conversa própria mantém **`store: false`** — ver `ai-agents-setup` §*`store: false` é a regra da casa*, incluindo o atalho `AsIChatClientWithStoredOutputDisabled`.
+
+### Quando NÃO há histórico nenhum
+
+- 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.
+
+> *"Add Memory/Session because agents need state"* é um anti-pattern de `sweet-spot.md`.
+> Só adicione histórico quando o critério acima aponta para ele.
+
+---
+
+## A API
+
+**Pacote:** `Microsoft.Agents.AI` 1.20.0 (base; já requerido por `ai-agents-setup`).
+
+**Tipos e membros — medidos por reflexão sobre as assemblies do pin em 2026-09-08:**
+
+| Tipo | Onde | O que é |
+|---|---|---|
+| `AgentSession` | `Microsoft.Agents.AI.Abstractions` | Container de estado da conversa. Abstrato; tem `StateBag`. Criado por `agent.CreateSessionAsync()` |
+| `ChatClientAgentSession` | `Microsoft.Agents.AI` | A `AgentSession` do `ChatClientAgent`; acrescenta `ConversationId` (o id gerenciado pelo serviço, quando há) |
+| `ChatHistoryProvider` | `Microsoft.Agents.AI.Abstractions` | Classe **abstrata** a estender. Pontos de override: `ProvideChatHistoryAsync(InvokingContext, ct)` e `StoreChatHistoryAsync(InvokedContext, ct)` (ambos `protected`). Declare também `StateKeys` |
+| `ProviderSessionState<TState>` | `Microsoft.Agents.AI.Abstractions` | Estado **por sessão**, com `GetOrInitializeState(session)` / `SaveState(session, state)` e um `StateKey` |
+| `InMemoryChatHistoryProvider` | `Microsoft.Agents.AI.Abstractions` | Implementação embutida. `sealed`. Aceita `ChatReducer` e `ReducerTriggerEvent` |
+| `IChatReducer`, `MessageCountingChatReducer`, `SummarizingChatReducer` | `Microsoft.Extensions.AI` | Redutores de histórico |
+| `ChatClientAgentOptions` | `Microsoft.Agents.AI` | Aceita `ChatHistoryProvider`, `AIContextProviders`, e as três flags de conflito (`Throw/Warn/ClearOnChatHistoryProviderConflict`) |
+| `agent.SerializeSessionAsync(session, …)` / `agent.DeserializeSessionAsync(JsonElement, …)` | `AIAgent` | Serialização da sessão. **São `…Async` e devolvem `ValueTask`** — não existe forma síncrona |
+
+> **Correções contra a versão anterior deste standard, todas medidas:** `AgentThread` e `GetNewThread()` **não existem** em `Microsoft.Agents.AI` 1.20.0 (renomeados para `AgentSession` / `CreateSessionAsync` ainda no ciclo pré-GA, `preview.260128.1` e `preview.260205.1`); `CosmosChatHistoryProvider` **não está** em `Microsoft.Agents.AI` nem em `Microsoft.Agents.AI.Abstractions` 1.20.0 — se existir, é de outro pacote, e este standard não afirma qual.
+
+### A forma de um provider de conversa própria
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+public sealed class ConversationStore : ChatHistoryProvider
+{
+    public const string ConversationIdStateKey = "app.conversation.id";
+
+    private readonly IConversationStore _store;                      // o acervo do PROJETO
+    private readonly ProviderSessionState<string> _conversationId;   // estado POR SESSÃO
+
+    public ConversationStore(IConversationStore store)
+    {
+        ArgumentNullException.ThrowIfNull(store);
+        _store = store;
+        _conversationId = new ProviderSessionState<string>(NewConversationId, ConversationIdStateKey);
+    }
+
+    // Declara a chave que este provider ocupa no estado da sessão — é o que permite
+    // ao MAF serializar e retomar uma sessão sem adivinhar o que é de quem.
+    public override IReadOnlyList<string> StateKeys => [ConversationIdStateKey];
+
+    protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(
+        InvokingContext context, CancellationToken cancellationToken = default)
+        => await _store.LoadAsync(GetConversationId(context.Session!), cancellationToken);
+
+    protected override async ValueTask StoreChatHistoryAsync(
+        InvokedContext context, CancellationToken cancellationToken = default)
+    {
+        // Volta que falhou não é gravada: persistir o pedido sozinho deixaria a conversa
+        // terminando numa pergunta que o modelo nunca respondeu.
+        if (context.InvokeException is not null) return;
+
+        List<ChatMessage> round = [.. context.RequestMessages ?? [], .. context.ResponseMessages ?? []];
+        if (round.Count == 0) return;
+
+        // Grava SÓ esta volta. Regravar o histórico inteiro a cada turno faz a conversa
+        // crescer em progressão geométrica.
+        await _store.AppendAsync(GetConversationId(context.Session!), round, cancellationToken);
+    }
+
+    public string GetConversationId(AgentSession session)
+        => _conversationId.GetOrInitializeState(session);
+
+    private static string NewConversationId(AgentSession? session)
+        => session is ChatClientAgentSession { ConversationId.Length: > 0 } managed
+            ? managed
+            : Guid.CreateVersion7().ToString("n");   // ordenável no tempo; NewGuid fragmenta índice
+}
+```
+
+### A invariante de instância — o erro que só aparece em produção
+
+**O provider é UMA instância compartilhada por todas as sessões.** Ele não pode ter campo de estado por conversa. O único estado por sessão vive em `ProviderSessionState<TState>`, **dentro da `AgentSession`**.
+
+Um campo de instância guardando "a conversa atual" é como o histórico de um usuário aparece na tela de outro — e a falha **não** aparece em teste de uma sessão só: aparece sob concorrência, em produção, como vazamento de dado alheio. O canário é um teste com **duas sessões concorrentes** sobre o **mesmo** provider.
+
+### Histórico embutido, quando o critério aponta para ele
+
+```csharp
+AIAgent agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new() { Instructions = "You are a helpful assistant." },
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
+        {
+            ChatReducer = new MessageCountingChatReducer(20),
+            ReducerTriggerEvent = ChatReducerTriggerEvent.AfterMessageAdded,
+        }),
+    });
+```
+
+---
+
+## 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<IConversationStore, PostgresConversationStore>();
+builder.Services.AddSingleton<ChatHistoryProvider>(sp =>
+    new ConversationStore(sp.GetRequiredService<IConversationStore>()));   // UMA instância
+
+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." },
+            ChatHistoryProvider = sp.GetRequiredService<ChatHistoryProvider>(),
+        });
+});
+
+// ── 2. Uma session por conversa (por conexão SignalR, por "start chat") ──
+public class ChatService(AIAgent _agent, ConversationStore _history)
+{
+    public async Task<AgentSession> StartConversationAsync(string conversationId)
+    {
+        var session = await _agent.CreateSessionAsync();
+        _history.BindConversation(session, conversationId);   // a conversa JÁ EXISTE como registro
+        return session;
+    }
+
+    public async Task<string> SendMessageAsync(AgentSession session, string userMessage)
+    {
+        AgentResponse response = await _agent.RunAsync(userMessage, session);
+        return response.Text;
+    }
+
+    // Retomar depois de um restart: a sessão é dado, não objeto vivo.
+    public async Task<AgentSession> ResumeAsync(JsonElement serialized)
+        => await _agent.DeserializeSessionAsync(serialized);
+}
+
+// ── 3. Uso ──
+AgentSession session = await chatService.StartConversationAsync(conversation.Id);
+string reply1 = await chatService.SendMessageAsync(session, "Meu pedido #1234 está atrasado.");
+string reply2 = await chatService.SendMessageAsync(session, "E quando foi despachado?");
+// O contexto do segundo turno veio do ACERVO DO PROJETO — legível por relatório, por auditoria,
+// e apagável a pedido do titular.
+```
+
+---
+
+## History management
+
+O histórico cresce a cada turno. Quando estoura o context window do modelo, as chamadas falham ou truncam silenciosamente.
+
+| Estratégia | Quando usar | Como implementar |
+|------------|-------------|------------------|
+| **Sliding window** | Conversas longas com contexto recente suficiente | `MessageCountingChatReducer(n)` no `InMemoryChatHistoryProvider`, ou um `LIMIT` na query do provider próprio |
+| **Token budget** | Modelos com context window pequeno | Contar tokens acumulados no provider próprio e truncar |
+| **Summarization** | Histórico precisa de contexto antigo comprimido | `SummarizingChatReducer`, ou compaction (`ai-agents-context-providers` §Compaction) |
+
+**Com conversa própria, a truncation é query, não middleware.** `ProvideChatHistoryAsync` devolve o que a query devolveu — `ORDER BY created_at DESC LIMIT n` já é o sliding window, e é auditável no banco. `IChatReducer` existe para o caminho embutido.
+
+**Grave só a volta corrente.** `StoreChatHistoryAsync` recebe `RequestMessages` + `ResponseMessages` **daquela** volta; regravar o histórico completo a cada turno é crescimento geométrico do acervo.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema |
+|-------------|----------|
+| **Estado por sessão em campo do provider** | O provider é **uma** instância para todas as sessões. Um campo `_currentConversation` faz o histórico de um usuário aparecer para outro. Estado por sessão vive em `ProviderSessionState<TState>`, com `StateKey` declarado em `StateKeys`. A falha não aparece em teste de uma sessão só |
+| **`ConversationId` / `previous_response_id` como fronteira de autorização** | Esses ids são escopados à **chave da API**, não ao usuário: quem tem o id e a chave lê a conversa. Mapeie o id do cliente para o id do serviço e **verifique o dono** antes de retomar |
+| Adicionar histórico 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 | A isolation depende de `AgentSession` — sempre uma session por conversa, via `agent.CreateSessionAsync()` |
+| Gravar a volta que falhou | Sem resposta, a conversa termina numa pergunta não respondida; a volta seguinte a repete e o usuário se vê duplicado |
+| Deixar `store` ligado tendo histórico próprio | Duas cópias da conversa, uma delas fora do seu controle de retenção |
+
+> **Nota de migração (histórico, não API viva):** `AgentThread` → `AgentSession` e `GetNewThread()` → `CreateSessionAsync()` aconteceram **antes** do GA de 2026-04-02. Código escrito contra os nomes antigos não compila com o pin. Não são alternativas: são nomes mortos.
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] A escolha da fonte de histórico foi feita pela tabela de critério — e está escrita em `decisions.md` quando não foi a conversa própria
+- [ ] O provider de histórico é registrado como **uma** instância compartilhada
+- [ ] Nenhum campo de instância do provider guarda estado de conversa; o que é por sessão está em `ProviderSessionState<TState>` e declarado em `StateKeys`
+- [ ] Existe teste com **duas sessões concorrentes** sobre o mesmo provider
+- [ ] Uma `AgentSession` por conversa/usuário — nunca compartilhada
+- [ ] `ConversationId` nunca é usado como prova de autorização; o dono é verificado antes de retomar
+- [ ] `store: false` quando o histórico é próprio
+- [ ] Estratégia de truncation definida (query com `LIMIT`, reducer ou summarization)
+- [ ] Agentes one-shot (gerador, executor, classificador) **não** recebem histórico
+- [ ] Nenhuma ocorrência de `AgentThread` / `GetNewThread()` no código
+
+---
+
+## References
+
+- `ai-agents-setup` — packages, DI base, `store: false`
+- `ai-agents-sweet-spot` — decisão de quando adicionar estado ao agente
+- `ai-agents-context-providers` — a mesma invariante de instância, e compaction
+- `ai-agents-middleware-patterns` — pipeline e middleware
+- Reference implementation (compila contra o pin): `templates/dotnet/ai-kit/src/Morph.AiKit/Conversation/ConversationStore.cs`
+- MAF Conversations / storage: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/storage (`ms.date` 2026-07-01)
+- MAF self-hosting: https://learn.microsoft.com/en-us/agent-framework/hosting/self-hosting/ (`ms.date` 2026-08-17)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/agent-session.md v2.0 (2026-09-08)*