@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

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

@@ -2,10 +2,10 @@
 
 > **Scope:** stacks=["dotnet"]
 > **Layer:** 0 (always-load via persona maf-expert)
-> **Keywords:** maf setup, microsoft agents ai, chatclient, ai agent, agent framework, agent dotnet, AsAIAgent
+> **Keywords:** maf setup, microsoft agents ai, chatclient, ai agent, agent framework, agent dotnet, AsAIAgent, responses api, chat completions, store false
 > **Read by Claude in:** plan (pra citar pacote em tasks.json) + implement (pra escrever .csproj e Program.cs)
 
-**Verified against:** Microsoft.Agents.AI 1.0 GA (abril/2026). Last-verified: 2026-05-19.
+**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 + OpenAI 2.13.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentFactory.cs` (pipeline e escolha de protocolo). A superfície do SDK `OpenAI` e das pontes `Microsoft.Agents.AI.OpenAI` / `Microsoft.Extensions.AI.OpenAI` foi **medida por reflexão sobre as assemblies do pin** em 2026-09-08 — o ai-kit **não exercita** o cliente concreto da OpenAI — referencia o pacote no `.csproj`, mas não há `using OpenAI` em `src/` (medido 2026-09-08); ver a tabela "Dois níveis de garantia" no README do kit. Last-verified: 2026-09-08.
 
 ---
 
@@ -24,7 +24,7 @@ The concrete model choice lives in the project's Model Registry, not in this sta
 Está adicionando um agente AI a um projeto .NET?
 ├─ Sim → use este standard + ai-agents-sweet-spot + ai-agents-providers-model-registry
 │   ├─ Projeto tem >1 modelo ou >1 provider? → SEMPRE use Model Registry
-│   ├─ Provider OpenAI? → §3.1
+│   ├─ Provider OpenAI? → §3.1 (Responses = default) / §3.1.b (Chat Completions = opt-in)
 │   ├─ Provider Ollama (local)? → §3.2
 │   ├─ Provider Google / Anthropic? → §3.3
 │   └─ Provider Azure OpenAI (data residency)? → §3.4 (nota, não default)
@@ -35,80 +35,162 @@ Está adicionando um agente AI a um projeto .NET?
 
 ## 1. Packages (NuGet)
 
+**Nenhuma faixa flutuante.** Um SDK de cadência semanal com `2.*` é como o ProspectPRO comprou um `MissingMethodException` na Responses API **depois de a chamada ser paga**. Versões abaixo: as do `framework/ai-pin.json` (`pinnedAt` 2026-09-08) ou, quando o pacote **não está no pin**, a versão apurada no nuget.org em **2026-09-08**, dita como tal.
+
 **Required for any MAF project:**
 
 ```xml
-<PackageReference Include="Microsoft.Agents.AI" Version="1.0.*" />
+<!-- no ai-pin.json -->
+<PackageReference Include="Microsoft.Agents.AI" Version="1.20.0" />
 ```
 
 **Provider-specific (escolha conforme o Model Registry do projeto):**
 
 ```xml
-<!-- OpenAI direct -->
-<PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.*" />
-<PackageReference Include="OpenAI" Version="2.*" />
+<!-- OpenAI direct.
+     Microsoft.Agents.AI.OpenAI e Microsoft.Extensions.AI.OpenAI NÃO estão no ai-pin.json;
+     versões apuradas no nuget.org em 2026-09-08. -->
+<PackageReference Include="Microsoft.Agents.AI.OpenAI"     Version="1.20.0" />
+<PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="10.9.0" />
+<PackageReference Include="OpenAI"                         Version="2.13.0" />   <!-- pin -->
 
 <!-- Ollama (local / on-prem) — usa o mesmo OpenAI-compatible client -->
-<PackageReference Include="OpenAI" Version="2.*" />
+<PackageReference Include="OpenAI" Version="2.13.0" />                            <!-- pin -->
 
-<!-- Google Gemini — SDK verificado no standard model-registry.md -->
+<!-- Google Gemini — Google.GenAI 1.21.0 (pin). Ver ai-agents-providers-model-registry §providers -->
 <!-- Anthropic Claude — SDK verificado no standard model-registry.md -->
