@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/framework/standards/ai-agents/multi-agent-patterns.md

@@ -2,10 +2,10 @@
 
 > **Scope:** stacks=["dotnet"]
 > **Layer:** 1 (on-keyword)
-> **Keywords:** multi-agent, agent as tool, agent composition, sequential agents, handoff, sub-agent, agent orchestration
+> **Keywords:** multi-agent, agent as tool, agent composition, sequential agents, handoff, sub-agent, agent orchestration, agente auxiliar, nesting
 > **Read by Claude in:** plan (quando ai-agents-sweet-spot indica multi-agent) + implement
 
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+**Verified against:** Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08) + Microsoft.Agents.AI.Workflows 1.20.0 (**fora do pin**; versão apurada no nuget.org em 2026-09-08). **Verificação documental**, sem cláusula `provado por` — o ai-kit não compõe agentes. As assinaturas de `AgentWorkflowBuilder`/`HandoffWorkflowBuilder` e a **ausência** do atributo `[Experimental]` no Handoff foram **medidas por reflexão sobre a assembly 1.20.0** em 2026-09-08. Last-verified: 2026-09-08.
 
 ---
 
@@ -91,12 +91,59 @@ Use `AgentWorkflowBuilder.BuildSequential(agent1, agent2, ...)` quando precisar
 
 Um agent de triagem decide qual especialista assume o controle com base no contexto. Útil quando há N especialistas e a decisão de roteamento é complexa demais para uma tool simples.
 
-Para handoff baseado em Workflow: `AgentWorkflowBuilder.CreateHandoffBuilderWith(triageAgent).WithHandoffs(...)`. Ver `ai-agents-workflows` para o padrão completo.
+**Status: graduou.** O Handoff era marcado experimental no 1.0 e foi anunciado como *"graduating to release"* no BUILD 2026 (2026-06-03). **Medido em 2026-09-08:** `Microsoft.Agents.AI.Workflows.HandoffWorkflowBuilder` e `AgentWorkflowBuilder` **não carregam** `[Experimental]` na assembly 1.20.0 — a graduação está no binário, não só no anúncio.
+
+Para handoff baseado em Workflow: `AgentWorkflowBuilder.CreateHandoffBuilderWith(triageAgent)`. Ver `ai-agents-workflows` para o padrão completo.
+
+**Limites documentados, e o que cada um evita** (assinaturas medidas em `HandoffWorkflowBuilderCore<TBuilder>`):
+
+| Limite | Como | O que evita |
+|---|---|---|
+| Teto de turnos | `.WithAutonomousMode(turnLimit: 8)` — aceita também `agentTurnLimits` por agente | Loop infinito de dois agentes se devolvendo a conversa |
+| Condição de término | `.WithTerminationCondition(...)` | O mesmo, por critério de conteúdo em vez de contagem |
+| `Id` estável por agente | Cada `AIAgent` com `Id` fixo (não regenerado a cada boot) | Handoff que aponta para um agente que "sumiu" entre reinícios |
+| Group chat pequeno | ≤ **3** agentes por group chat | Acima disso o gerente gasta mais turnos escolhendo quem fala do que resolvendo |
 
 > Para roteamento simples (2-3 caminhos), considere Agent-as-Tool com um agent por caminho antes de ir para Handoff Workflow.
 
 ---
 
