@polymorphism-tech/morph-spec 8.34.2 → 8.35.1

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)*

package/framework/standards/ai-agents/structured-output.md

@@ -5,7 +5,7 @@
 > **Keywords:** structured output, typed response, response format, schema validated output, record output, JSON schema agent, RunAsync generic
 > **Read by Claude in:** implement (sempre que um agente produz saída consumida por outro sistema)
 
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+**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` **apenas** para o mapeamento de `AgentSpec.OutputSchema` → `ChatOptions.ResponseFormat = ChatResponseFormat.ForJsonSchema(...)`, que é o que o kit compila. `RunAsync<T>`, `Deserialize<T>` e os limites do `ResponseFormat` são **verificação documental**, com os nomes de tipo medidos por reflexão sobre `Microsoft.Extensions.AI.Abstractions` 10.9.0 em 2026-09-08. Last-verified: 2026-09-08.
 
 ---
 
@@ -55,9 +55,11 @@ ProposalDraft draft = response.Deserialize<ProposalDraft>(JsonSerializerOptions.
 ```
 
 **Use Form 2 quando:**
-- Você precisa setar `ResponseFormat` junto com outras `ChatOptions` (ex: temperatura, system prompt por invocação).
+- Você precisa setar `ResponseFormat` junto com outras `ChatOptions` (ex.: `ModelId`, `MaxOutputTokens`, system prompt por invocação).
 - Você quer reusar o mesmo agente para múltiplos tipos de saída, trocando o format por chamada via `ChatClientAgentRunOptions`.
 
+> **Por que o exemplo não é `Temperature`.** Um alias de raciocínio não carrega temperatura, e em modelo de raciocínio ela é justamente a opção que não se envia — ver `ai-agents-providers-model-registry` §*temperature × reasoning*. Usar temperatura como exemplo de "outra `ChatOption` normal" ensina a colisão pela porta dos fundos.
+
 **Setando ResponseFormat por invocação (sem recriar o agente):**
 
 ```csharp
@@ -70,6 +72,31 @@ AgentResponse response = await agent.RunAsync("Draft a proposal.", runOptions);
 ProposalDraft draft = response.Deserialize<ProposalDraft>(JsonSerializerOptions.Web);
 ```
 
+### Limites documentados do `ResponseFormat`
+
+1. **Não aceita primitivo nem array na raiz.** `ChatResponseFormat.ForJsonSchema<string>()` ou `<List<Item>>` não é um schema de objeto válido para o provedor. Embrulhe:
+
+   ```csharp
+   // ERRADO: raiz é array
+   // ResponseFormat = ChatResponseFormat.ForJsonSchema<List<ProposalItem>>()
+
+   // CERTO: wrapper com a coleção como propriedade
+   [Description("A list of proposal line items")]
+   public sealed record ProposalItems
+   {
+       [JsonPropertyName("items")] public required IReadOnlyList<ProposalItem> Items { get; init; }
+   }
+   ```
+
+2. **Em streaming, não desserialize os pedaços.** Um `ChatResponseUpdate` isolado é JSON incompleto. Monte a resposta primeiro e desserialize o todo:
+
+   ```csharp
+   AgentResponse full = await agent.RunStreamingAsync(prompt, session).ToAgentResponseAsync();
+   ProposalDraft draft = full.Deserialize<ProposalDraft>(JsonSerializerOptions.Web);
+   ```
+
+3. **Bug conhecido com arrays — ISSUE ABERTA, não comportamento estável.** A issue **2874** do repositório `microsoft/agent-framework` relata falha de `ResponseFormat` com propriedades de array em certos provedores. Está **em aberto** na data desta verificação (2026-09-08): trate como armadilha a verificar no seu provedor, **não** como regra do framework. Se aparecer, o contorno é o wrapper do item 1 mais validação pós-call.
+
 ---
 
 ## Definindo o tipo de saída