-<!-- Azure OpenAI (somente se data residency exigir) — Azure.AI.OpenAI 2.* + Azure.Identity 1.* -->
+<!-- Azure OpenAI (somente se data residency exigir) — confira Azure.AI.OpenAI + Azure.Identity no NuGet -->
 ```
 
-> The `.AsIChatClient()` extension on `OpenAI.ChatClient` comes from `Microsoft.Agents.AI.OpenAI`. The `IChatClient` abstraction itself lives in `Microsoft.Extensions.AI` (a transitive dependency of `Microsoft.Agents.AI`) — code that uses `IChatClient` needs `using Microsoft.Extensions.AI;`.
+> **Armadilha de restore, medida em 2026-09-08:** `Microsoft.Extensions.AI.OpenAI` 10.9.0 declara a dependência `OpenAI (>= 2.12.0 && < 2.13.0)`. Com o `OpenAI` **2.13.0** do pin, o `dotnet restore` emite **NU1608** (*"Versão detectada do pacote fora da restrição de dependência"*). Duas saídas honestas: fixar `OpenAI` em 2.12.x ao lado da ponte, **ou** aceitar o aviso conscientemente e registrar a decisão em `decisions.md`. Não descubra isso no CI.
+
+> **De onde vem cada extensão** (medido por reflexão sobre as assemblies do pin, 2026-09-08):
+> | Extensão | Assembly que a publica | Namespace do `using` |
+> |---|---|---|
+> | `.AsIChatClient()` sobre `OpenAI.Chat.ChatClient` e sobre `OpenAI.Responses.ResponsesClient` | **`Microsoft.Extensions.AI.OpenAI`** (`Microsoft.Extensions.AI.OpenAIClientExtensions`) | `Microsoft.Extensions.AI` |
+> | `.AsAIAgent(...)` sobre `ResponsesClient` / `ChatClient` | **`Microsoft.Agents.AI.OpenAI`** (`OpenAI.Responses.OpenAIResponseClientExtensions`, `OpenAI.Chat.OpenAIChatClientExtensions`) | `Microsoft.Agents.AI` + `OpenAI.Responses` / `OpenAI.Chat` |
+> | `.AsIChatClientWithStoredOutputDisabled(...)` | **`Microsoft.Agents.AI.OpenAI`** | `OpenAI.Responses` |
+>
+> A abstração `IChatClient` em si vive em `Microsoft.Extensions.AI.Abstractions` (dependência transitiva) — código que usa `IChatClient` precisa de `using Microsoft.Extensions.AI;`.
 
 > Os pacotes de Google e Anthropic mudam de nome/versão com frequência. O standard `ai-agents-providers-model-registry` mantém a lista verificada com data. Não trave SDK aqui.
 
 **Optional (only when feature requires):**
 
 ```xml
-<!-- Hosting helpers (AddAIAgent, AddSequentialWorkflow) -->
-<PackageReference Include="Microsoft.Agents.AI.Hosting" Version="1.0.*" />
+<!-- Hosting helpers (AddAIAgent, AddSequentialWorkflow).
+     PRERELEASE: não há versão estável. Apurado no nuget.org em 2026-09-08. -->
+<PackageReference Include="Microsoft.Agents.AI.Hosting" Version="1.20.0-preview.260831.1" />
+
+<!-- A2A protocol. PRERELEASE, fora do pin. Apurado em 2026-09-08. -->
+<PackageReference Include="Microsoft.Agents.AI.A2A" Version="1.20.0-preview.260831.1" />
 