+## Agente auxiliar: em SEQUÊNCIA, nunca dentro de uma tool
+
+**Anti-padrão medido em campo.** É tentador embrulhar um agente auxiliar (resumidor, classificador, extrator) numa tool do agente principal: parece composição barata. Não é.
+
+```csharp
+// ERRADO — o auxiliar roda DENTRO da tool do principal.
+AIFunction summarize = AIFunctionFactory.Create(async (string text) =>
+{
+    var r = await _summarizerAgent.RunAsync(text);   // agente aninhado na tool
+    return r.Text;
+});
+```
+
+**Dois problemas concretos:**
+
+1. **`CallId` com tools encadeadas.** O agente auxiliar tem o próprio ciclo de tool calling. Rodando dentro da tool do principal, dois laços de function-calling se sobrepõem no mesmo turno, e a reconciliação de `CallId` entre pedido e resultado passa a depender da ordem em que os dois laços terminam.
+2. **O loop do principal fica aberto enquanto o auxiliar roda.** O principal está no meio de um turno, com uma chamada pendente, esperando algo que pode levar várias voltas de LLM. Timeout, retry e telemetria do turno principal passam a medir a soma dos dois.
+
+**O contrato correto são DUAS chamadas visíveis, em sequência:**
+
+```csharp
+// CERTO — o auxiliar roda FORA, e o resultado entra como dado no turno seguinte.
+AgentResponse summary = await _summarizerAgent.RunAsync(text);
+AgentResponse answer  = await _mainAgent.RunAsync(
+    $"Resumo do documento:
+{summary.Text}
+
+Pergunta: {question}", session);
+```
+
+Cada chamada tem o próprio span, o próprio custo e o próprio timeout — e o orquestrador é o **código**, não o modelo. É o mesmo princípio do compositor determinístico em `ai-agents-context-providers`.
+
+**A exceção, com regra:** `agent.AsAIFunction()` é a composição barata **antes** de qualquer orquestração — e serve exatamente quando o LLM principal precisa **decidir** se chama o auxiliar. Nesse caso vale o teto: **aninhamento ≤ 2 níveis** (pai → filho). Um terceiro nível é sinal de que a composição devia ser sequência no código.
+
+---
+
 ## Decision tree
 
 ```
@@ -126,7 +173,11 @@ Tenho múltiplos agents — qual padrão usar?
 | Usar multi-agent quando um único agent resolve | Adiciona latência, custo e superfície de erro sem ganho | Single agent com tools. Ver `ai-agents-sweet-spot`. |
 | Usar Workflow quando Agent-as-Tool basta | Workflow traz edges, builders, streaming — complexidade desnecessária | `agent.AsAIFunction()` primeiro |
 | Passar histórico de conversa bruto entre agents | Output do LLM é não-determinístico; o outro agent não sabe o que fazer com histórico livre | Structured Output entre agents. Ver `ai-agents-structured-output`. |
-| Nesting profundo (agent A chama B chama C chama D) | Dificulta debug, amplifica latência, falhas em cascata | Achate a composição: Agent-as-Tool com o agent folha direto no pai. |
+| Nesting profundo (agent A chama B chama C chama D) | Dificulta debug, amplifica latência, falhas em cascata | Achate a composição: Agent-as-Tool com o agent folha direto no pai; teto de **2** níveis. |
+| **Agente auxiliar aninhado dentro de uma tool** | Dois laços de function-calling no mesmo turno (reconciliação de `CallId`) e o turno do principal aberto enquanto o auxiliar roda | Duas chamadas visíveis, auxiliar **em sequência**, fora da tool |
+| Handoff sem `turnLimit` nem condição de término | Dois agentes devolvem a conversa um ao outro indefinidamente | `.WithAutonomousMode(turnLimit:)` ou `.WithTerminationCondition(...)` |
+| `Id` de agente gerado a cada boot num workflow de handoff | O destino do handoff deixa de existir entre reinícios | `Id` estável, vindo de configuração |
+| Group chat com 5+ agentes | O gerente gasta os turnos escolhendo quem fala | ≤ 3 agentes; acima disso, repense a decomposição |
 | Agents com responsabilidades sobrepostas | Nenhum dos dois sabe quando agir; o LLM fica confuso | Fronteiras claras de responsabilidade; documente em `decisions.md`. |
 
 ---
@@ -139,6 +190,9 @@ Tenho múltiplos agents — qual padrão usar?
 - [ ] Agents usando alias do Model Registry — nenhum model string hardcoded?
 - [ ] Structured Output entre agents onde o output de um é input do outro?
 - [ ] Nesting máximo de 2 níveis (pai → filho) sem cascata profunda?
+- [ ] Nenhum agente auxiliar roda dentro de uma tool de outro agente — auxiliares são chamadas em sequência, no código?
+- [ ] Todo workflow de handoff tem `turnLimit` **ou** condição de término, e os agentes têm `Id` estável?
+- [ ] Group chat (se houver) tem no máximo 3 agentes?
 
 ---
 
@@ -149,7 +203,9 @@ Tenho múltiplos agents — qual padrão usar?
 - `ai-agents-setup` — pacotes, DI, `AsAIAgent`
 - `ai-agents-structured-output` — output tipado entre agents
 - `ai-agents-providers-model-registry` — Model Registry alias pattern
+- `ai-agents-context-providers` — o compositor determinístico: o código decide o modo, o LLM classifica
+- `ai-agents-observability-patterns` — por que "uma chamada, um span" importa para medir latência
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/multi-agent-patterns.md v1.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/multi-agent-patterns.md v2.0 (2026-09-08)*

package/framework/standards/ai-agents/observability-patterns.md

@@ -5,7 +5,7 @@
 > **Keywords:** observability, telemetry, opentelemetry, logging, tracing, log investigation, troubleshooting, aspire dashboard, span, correlation id
 > **Read by Claude in:** implement (wiring telemetry into an agent) and troubleshoot (investigating a production issue)
 
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-07-22.
+**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/Observability/MorphOpenTelemetryExtensions.cs` — o guard de span duplicado, a regra de "um nível, uma instrumentação" e o default `EnableSensitiveData = false` são exatamente o que o kit compila, com os spans contados em `tests/Morph.AiKit.Tests/TelemetryTests.cs`. Nomes de símbolo, de span, de métrica e das duas `ActivitySource` foram **medidos por reflexão e por leitura dos literais das assemblies do pin** em 2026-09-08, e em 2026-09-09 **todos os treze nomes `gen_ai.*` desta página** foram remedidos, um a um, por **teste de exclusividade**: os quatro `SetTag` da seção *Enrichment* e os nove das seções de span, métrica e atributo de agente. **Os treze existem** — depois de uma correção: `gen_ai.response.finish_reason`, no **singular**, não existia, só aparecia como cabeça de `finish_reason`**s**, e sobreviveu a duas varreduras porque as duas usaram `includes` — e **`includes` de um prefixo não prova o literal autônomo**. Os treze estão tabelados, em **duas** tabelas com propósitos diferentes: a de *Enrichment* registra os **4** `SetTag` daquele bloco (mais os **cinco** nomes rejeitados: o `finish_reason` singular, `PromptTokens`, `CompletionTokens`, `prompt_tokens` e `completion_tokens`), e a de distribuição, na seção *Nomes de span, métricas e atributos — medidos*, registra os **13** por assembly. A conferência é reproduzível por `node scripts/api-probe/probe.mjs tags` sobre este arquivo. A **instabilidade da convenção** — o split do semconv **v1.42.0 (2026-06-12)**, que depreciou e moveu todo `gen_ai.*` para `open-telemetry/semantic-conventions-genai`, onde nada GenAI está `Stable`, contra a v1.37 que o `OpenTelemetryChatClient` declara implementar — é **verificação documental**, apurada em 2026-09-08. Last-verified: 2026-09-08.
 
 ---
 