@@ -233,6 +260,8 @@ public async Task<Result<ProposalDraft>> DraftValidatedAsync(string clientContex
 - [ ] O tipo de saída é um `sealed record` ou `sealed class` decorado com `[Description("...")]`.
 - [ ] CADA propriedade do tipo de saída tem `[JsonPropertyName("...")]` explícito.
 - [ ] Validação de regras de negócio existe após `RunAsync<T>` — o resultado é verificado além da shape do schema.
+- [ ] Nenhum `ResponseFormat` com primitivo ou array na raiz — coleções vão dentro de um wrapper.
+- [ ] Em streaming, a desserialização acontece depois de `ToAgentResponseAsync()`, nunca por update.
 - [ ] O agente é construído a partir de `_modelRegistry.GetChatClient("alias")` — nenhum model name hardcoded.
 
 ---
@@ -242,8 +271,10 @@ public async Task<Result<ProposalDraft>> DraftValidatedAsync(string clientContex
 - `ai-agents-setup` — packages, DI, e setup mínimo de agente
 - `ai-agents-sweet-spot` — quando usar agente, quando não usar
 - `ai-agents-providers-model-registry` — como registrar e resolver modelos por alias
+- `ai-agents-agent-session` — `RunStreamingAsync` numa sessão, e onde o histórico entra
 - Microsoft Agent Framework docs: https://learn.microsoft.com/agent-framework/
+- Issue aberta `microsoft/agent-framework#2874` — arrays com `ResponseFormat` (estado em 2026-09-08: **aberta**)
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/structured-output.md v1.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/structured-output.md v1.1 (2026-09-08)*

package/framework/standards/ai-agents/sweet-spot.md

@@ -2,10 +2,10 @@
 
 > **Scope:** stacks=["dotnet"]
 > **Layer:** 0 (always-load via persona maf-expert)
-> **Keywords:** sweet spot, when to use agent, agent vs workflow, when not to use workflow, MAF decision, simple agent
+> **Keywords:** sweet spot, when to use agent, agent vs workflow, when not to use workflow, MAF decision, simple agent, tool budget, quantas tools
 > **Read by Claude in:** plan (decide arquitetura da feature antes de quebrar em tasks) + implement (validar que a arquitetura ainda é a mais simples possível)
 
-**Verified against:** MAF Tier List research (2026-05-18) + Microsoft Learn docs. Last-verified: 2026-05-19.
+**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Agents.AI.Workflows 1.20.0 (ai-pin 2026-09-08 para o primeiro; o segundo está **fora do pin**, versão apurada no nuget.org em 2026-09-08). **Verificação documental**, sem cláusula `provado por` — este standard é decisão de arquitetura, não API. A escada de complexidade foi reconferida e **continua correta**; o que entrou de novo é o custo de definição de tool por turno e o status do Handoff. Last-verified: 2026-09-08.
 
 ---
 
@@ -24,6 +24,23 @@ If your feature needs ONLY these 4 → use a single agent. Don't reach for workf
 
 Apply this rule before deciding multi-agent or workflow. Most of the time the answer is "single agent".
 
+### O quinto sinal: quantas tools o agente carrega
+
+A regra das 4 features diz **o que** o agente faz. Falta **quanto** ele carrega — e esse é o custo que ninguém vê no código.
+
+**Toda tool registrada entra na definição enviada ao modelo em CADA turno**: nome, descrição e o JSON Schema completo dos parâmetros. Um agente com 40 tools paga esses 40 schemas de entrada em todo turno, inclusive nos turnos em que nenhuma tool é chamada — e paga de novo em cada volta do laço de tool calling.
+
+**Referência prática: ≤ 12 tools por agente.** Acima disso, dois efeitos se somam, e o segundo é pior que o primeiro:
+
+1. **Custo por turno cresce** com o tamanho da definição.
+2. **A escolha piora.** Quanto mais tools parecidas, mais o modelo erra qual chamar — e um erro de escolha custa uma volta inteira.
+
+**Quando estourar o teto, na ordem:** (a) **poda** — remova o que não é usado naquele modo; (b) **plano por fase** — uma allow-list por estado do funil, montada em C# (`ai-agents-context-providers` §Ordem de escolha); (c) **só então** agent-as-tool, com o auxiliar carregando o próprio subconjunto (`ai-agents-multi-agent-patterns`). Servidor MCP com dezenas de tools é o caso mais comum de estouro — ver `ai-agents-mcp-tools` §Custo de definição de tool por turno.
+
+### Status do Handoff (2026-09-08)
+
+O Handoff era marcado **experimental** no 1.0 e **graduou**: `Microsoft.Agents.AI.Workflows.HandoffWorkflowBuilder` **não carrega** `[Experimental]` na assembly 1.20.0 (medido). Isso muda o degrau da escada: handoff deixou de ser "experimental, evite" e passou a ser "estável, mas ainda depois de agent-as-tool" — a ordem de preferência **não** mudou, o motivo mudou. O critério continua o mesmo: agent-as-tool primeiro, handoff quando há N especialistas e a decisão de roteamento não cabe numa tool.
+
 ---
 
 ## Decision tree (Claude reads this in plan phase)
@@ -92,6 +109,7 @@ You may need to step outside the sweet spot when:
 - [ ] If a Workflow is used, is fan-in/out or HITL checkpointing genuinely present? Or could `foreach + LINQ` replace it?
 - [ ] Are the 4 features (Chat, Structured Output, Tools, RAG Custom) all present where applicable?
 - [ ] Are hosted agent services avoided?
+- [ ] Nenhum agente carrega mais de ~12 tools sem uma decisão escrita em `decisions.md` sobre a poda
 
 ---
 
@@ -103,7 +121,9 @@ You may need to step outside the sweet spot when:
 - `ai-agents-multi-agent-patterns` (Onda 2)
 - `ai-agents-workflows` (Onda 2, reframed)
 - `ai-agents-rag-custom-pgvector` (Onda 2)
+- `ai-agents-mcp-tools` — o caso mais comum de estouro do teto de tools
+- `ai-agents-context-providers` — plano por fase com allow-list de tools
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/sweet-spot.md v1.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/sweet-spot.md v1.1 (2026-09-08)*