-<!-- A2A protocol -->
-<PackageReference Include="Microsoft.Agents.AI.A2A" Version="1.0.*" />
+<!-- Workflows (grafo). Estável, fora do pin. Apurado em 2026-09-08. -->
+<PackageReference Include="Microsoft.Agents.AI.Workflows" Version="1.20.0" />
 ```
 
 **Forbidden in new MAF projects:**
 
-- `Microsoft.SemanticKernel.*` — superseded by MAF, do not introduce.
-- `Microsoft.Extensions.AI.OpenAI` 9.* — replaced by `Microsoft.Agents.AI.OpenAI` in GA.
+- `Microsoft.SemanticKernel.*` — superseded by MAF, do not introduce (ver a exceção de Vector Store abaixo).
+- `Microsoft.Extensions.AI.OpenAI` **9.\*** — a linha 9.x é a antiga. A linha **10.x é a atual e é o que a ponte `AsIChatClient` publica hoje**; ver a tabela de origem das extensões acima. (Correção de 2026-09-08: a versão anterior deste standard mandava substituir `Microsoft.Extensions.AI.OpenAI` por `Microsoft.Agents.AI.OpenAI`, o que não é possível — os dois pacotes publicam extensões **diferentes**.)
 - Hosted agent services (Foundry Agent Service, etc.) — use direct models.
 
-> **Exceção — conectores de Vector Store:** the ban above targets the SK **orchestration** surface (`Kernel`, `KernelFunction`, `ChatHistory`, `Kernel.InvokePromptAsync()`). It does **not** apply to `Microsoft.SemanticKernel.Connectors.*` packages (PgVector, Qdrant, SqlServer, CosmosNoSQL, InMemory) — those are `Microsoft.Extensions.VectorData` backend connectors with zero SK orchestration code, despite the package name. See `ai-agents-vector-data-extensions` before treating one of these as forbidden.
+> **Exceção — conectores de Vector Store:** the ban above targets the SK **orchestration** surface (`Kernel`, `KernelFunction`, `ChatHistory`, `Kernel.InvokePromptAsync()`). It does **not** apply to `Microsoft.SemanticKernel.Connectors.*` packages — those are `Microsoft.Extensions.VectorData` backend connectors with zero SK orchestration code, despite the package name. See `ai-agents-vector-data-extensions` before treating one of these as forbidden — e note que o conector PgVector foi **renomeado** para `CommunityToolkit.VectorData.PgVector`.
 
 ---
 
 ## 2. Quick Start (canonical minimal agent)
 
+**Caminho default para OpenAI: a Responses API.** Código conferido contra a doc oficial (learn.microsoft.com/en-us/agent-framework/integrations/by-component/model-providers/openai, `ms.date` 2026-09-03) e contra a assinatura real medida na assembly `Microsoft.Agents.AI.OpenAI` 1.20.0.
+
 ```csharp
 using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
 using OpenAI;
-using OpenAI.Chat;
+using OpenAI.Responses;
 