@@ -17,28 +17,45 @@ Um agente MAF em produção não é uma função — é uma cadeia (LLM call →
 
 ## Setup — OpenTelemetry
 
+### Duas correções medidas contra a versão anterior deste standard
+
+| O que este standard dizia | O que o pin diz (medido em 2026-09-08) |
+|---|---|
+| `AgentOpenTelemetryConsts.DefaultSourceName` e `agent.WithOpenTelemetry()` | **Nenhum dos dois existe** em `Microsoft.Agents.AI` 1.20.0. A API é `builder.UseOpenTelemetry(sourceName, configure)` sobre `AIAgentBuilder` / `ChatClientBuilder` |
+| `EnableSensitiveTelemetryData` | O símbolo é **`EnableSensitiveData`**, e existe **nos dois** tipos: `OpenTelemetryAgent.EnableSensitiveData` e `OpenTelemetryChatClient.EnableSensitiveData`. Não são dois nomes diferentes: é o **mesmo nome em dois níveis** |
+| *"não use `Experimental.Microsoft.Extensions.AI.*` — é do 9.x"* | São **duas fontes vivas e necessárias**: `Experimental.Microsoft.Agents.AI` (do agente) e `Experimental.Microsoft.Extensions.AI` (do chat e das tools). Quem só registra a primeira perde os spans `chat` e `execute_tool` |
+
+Os dois nomes de `ActivitySource` foram lidos como literais nas assemblies `Microsoft.Agents.AI.dll` 1.20.0 e `Microsoft.Extensions.AI.dll` 10.9.0.
+
 ```csharp
 using OpenTelemetry;
 using OpenTelemetry.Trace;
 using OpenTelemetry.Metrics;
 using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
 
-// Habilitar em agents individuais
-agent.WithOpenTelemetry();
+const string AgentSource = "Experimental.Microsoft.Agents.AI";      // span invoke_agent
+const string ChatSource  = "Experimental.Microsoft.Extensions.AI";  // spans chat e execute_tool
+
+// Instrumentar o AGENTE (span externo). EnableSensitiveData default = false.
+AIAgent instrumented = agent.AsBuilder()
+    .UseOpenTelemetry(sourceName: AgentSource, configure: o => o.EnableSensitiveData = false)
+    .Build();
 
 // Program.cs — setup completo
 builder.Services.AddOpenTelemetry()
     .WithTracing(tracing =>
     {
-        tracing.AddSource(AgentOpenTelemetryConsts.DefaultSourceName);   // MAF 1.0 GA source
-        tracing.AddSource(builder.Environment.ApplicationName);          // seus spans customizados (ver Enrichment)
+        tracing.AddSource(AgentSource);                             // sem isto: nenhum invoke_agent
+        tracing.AddSource(ChatSource);                              // sem isto: nenhum chat / execute_tool
+        tracing.AddSource(builder.Environment.ApplicationName);     // seus spans customizados (ver Enrichment)
         tracing.AddAspNetCoreInstrumentation();
         tracing.AddHttpClientInstrumentation();
         tracing.AddOtlpExporter();
     })
     .WithMetrics(metrics =>
     {
-        metrics.AddMeter(AgentOpenTelemetryConsts.DefaultSourceName);
+        metrics.AddMeter(ChatSource);                               // as métricas gen_ai.client.* saem daqui
         metrics.AddAspNetCoreInstrumentation();
         metrics.AddHttpClientInstrumentation();
         metrics.AddRuntimeInstrumentation();
@@ -52,9 +69,99 @@ builder.Logging.AddOpenTelemetry(logging =>
 });
 ```
 
-> **Source name:** sempre `AgentOpenTelemetryConsts.DefaultSourceName` de `Microsoft.Agents.AI`.
-> **NÃO usar** o source string `"Experimental.[pacote-antigo].*"` — pertence à família `Microsoft.Extensions.AI` 9.x, incompatível com MAF 1.0 GA.
-> **Produção:** desabilite dados sensíveis — `EnableSensitiveTelemetryData = false` no agent — para não vazar prompt/response completos no backend de export.
+> **Produção:** `EnableSensitiveData = false` (é o default nos dois níveis) para não vazar prompt/response completos no backend de export.
+
+### A regra de duplicação — um NÍVEL, uma instrumentação
+
+A mudança de **1.6.1** (2026-05-14) foi o `OpenTelemetryAgent` passar a **auto-encapsular** o chat client com um `OpenTelemetryChatClient` no pipeline que o `ChatClientAgent` monta sozinho. Daí saiu a regra folclórica *"instrumente o agente **ou** o chat client, nunca os dois"* — que é **imprecisa**, e a diferença muda o que se escreve.
+
+**O que foi medido no pin** (`Morph.AiKit.Tests/TelemetryTests.cs`, contra `Microsoft.Agents.AI` 1.20.0):
+
+- Uma invocação instrumentada produz **`invoke_agent` (raiz) + `chat` (filho)**. Instrumentar os **dois níveis** é o caminho normal, e **não** duplica nada — o teste `AnInstrumentedAgentEmitsOneInvokeAgentSpanAndOneChatSpan` pina isso.
+- O que duplica é **duas camadas no MESMO nível**: dois `OpenTelemetryChatClient` dão dois `chat`; dois `OpenTelemetryAgent` dão dois `invoke_agent` (`ForcingInstrumentChatClientProducesTheDuplicateChatSpan`).
+- O guard do MAF **só alcança o pipeline que o `ChatClientAgent` monta sozinho**. Quem monta o próprio pipeline (`ChatClientAgentOptions.UseProvidedChatClientAsIs = true`, necessário para posicionar middleware de custo ou ajustar tool calling) **perde** esse slot: medido, agente instrumentado + pipeline próprio sem instrumentação de chat = **zero** spans de chat.
+
+**A regra correta, então, é em duas linhas:**
+
+1. **Instrumente cada nível no máximo uma vez.** O predicado é respondível, não um palpite: `inner.GetService(typeof(OpenTelemetryChatClient))` / `typeof(OpenTelemetryAgent)` atravessa a cadeia de delegates.
+2. **Com pipeline próprio, a instrumentação de chat é obrigatória** — não é um extra opcional, é a única coisa que produz o span `chat`.
+
+```csharp
+// O guard, na forma que o ai-kit compila: nulo = instrumenta só o que ainda não está.
+builder.Use(inner => inner.GetService(typeof(OpenTelemetryChatClient)) is null
+    ? new OpenTelemetryChatClient(inner, logger: null, sourceName: ChatSource) { EnableSensitiveData = false }
+    : inner);
+```
+
+**Onde o span de chat fica no pipeline:** **abaixo** do `FunctionInvokingChatClient`. É assim que o span `chat` fecha antes das tools e o `invoke_agent` fica sendo a raiz. Ver a ordem completa do pipeline em `ai-agents-middleware-patterns`.
+
+### Nomes de span, métricas e atributos — medidos
+
+| O que | Nome | Onde foi medido |
+|---|---|---|
+| Span do agente | `invoke_agent` | literal em `Microsoft.Agents.AI.dll` 1.20.0 |
+| Span do modelo | operação + modelo (`gen_ai.operation.name` + `gen_ai.request.model`) | `Microsoft.Extensions.AI.dll` 10.9.0 |
+| Span de tool | `execute_tool` | `Microsoft.Extensions.AI.dll` 10.9.0 |
+| Métrica de duração | `gen_ai.client.operation.duration` | idem |
+| Métrica de tokens | `gen_ai.client.token.usage` | idem |
+| Métricas extras | `gen_ai.client.operation.exception`, `gen_ai.client.operation.time_per_output_chunk` | idem |
+| Atributos do agente | `gen_ai.agent.id`, `gen_ai.agent.name`, `gen_ai.agent.description`, `gen_ai.provider.name` | `Microsoft.Agents.AI.dll` 1.20.0 |
+
+A coluna "onde foi medido" nomeia **uma** assembly onde o literal ocorre, e **não** afirma
+exclusividade. A distribuição completa, medida por exclusividade sobre **todas** as assemblies
+restauradas do pin (`probe.mjs tags`, 2026-09-09) — repare que ela **não se limita às duas** que esta
+página nomeia:
+
+| Nome | Assemblies onde o literal ocorre |
+|---|---|
+| `invoke_agent` | `Microsoft.Agents.AI` **e** `Microsoft.Extensions.AI` |
+| `execute_tool` | `Microsoft.Extensions.AI` **e** `ModelContextProtocol.Core` |
+| `gen_ai.agent.id`, `gen_ai.agent.name`, `gen_ai.agent.description` | **só** `Microsoft.Agents.AI` |
+| `gen_ai.provider.name` | `Microsoft.Agents.AI` **e** `Microsoft.Extensions.AI` |
+| `gen_ai.operation.name` | `Microsoft.Agents.AI`, `Microsoft.Extensions.AI`, `ModelContextProtocol.Core` **e** `OpenAI` |
+| `gen_ai.request.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.response.finish_reasons`, `gen_ai.client.operation.duration`, `gen_ai.client.token.usage` | `Microsoft.Extensions.AI` **e** `OpenAI` |
+| `gen_ai.client.operation.exception`, `gen_ai.client.operation.time_per_output_chunk` | **só** `Microsoft.Extensions.AI` |
+
+**Por que isto importa para quem instrumenta:** o mesmo nome emitido por camadas diferentes é o que
+produz span duplicado — e é a razão de este standard começar pelo guard de "um nível, uma
+instrumentação". `OpenAI` e `ModelContextProtocol.Core` estão sob o **mesmo pin** e carregam parte
+destes nomes; se você registrar a fonte deles junto com a do agente sem o guard, o atributo chega
+duas vezes com procedências diferentes.
+
+> **Duas afirmações que NÃO se confirmaram, e por isso não estão acima.** `agent_framework.function.invocation.duration` e a variável de ambiente `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` **não aparecem** em nenhuma das quatro assemblies do pin (`Microsoft.Agents.AI`, `.Abstractions`, `Microsoft.Extensions.AI`, `.Abstractions`), varridas por literal em 2026-09-08. A duração de invocação de função pode existir noutro pacote, e a variável é do SDK do OpenTelemetry, não destes pacotes — em nenhum dos dois casos este standard as prescreve sem fonte.
+
+### Estabilidade da convenção GenAI — a ressalva que muda como ler a tabela acima
+
+Os nomes acima são **medidos nas assemblies do pin**, e continuam corretos. O que não é estável é a
+**convenção** que eles implementam, e um standard que manda instrumentar sem dizer isso está mandando
+pintar alvo num muro que se move.
+
+Os fatos, apurados em 2026-09-08:
+
+- As **GenAI semantic conventions saíram do repositório principal** do OpenTelemetry. A versão
+  **1.42.0 do semconv (2026-06-12)** depreciou e moveu todo o namespace `gen_ai.*`; a **1.43.0
+  (2026-07-03)** não traz nenhum.
+- O conteúdo passou a viver em `open-telemetry/semantic-conventions-genai`, e ali **nenhum** span,
+  evento, métrica ou atributo GenAI está marcado `Stable` — todos estão em `Development`. Os únicos
+  estáveis no conjunto são `error.type`, `server.address` e `server.port`, que são **atributos
+  comuns**, não GenAI.
+- Enquanto isso, o `OpenTelemetryChatClient` do `Microsoft.Extensions.AI` declara implementar a
+  **v1.37** — ou seja, a versão implementada está **atrás** do split.
+
+**O que isso implica na prática, e é o que se leva daqui:**
+
+| Implicação | O que fazer |
+|---|---|
+| Nome de atributo `gen_ai.*` pode mudar entre versões do pacote | Não construa alerta cujo único identificador seja um nome `gen_ai.*` sem um plano de renomeação |
+| A versão implementada pelo pacote **não** é a última da convenção | Ao subir o pin, confira a tabela de nomes acima em vez de assumir continuidade |
+| Painel montado sobre o namespace instável envelhece com o pacote | Vale a pena manter uma camada própria de nomes (`morph.*`) para o que o time consulta todo dia |
+
+Isto **não** é motivo para não instrumentar. É motivo para instrumentar sabendo que os nomes são de
+uma convenção em desenvolvimento, e para não tratar uma renomeação futura como incidente.
+
+### Limitação conhecida, em aberto
+
+Issue **3637** do `microsoft/agent-framework`: o `UseOpenTelemetry()` do .NET **não emite `ActivityEvent`s** conforme a spec de eventos GenAI — o conteúdo de mensagem viaja como atributo, não como evento. Estado em 2026-09-08: **aberta**. Consequência prática: um backend que monta a conversa a partir de *events* GenAI mostra spans sem mensagens. Não é bug do seu wiring.
 
 ### Aspire Dashboard (dev/local)
 
@@ -81,12 +188,54 @@ Sem um `correlation_id` propagado manualmente através de chamadas assíncronas/
 
 ```csharp
 activity?.SetTag("gen_ai.request.model", modelAlias);       // alias do Model Registry, nunca o nome hardcoded
-activity?.SetTag("gen_ai.usage.prompt_tokens", usage.PromptTokens);
-activity?.SetTag("gen_ai.usage.completion_tokens", usage.CompletionTokens);
-activity?.SetTag("gen_ai.response.finish_reason", finishReason);
+activity?.SetTag("gen_ai.usage.input_tokens", usage.InputTokenCount);
+activity?.SetTag("gen_ai.usage.output_tokens", usage.OutputTokenCount);
+activity?.SetTag("gen_ai.response.finish_reasons", finishReasons);   // PLURAL — o singular não existe no pin
 ```
 
-Nomeação `gen_ai.*` segue a convenção semântica OpenTelemetry para GenAI — mantém compatibilidade se o backend de observability tiver dashboards prontos para essa convenção.
+> **Correção de 2026-09-09 (duas passadas), medida por reflexão e por literal nas assemblies do
+> pin. As QUATRO linhas acima foram conferidas, uma a uma** — a primeira passada corrigiu duas e
+> deixou uma errada no mesmo bloco, que é a razão de este callout listar todas em vez de só as que
+> mudaram.
+>
+> | Tag / símbolo | Veredito | Como |
+> |---|---|---|
+> | `gen_ai.request.model` | **existe** | 2 ocorrências autônomas; **distribuição por assembly na tabela da seção _Nomes de span, métricas e atributos — medidos_** — não é exclusivo de uma |
+> | `gen_ai.usage.input_tokens` | **existe** | 2 autônomas; distribuição na tabela citada acima |
+> | `gen_ai.usage.output_tokens` | **existe** | 2 autônomas; distribuição na tabela citada acima |
+> | `gen_ai.response.finish_reasons` (a linha acima, no **plural**) | **existe** | 2 autônomas; distribuição na tabela citada acima |
+> | `gen_ai.response.finish_reason` (o **singular**, que estava aqui) | **NÃO existe** | as **mesmas** 2 ocorrências do plural, **nenhuma autônoma**: o singular é a cabeça de `finish_reason`**s** |
+> | `usage.PromptTokens` / `CompletionTokens` | **NÃO existem** | 0 ocorrências autônomas em assembly restaurada nenhuma |
+> | `gen_ai.usage.prompt_tokens` / `completion_tokens` | **NÃO existem** | 0 ocorrências autônomas em assembly restaurada nenhuma |
+>
+> O que existe no lugar dos dois últimos é `InputTokenCount` / `OutputTokenCount`, propriedades de
+> `UsageDetails` — que vive na assembly **`Microsoft.Extensions.AI.Abstractions` 10.9.0** (que viaja dentro do pacote `Microsoft.Extensions.AI`, e não é id de pacote do pin), e não na assembly
+> que carrega os literais. E **"a assembly que carrega os literais" não é uma só** — a distribuição
+> completa, por nome, está na tabela da seção *Nomes de span, métricas e atributos — medidos*, e **esta linha não a
+> repete**: uma segunda tabela dos mesmos nomes foi escrita aqui na rodada 5 e **contradizia** a
+> primeira (dizia "só em `Microsoft.Extensions.AI`" para seis literais que também vivem em `OpenAI`),
+> justamente por invocá-la como autoridade sem relê-la. Duas cópias do mesmo fato divergem; a
+> segunda foi removida.
+>
+> Faz sentido: quem **emite** o span de chamada de modelo é `OpenTelemetryChatClient`
+> (`Microsoft.Extensions.AI` 10.9.0); quem descreve o **agente** é a camada de agente. Os nomes
+> velhos eram da convenção **anterior** à renomeação do semconv. Código copiado daqui não compilava,
+> e a tag emitida não casaria com nenhum painel montado sobre a convenção atual.
+>
+> **O método importa tanto quanto o resultado:** `finish_reason` sobreviveu a duas varreduras porque
+> as duas usaram `includes(literal)`, e **`includes` de um prefixo não prova o literal autônomo** —
+> o singular casa dentro do plural. A conferência acima é por **exclusividade**: cada ocorrência é
+> aceita só se o caractere anterior e o seguinte não forem `[A-Za-z0-9_.-]`. Literais de string .NET
+> vivem no heap `#US` em **UTF-16**; a varredura cobre `#US` (UTF-16) e `#Strings` (ASCII).
+
+Nomeação `gen_ai.*` segue a convenção semântica OpenTelemetry para GenAI — mantém compatibilidade se o backend de observability tiver dashboards prontos para essa convenção. Sobre a **instabilidade** dessa convenção, ver a ressalva na seção de Setup.
+
+> **Tokens ficam aqui; dinheiro não.** A **tarifa** por alias (com data de verificação), o **cálculo**
+> do custo (e as três armadilhas de fórmula: raciocínio cobrado como saída, entrada cacheada como
+> subconjunto da entrada, taxa fixa de operação hospedada), o estado de um custo
+> (`Computed`/`Waived`/`UsageMissing`, e por que `cost_usd` nunca é nulo) e o **teto de orçamento**
+> têm **tratamento canônico** em **`ai-agents-cost-and-budget`**. Não duplicado aqui. A delegação é
+> de mão dupla: aquele standard aponta de volta para esta seção quando o assunto é atributo de span.
 
 ### Logging estruturado com `ILogger` — sempre com scope
 
@@ -105,11 +254,57 @@ using (_logger.BeginScope(new Dictionary<string, object>
 ```
 
 - **Sempre** parâmetros nomeados no template (`{ToolName}`, não string interpolada) — permite querying estruturado no backend em vez de grep de texto livre.
-- **Nunca** logar o conteúdo completo do prompt/response em `Information` — isso é PII/dado sensível do cliente por padrão. Logar em `Debug` apenas, e só se `EnableSensitiveTelemetryData` estiver habilitado explicitamente para o ambiente.
+- **Nunca** logar o conteúdo completo do prompt/response em `Information` — isso é PII/dado sensível do cliente por padrão. Logar em `Debug` apenas, e só se `EnableSensitiveData` estiver habilitado explicitamente para o ambiente.
 - **Nível de log por tipo de evento:** `Information` para início/fim de tool call e decisões do agent; `Warning` para retry/fallback de provider; `Error` apenas para falhas que geram resposta degradada ao usuário (não para toda exceção capturada e tratada).
 
 ---
 
+## Rastreabilidade do que foi ao provedor
+
+A pergunta que a instrumentação existe para responder depois de um incidente é uma só: **dá para
+reconstruir o que foi enviado ao provedor, e o que ele respondeu, neste turno?**
+
+**A regra: prompt cru no harness; hash em produção.**
+
+| Ambiente | O que se registra | Por quê |
+|---|---|---|
+| Dev e harness | O texto enviado, com **opt-in explícito** e sem dado pessoal | É onde se depura; o custo de vazamento é controlado |
+| Produção | O **hash** do texto enviado (e, quando o prompt é composto de blocos, um hash por bloco) | Um prompt cru persistido em produção é um vazamento esperando indexação. O hash responde "foi o mesmo texto?" sem guardar o texto |
+
+Isso é a mesma chave que `EnableSensitiveData = false` fora de dev já protege — e o hash é o que
+sobra de útil depois de desligá-la.
+
+### A invariante que torna o hash confiável
+
+Um hash só prova alguma coisa se o texto de que ele é hash **é** o texto que foi enviado. Isso deixa
+de valer no instante em que existe um cache entre a montagem e o envio: a partir dali, telemetria e
+requisição podem divergir, e a divergência é silenciosa.
+
+Por isso a exigência é do lado de quem monta o prompt, não de quem o registra: **o texto enviado é
+derivado dos blocos, sem cache**. É uma invariante deliberadamente cara, e a razão está escrita no
+código de campo que a implementa — *"para a telemetria não poder mentir"*. O tratamento canônico
+está em `ai-agents-conversational-agent-with-phases`, seção do compositor de turno.
+
+**Duas asserções que fecham o ciclo**, e ambas são de teste, não de wiring:
+
+- A lista de tools **ofertadas** saiu da lista real do turno, e não de uma constante paralela.
+- **Turno cancelado não grava** — um registro de algo que não aconteceu é pior que a ausência dele.
+
+A metade de harness deste assunto (o que o fake captura, e como assertar sobre isso) é de
+`ai-agents-testing-ai`. O veredito ternário e o escape registrado, que são o que torna um guard
+auditável pela mesma via, são de `ai-agents-guardrails`.
+
+> **O que o Gate 3 procura.** Os nomes concretos — `ActivitySource`, spans, métricas e atributos
+> requeridos — estão medidos na tabela **"Nomes de span, métricas e atributos — medidos"** acima, e
+> **não** são repetidos aqui: uma segunda lista dos mesmos nomes é a segunda verdade nascendo. A
+> régua de avaliação correspondente vive em
+> `.morph/framework/evals/proof-rubrics/observabilidade-genai.md`, e ela pergunta a **propriedade**
+> desta seção (dá para reconstruir o turno?), não a tecnologia — porque uma régua binária "tem span?"
+> daria a mesma nota a quem tem só a mensagem da exceção e a quem tem hash por bloco de prompt com
+> teste de fidelidade.
+
+---
+
 ## Investigação e análise — quando algo dá errado
 
 Workflow para diagnosticar um incidente relatado ("o agente X respondeu errado/lento/nada às HH:MM"):
@@ -134,12 +329,20 @@ Workflow para diagnosticar um incidente relatado ("o agente X respondeu errado/l
 
 ## Checklist (verifiable by morph-eval)
 
-- [ ] OpenTelemetry configurado com `AgentOpenTelemetryConsts.DefaultSourceName` (traces + metrics + logging)
-- [ ] `EnableSensitiveTelemetryData = false` fora de dev/staging
+- [ ] `AddSource` das **duas** fontes: `Experimental.Microsoft.Agents.AI` e `Experimental.Microsoft.Extensions.AI`
+- [ ] Nenhuma referência a `AgentOpenTelemetryConsts` ou `agent.WithOpenTelemetry()` (não existem no pin)
+- [ ] `EnableSensitiveData = false` fora de dev/staging (é o default — confirme que ninguém ligou)
+- [ ] Cada nível instrumentado **no máximo uma vez**; com `UseProvidedChatClientAsIs = true`, a instrumentação de chat está explicitamente presente
+- [ ] Um teste conta os spans de uma invocação: exatamente um `invoke_agent` e um `chat`
 - [ ] Todo tool call relevante tem `correlation_id` propagado manualmente através de boundaries assíncronos (filas, background jobs)
 - [ ] Logging via `ILogger` com `BeginScope` estruturado, nunca string interpolada em templates de log
 - [ ] Nenhum log em `Information`/produção contém prompt/response completo
 - [ ] Alertas configurados para os thresholds da tabela "What to Monitor" relevantes ao projeto
+- [ ] Nenhum alerta depende de um nome `gen_ai.*` como identificador único sem plano de renomeação (a convenção está em `Development`, não `Stable`)
+- [ ] Em produção, o que foi ao provedor é reconstituível por **hash**; prompt cru só em dev/harness, com opt-in
+- [ ] O texto enviado é derivado dos blocos **sem cache** — sem isso o hash não prova nada
+- [ ] Há asserção de que a lista de tools ofertadas saiu da lista real do turno
+- [ ] Turno cancelado **não** grava telemetria
 
 ---
 
@@ -147,10 +350,17 @@ Workflow para diagnosticar um incidente relatado ("o agente X respondeu errado/l
 
 - `ai-agents-production` — panorama de produção; esta seção era resumida lá, tratamento canônico agora aqui
 - `ai-agents-middleware-patterns` — middleware de telemetria no nível `IChatClient` (`TelemetryMiddleware`)
+- `ai-agents-cost-and-budget` — tarifa, cálculo de custo e teto de orçamento (delegação recíproca: tokens ficam aqui, dinheiro fica lá)
+- `ai-agents-conversational-agent-with-phases` — o compositor de turno e a invariante "derivado sem cache" que torna o hash confiável
+- `ai-agents-testing-ai` — a metade de harness da rastreabilidade (captura do fake, prompt cru com opt-in)
+- `ai-agents-guardrails` — veredito ternário e escape registrado, auditáveis pela mesma telemetria
+- `.morph/framework/evals/proof-rubrics/observabilidade-genai.md` — a régua do Gate 3 para a propriedade desta seção
 - `infrastructure-docker-coolify-deploy` — Serilog/JSON console log para o pipeline de agregação em produção
+- Reference implementation (compila e conta spans contra o pin): `templates/dotnet/ai-kit/src/Morph.AiKit/Observability/MorphOpenTelemetryExtensions.cs` + `tests/Morph.AiKit.Tests/TelemetryTests.cs`
 - [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
 - [Agent Observability](https://learn.microsoft.com/agent-framework/user-guide/observability/)
+- Issue aberta `microsoft/agent-framework#3637` — `ActivityEvent`s da spec GenAI não emitidos (estado em 2026-09-08: **aberta**)
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/observability-patterns.md v1.0 (2026-07-22)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/observability-patterns.md v2.0 (2026-09-08)*

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

@@ -5,7 +5,7 @@
 > **Keywords:** middleware, observability, telemetry, mcp, a2a, caching, anti-hallucination, production agent
 > **Read by Claude in:** implement (when wiring middleware/telemetry/MCP into an agent)
 
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+**Verified against:** Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08) + Microsoft.Agents.AI.Hosting `1.20.0-preview.260831.1` e Microsoft.Agents.AI.A2A `1.20.0-preview.260831.1` (**fora do pin**; versões apuradas no nuget.org em 2026-09-08). **Verificação documental**, sem cláusula `provado por` — este standard é panorama, e cada tema tem dono canônico noutro standard. Os nomes de isolamento multi-tenant foram **medidos por reflexão sobre `Microsoft.Agents.AI.Hosting`** em 2026-09-08. Last-verified: 2026-09-08.
 
 ---
 
@@ -33,12 +33,15 @@ e os patterns de telemetria, resilência (retry + rate-limit) e anti-hallucinati
 
 Exponha agents como serviços web interoperáveis via protocolo A2A padronizado.
 
-**Package (GA):**
+**Package — PRERELEASE, e fora do `ai-pin.json`:**
 
 ```xml
-<PackageReference Include="Microsoft.Agents.AI.A2A" Version="1.0.*" />
+<!-- Apurado no nuget.org em 2026-09-08: não há versão estável de Microsoft.Agents.AI.A2A. -->
+<PackageReference Include="Microsoft.Agents.AI.A2A" Version="1.20.0-preview.260831.1" />
 ```
 
+> **Correção de 2026-09-08:** a versão anterior deste standard rotulava o A2A como **GA** com faixa `1.0.*`. Nenhuma das duas coisas se sustenta: o pacote nunca teve versão estável, e faixa flutuante num SDK de cadência semanal é o defeito que `ai-agents-setup` §1 proíbe.
+
 ### Expor um agent via A2A
 
 ```csharp
@@ -181,7 +184,30 @@ public async Task<WeatherResponse> GetWeatherAsync(
 
 Setup, enrichment (span attributes, correlation IDs, structured logging) e o workflow de investigação/análise de logs em produção têm **tratamento canônico** em **`ai-agents-observability-patterns`**. Não duplicado aqui.
 
-> Em produção: source name sempre `AgentOpenTelemetryConsts.DefaultSourceName`; `EnableSensitiveTelemetryData = false` fora de dev/staging. Ver `ai-agents-observability-patterns` para o setup completo, o que preencher em cada span/log, e o workflow de investigação quando um incidente for reportado.
+> Em produção: `AddSource` das **duas** fontes — `Experimental.Microsoft.Agents.AI` e `Experimental.Microsoft.Extensions.AI` — e `EnableSensitiveData = false` fora de dev/staging. (Correção de 2026-09-08: `AgentOpenTelemetryConsts` e `EnableSensitiveTelemetryData` **não existem** no pin; medido.) Ver `ai-agents-observability-patterns` para o setup completo, o que preencher em cada span/log, e o workflow de investigação quando um incidente for reportado.
+
+---
+
+## Isolamento multi-tenant — renomeado em 1.18
+
+Um agente registrado como singleton atende todos os tenants. O que separa um do outro não é o agente: é a **chave de isolamento** que decide de qual balde vem a sessão.
+
+Na **1.18** (2026-08-18) essa superfície foi renomeada. Nomes atuais, medidos por reflexão sobre `Microsoft.Agents.AI.Hosting` (pacote `1.20.0-preview.260831.1`) em 2026-09-08:
+
+| Tipo | Papel |
+|---|---|
+| `Microsoft.Agents.AI.Hosting.AgentIsolationKeyProvider` | Produz a chave de isolamento do request corrente |
+| `Microsoft.Agents.AI.Hosting.IsolationKeyScopedAgentSessionStore` | O `AgentSessionStore` que aplica a chave; tem `IsolationKeyScopedAgentSessionStoreOptions` |
+| `UseClaimsBasedAgentIsolation()` (ASP.NET Core) | Deriva a chave das claims do usuário autenticado |
+
+**Duas advertências que valem mais que os nomes:**
+
+1. **O pacote é prerelease.** `Microsoft.Agents.AI.Hosting` não tem versão estável (apurado 2026-09-08). Isolamento multi-tenant por esse caminho é adoção de preview — registre em `decisions.md`.
+2. **A chave vem da credencial, nunca do payload.** Uma chave derivada de algo que o cliente envia é uma chave que o cliente escolhe. `UseClaimsBasedAgentIsolation()` existe exatamente para não deixar essa decisão passar pelo corpo do request.
+
+### Invocação concorrente de tools é opt-in desde 1.18
+
+`FunctionInvokingChatClient.AllowConcurrentInvocation` (exposto como `ChatClientAgentOptions.AllowConcurrentInvocation`) tem default **`false`**: numa volta com várias chamadas de tool, elas rodam **em sequência**. Ligar a concorrência é decisão explícita — e só é segura se **todas** as tools daquele agente forem thread-safe. Um `DbContext` do EF Core **não** é: duas tools concorrentes sobre o mesmo `DbContext` scoped produzem `InvalidOperationException` intermitente sob carga, que é o pior formato possível de bug.
 
 ---
 
@@ -194,18 +220,21 @@ Setup, enrichment (span attributes, correlation IDs, structured logging) e o wor
 - [ ] Rate limiting middleware em agents expostos publicamente
 - [ ] Endpoints A2A protegidos com autenticação
 - [ ] Structured output usado para respostas — evita parsing de texto livre
-- [ ] OpenTelemetry com `AgentOpenTelemetryConsts.DefaultSourceName` configurado
+- [ ] OpenTelemetry com `AddSource` das duas fontes `Experimental.Microsoft.*` configurado
+- [ ] Multi-tenant: a chave de isolamento vem da credencial (claims), nunca do payload do request
 
 ---
 
 ## Production Checklist (verifiable by morph-eval)
 
-- [ ] `Microsoft.Agents.AI` 1.0.* no `.csproj`; nenhum pacote `Experimental.*` ou SK
+- [ ] `Microsoft.Agents.AI` **1.20.0** (versão exata, do `ai-pin.json`) no `.csproj`; nenhum pacote SK de orquestração
+- [ ] Nenhum `PackageReference` de SDK de IA com faixa flutuante; pacote fora do pin com versão exata + data de apuração
+- [ ] `AllowConcurrentInvocation` continua `false`, ou todas as tools do agente são comprovadamente thread-safe
 - [ ] Middleware registrado via `.AsBuilder().Use(...)` antes de `Build()`
 - [ ] `ResilientToolMiddleware` (ou equivalente) em agents que chamam APIs externas
 - [ ] Semantic cache configurado se o agent recebe queries repetitivas
-- [ ] OpenTelemetry source = `AgentOpenTelemetryConsts.DefaultSourceName`
-- [ ] Dados sensíveis de telemetry desabilitados em produção (`EnableSensitiveTelemetryData = false`)
+- [ ] OpenTelemetry source = `Experimental.Microsoft.Agents.AI` **e** `Experimental.Microsoft.Extensions.AI`
+- [ ] Dados sensíveis de telemetry desabilitados em produção (`EnableSensitiveData = false`)
 - [ ] A2A endpoints com `MapA2A` protegidos por auth se expostos na internet
 - [ ] MCP client `await using` para dispose correto do transporte
 
@@ -228,4 +257,4 @@ Setup, enrichment (span attributes, correlation IDs, structured logging) e o wor
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/production.md v2.1 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/production.md v3.0 (2026-09-08)*