-AIAgent agent = new ChatClient(model: "gpt-4o-mini", apiKey: "<from-config>")
-    .AsIChatClient()
-    .AsAIAgent(instructions: "You are a helpful assistant.");
+OpenAIClient client = new OpenAIClient("<from-config>");
+ResponsesClient responses = client.GetResponsesClient();
+
+AIAgent agent = responses.AsAIAgent(
+    model: "gpt-4o-mini",
+    instructions: "You are a helpful assistant.",
+    name: "assistant");
 
 var response = await agent.RunAsync("Analyze this order.");
 Console.WriteLine(response.Text);
 ```
 
+Para o caminho `IChatClient` puro (sem MAF):
+
+```csharp
+using Microsoft.Extensions.AI;
+using OpenAI;
+
+IChatClient chat = new OpenAIClient("<key>")
+    .GetResponsesClient()
+    .AsIChatClient("gpt-4o-mini");   // o modelo é argumento da ponte, não do GetResponsesClient()
+```
+
+> **Assinatura medida:** `OpenAIClient.GetResponsesClient()` **não recebe modelo**; o modelo entra em `AsAIAgent(model:)` ou em `AsIChatClient(defaultModelId)`. Isso difere do `GetChatClient(model)` da Chat Completions.
+
 This snippet is the baseline. In a real project you never hardcode the model — use the Model Registry (`ai-agents-providers-model-registry`). Anything more complex (DI, tools, structured output, RAG) layers on top via the other ai-agents standards.
 
+### Por que Responses é o default
+
+| Ferramenta hospedada | Responses | Chat Completions |
+|---|---|---|
+| Code Interpreter | ✔ | ✘ |
+| File Search | ✔ | ✘ |
+| Hosted MCP | ✔ | ✘ |
+| Function calling (tools do seu código) | ✔ | ✔ |
+
+Fontes, ambas lidas em 2026-09-08:
+
+- Microsoft Learn, *Agent Framework → model providers → OpenAI* (`ms.date` 2026-09-03), verbatim: *"Responses is the recommended primary client when available"* — é de lá que sai a matriz acima.
+- OpenAI, *Migrate to the Responses API* (developers.openai.com/api/docs/guides/migrate-to-responses), verbatim: *"While Chat Completions remains supported, Responses is recommended for all new projects."* e *"…improved cache utilization (40% to 80% improvement when compared to Chat Completions in internal tests)"*.
+
+**Chat Completions continua legítima** — não está deprecada. Escolha-a, **por escrito no alias** (`"api": "chat"`), quando: (a) o modelo alvo não é servido pela Responses; (b) a integração existente já fala Chat Completions e o custo de migrar não se paga; (c) há um SDK de outra linguagem no caminho (o Go, por exemplo) sem cliente de Responses. Ver `ai-agents-providers-model-registry` §API per alias — inclusive o limite documentado de tool calling com `reasoning_effort` na Chat Completions.
+
+### `store: false` é a regra da casa
+
+A Responses API **armazena por padrão**. OpenAI, mesmo guia, verbatim: *"Responses are stored by default. Chat completions are stored by default for new accounts. To disable storage when using either API, set `store: false`."* Respostas retidas ficam 30 dias no provedor.
+
+Projetos desta casa mantêm o histórico **próprio** (ver `ai-agents-agent-session`), então não se quer uma segunda cópia da conversa no provedor. **Regra: `store: false` explícito.** Quem quiser o oposto registra o porquê em `decisions.md`.
+
+O MAF tem um atalho de primeira classe para isso — medido na assembly `Microsoft.Agents.AI.OpenAI` 1.20.0:
+
+```csharp
+using OpenAI.Responses;
+
+// AsIChatClientWithStoredOutputDisabled(ResponsesClient, string model, bool includeReasoningEncryptedContent)
+IChatClient chat = new OpenAIClient("<key>")
+    .GetResponsesClient()
+    .AsIChatClientWithStoredOutputDisabled(
+        model: "gpt-4o-mini",
+        includeReasoningEncryptedContent: true);   // reasoning encriptado viaja no lugar do estado no servidor
+```
+
+No caminho cru do SDK, o campo é `CreateResponseOptions.StoredOutputEnabled = false` (medido; o nome C# não é `Store`).
+
+> **Nota de leitura sobre reasoning encriptado:** a doc da OpenAI (*deployment checklist*) diz que *"…encrypted reasoning content enables a stateless handoff"*. Que isso seja **exclusivo** da Responses API é **inferência** desta casa a partir do conjunto das páginas, não uma frase da OpenAI — e está marcado como inferência de propósito.
+
+### `OPENAI001`
+
+**Medido, não inferido:** em `OpenAI` 2.13.0, `OpenAI.Responses.ResponsesClient` e `OpenAI.Responses.CreateResponseOptions` **ainda carregam** `[Experimental("OPENAI001")]` (reflexão sobre a assembly do pin, 2026-09-08). `OpenAI.Chat.ChatClient` não carrega.
+
+Consequência prática: código que toca os tipos concretos de Responses precisa de `#pragma warning disable OPENAI001` ou `<NoWarn>OPENAI001</NoWarn>` no `.csproj`. Código que fica em `IChatClient`/`AIAgent` **não** precisa — a ponte absorve o diagnóstico. É um argumento objetivo a favor da abstração, não preferência de estilo.
+
 ---
 
 ## 3. Setup by Provider
 
 > In any project with >1 model or >1 provider, **do not register `IChatClient` directly** — use the Model Registry (`ai-agents-providers-model-registry`). The snippets below show the raw client construction the registry wraps.
 
-### 3.1 OpenAI direct (most common)
+### 3.1 OpenAI direct — Responses (default)
 
 ```csharp
 using OpenAI;
-using OpenAI.Chat;
+using OpenAI.Responses;
 using Microsoft.Extensions.AI;
 
 builder.Services.AddSingleton<IChatClient>(sp =>
@@ -120,10 +202,11 @@ builder.Services.AddSingleton<IChatClient>(sp =>
         throw new InvalidOperationException(
             "OpenAI:ApiKey is required. Bind it from an environment variable or secret store.");
     }
-    return new ChatClient(
+    return new OpenAIClient(apiKey)
+        .GetResponsesClient()
+        .AsIChatClientWithStoredOutputDisabled(
             model: cfg["OpenAI:Model"] ?? "gpt-4o-mini",
-            apiKey: apiKey)
-        .AsIChatClient();
+            includeReasoningEncryptedContent: true);
 });
 ```
 
@@ -132,12 +215,27 @@ builder.Services.AddSingleton<IChatClient>(sp =>
 > exist with blank values — which is the common shape of a checked-in
 > `appsettings.json` placeholder (`"OpenAI": { "ApiKey": "" }`). A
 > `?? throw` guard against `null` therefore never fires; the program
-> proceeds to `new ChatClient(model, "")` and crashes much later with
+> proceeds to a client built with `""` and crashes much later with
 > an opaque OpenAI SDK error. Always check whitespace.
 
+### 3.1.b OpenAI direct — Chat Completions (opt-in explícito)
+
+Legítimo, mas escolhido por escrito. Ver `ai-agents-providers-model-registry` §API per alias.
+
+```csharp
+using OpenAI;
+using OpenAI.Chat;
+using Microsoft.Extensions.AI;
+
+builder.Services.AddSingleton<IChatClient>(sp =>
+    new OpenAIClient(apiKey)
+        .GetChatClient(cfg["OpenAI:Model"] ?? "gpt-4o-mini")   // modelo no Get, aqui
+        .AsIChatClient());
+```
+
 ### 3.2 Ollama (local dev / on-prem)
 
-Ollama exposes an OpenAI-compatible endpoint — use the same `ChatClient`:
+Ollama exposes an **OpenAI-compatible** endpoint — Chat Completions, não Responses. A Responses API é da OpenAI, não do protocolo compatível: nunca aponte um endpoint de Ollama para o caminho de Responses.
 
 ```csharp
 using OpenAI;
@@ -157,17 +255,17 @@ builder.Services.AddSingleton<IChatClient>(sp =>
 
 ### 3.3 Google (Gemini) / Anthropic (Claude)
 
-Both are first-class providers reached as direct models. The exact NuGet SDK and client construction are documented (with verification date) in `ai-agents-providers-model-registry` §providers — that standard is the single source of truth for provider SDKs, since they change names/versions often.
+Both are first-class providers reached as direct models. The exact NuGet SDK and client construction are documented (with verification date) in `ai-agents-providers-model-registry` §providers — that standard is the single source of truth for provider SDKs, since they change names/versions often. O pin traz `Google.GenAI` **1.21.0**.
 
 ### 3.4 Azure OpenAI (note — not a default)
 
-Azure OpenAI is also a direct model, but requires an Azure resource + deployment per model. It is **not a default provider** in this framework — projects deploy to VPS, not Azure. Add an Azure branch to the Model Registry only when a client explicitly requires data residency in a specific Azure region. The pattern: `new AzureOpenAIClient(endpoint, credential).GetChatClient(deployment).AsIChatClient()`.
+Azure OpenAI is also a direct model, but requires an Azure resource + deployment per model. It is **not a default provider** in this framework — projects deploy to VPS, not Azure. Add an Azure branch to the Model Registry only when a client explicitly requires data residency in a specific Azure region. The pattern: `new AzureOpenAIClient(endpoint, credential).GetChatClient(deployment).AsIChatClient()`. Confirme as versões de `Azure.AI.OpenAI` e `Azure.Identity` no NuGet antes de travar — não estão no pin.
 
 ---
 
 ## 4. DI Registration (keyed agents)
 
-> The `builder.AddAIAgent(...)` extension requires the `Microsoft.Agents.AI.Hosting` package (see §1 Optional). For projects that register agents manually without `AddAIAgent`, the base `Microsoft.Agents.AI` package is enough.
+> The `builder.AddAIAgent(...)` extension requires the `Microsoft.Agents.AI.Hosting` package (see §1 Optional) — que está em **prerelease**. For projects that register agents manually without `AddAIAgent`, the base `Microsoft.Agents.AI` package is enough.
 
 ```csharp
 // Program.cs
@@ -188,27 +286,36 @@ public class AgentController(
     [FromKeyedServices("OrderAnalyzer")] AIAgent orderAgent) : ControllerBase { ... }
 ```
 
-For agents with tools and structured output, see `ai-agents-multi-agent-patterns` and `ai-agents-structured-output` (Onda 2).
+For agents with tools and structured output, see `ai-agents-multi-agent-patterns` and `ai-agents-structured-output`.
 
 ---
 
 ## 5. OpenTelemetry
 
+**Correção medida em 2026-09-08:** `AgentOpenTelemetryConsts` e `agent.WithOpenTelemetry()` **não existem** em `Microsoft.Agents.AI` 1.20.0 (reflexão sobre a assembly do pin). A API real é `UseOpenTelemetry` sobre o *builder* de cada nível:
+
 ```csharp
 using OpenTelemetry;
 using OpenTelemetry.Trace;
 using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
 
+// Duas ActivitySource DIFERENTES, uma por nível — medidas nas assemblies do pin:
+//   agente     → "Experimental.Microsoft.Agents.AI"        (span invoke_agent)
+//   chat/tools → "Experimental.Microsoft.Extensions.AI"    (spans chat e execute_tool)
 using var tracerProvider = Sdk.CreateTracerProviderBuilder()
-    .AddSource(AgentOpenTelemetryConsts.DefaultSourceName)
+    .AddSource("Experimental.Microsoft.Agents.AI")
+    .AddSource("Experimental.Microsoft.Extensions.AI")
     .AddOtlpExporter()
     .Build();
 
-// Wrap any agent (e.g. the `agent` from §2)
-var instrumented = agent.WithOpenTelemetry();
+AIAgent instrumented = agent.AsBuilder()
+    .UseOpenTelemetry(sourceName: "Experimental.Microsoft.Agents.AI",
+                      configure: o => o.EnableSensitiveData = false)
+    .Build();
 ```
 
-> **Note:** Source name is `AgentOpenTelemetryConsts.DefaultSourceName` from `Microsoft.Agents.AI`. **Do NOT** use the old `Experimental.Microsoft.Extensions.AI.*` source — it belongs to a previous package family.
+> A regra de **onde** instrumentar (e como não duplicar span) é do standard `ai-agents-observability-patterns` — que é o dono canônico do assunto. O que precisa ficar aqui é só o fato que muda o `.csproj` e o `Program.cs`: são **duas** fontes, e o `AddSource` precisa das duas quando os dois níveis estão instrumentados. A instrução antiga deste standard — *"não use `Experimental.Microsoft.Extensions.AI.*`"* — está **errada para o pin** e foi removida.
 
 ---
 
@@ -217,7 +324,8 @@ var instrumented = agent.WithOpenTelemetry();
 - [ ] API keys never in source. Bind from environment variables / secret store (the VPS deploy uses env vars; Docker secrets or a vault are fine too).
 - [ ] `appsettings.json` checked into git never contains real keys — only placeholder/empty values.
 - [ ] Provider keys (`OpenAI:ApiKey`, `Google:ApiKey`, `Anthropic:ApiKey`) bound from environment.
-- [ ] No agent receives raw user input without input-validation middleware (see `ai-agents-middleware-patterns` — Onda 2).
+- [ ] `store: false` (ou `AsIChatClientWithStoredOutputDisabled`) quando o projeto tem histórico próprio — senão a conversa fica duplicada no provedor por 30 dias.
+- [ ] No agent receives raw user input without input-validation middleware (see `ai-agents-middleware-patterns`).
 
 ---
 
@@ -230,18 +338,24 @@ var instrumented = agent.WithOpenTelemetry();
 | `[KernelFunction]` | `[Description]` on method + parameters; register via `AIFunctionFactory.Create()` |
 | `ChatHistory` | `IEnumerable<ChatMessage>` |
 | Hardcoded model strings spread across codebase | Single source via Model Registry (see `ai-agents-providers-model-registry`) |
-| `Microsoft.Extensions.AI.OpenAI` 9.* | `Microsoft.Agents.AI.OpenAI` 1.* GA |
+| `PackageReference` com faixa flutuante (`2.*`, `1.0.*`) | Versão exata; fora do pin, com data de apuração |
+| Chat Completions por inércia num projeto novo OpenAI | Responses, e Chat Completions só com `"api": "chat"` escrito no alias |
+| Responses com o `store` default | `store: false` / `AsIChatClientWithStoredOutputDisabled` |
+| Apontar Ollama/endpoint compatível para o caminho de Responses | Ollama fala Chat Completions |
 | Hosted agent service "to simplify" | Direct models always |
 
 ---
 
 ## 8. Checklist (verifiable by morph-eval)
 
-- [ ] `Microsoft.Agents.AI` package present in `.csproj`
-- [ ] No `Microsoft.SemanticKernel.*` references
+- [ ] `Microsoft.Agents.AI` package present in `.csproj`, com versão exata
+- [ ] No `Microsoft.SemanticKernel.*` orchestration references
+- [ ] Nenhum `PackageReference` de SDK de IA com faixa flutuante
 - [ ] `IChatClient` registered (either directly or via Model Registry)
 - [ ] At least one `AIAgent` created via `AsAIAgent()` or `new ChatClientAgent()`
-- [ ] OpenTelemetry source name is `AgentOpenTelemetryConsts.DefaultSourceName` (if telemetry wired)
+- [ ] Projeto OpenAI novo usa Responses, ou tem `"api": "chat"` declarado no alias
+- [ ] `store` desligado quando o histórico é próprio
+- [ ] Telemetria (se ligada) faz `AddSource` das **duas** fontes: `Experimental.Microsoft.Agents.AI` e `Experimental.Microsoft.Extensions.AI`
 - [ ] Models reference Model Registry alias when project has >1 model use case
 
 ---
@@ -249,13 +363,15 @@ var instrumented = agent.WithOpenTelemetry();
 ## 9. References
 
 - `ai-agents-sweet-spot` — when to use agents vs workflows
-- `ai-agents-providers-model-registry` — provider-agnostic pattern
-- `ai-agents-structured-output` (Onda 2) — typed responses
-- `ai-agents-middleware-patterns` (Onda 2) — telemetry, retry, anti-hallucination, streaming agent responses
-- `ai-agents-vector-data-extensions` — the `Microsoft.SemanticKernel.Connectors.*` exception to the Forbidden list above
-- Microsoft.Agents.AI docs: https://learn.microsoft.com/agent-framework/
-- Verified packages list (context7 /microsoft/agent-framework): retrieved 2026-05-19
+- `ai-agents-providers-model-registry` — provider-agnostic pattern, `api` por alias, reasoning effort
+- `ai-agents-agent-session` — histórico próprio, e por que `store: false`
+- `ai-agents-observability-patterns` — dono canônico de spans, métricas e duplicação
+- `ai-agents-structured-output` — typed responses
+- `ai-agents-middleware-patterns` — telemetry, retry, anti-hallucination, streaming agent responses
+- `ai-agents-vector-data-extensions` — a exceção `Microsoft.SemanticKernel.Connectors.*` da lista Forbidden acima
+- Microsoft.Agents.AI docs: https://learn.microsoft.com/agent-framework/ (`ms.date` 2026-09-03 na página de OpenAI)
+- OpenAI, *Migrate to the Responses API*: https://developers.openai.com/api/docs/guides/migrate-to-responses (lido 2026-09-08)
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/setup.md v2.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/setup.md v3.0 (2026-09-08)*