@polymorphism-tech/morph-spec 6.0.0 → 7.1.0

package/framework/standards/ai-agents/mcp-server.md

@@ -0,0 +1,250 @@
+# MCP Server — Exposing project capabilities as MCP
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** mcp server, expose mcp, build mcp server, mcp host, publish tools, McpServerTool, AddMcpServer
+> **Read by Claude in:** implement (quando um projeto expõe capacidades como MCP server para consumo externo)
+
+**Verified against:** MAF 1.0 GA + ModelContextProtocol C# SDK server-side (`[McpServerToolType]`/`[McpServerTool]`, `WithStdioServerTransport`/`WithHttpTransport`, `ModelContextProtocol.AspNetCore`). Last-verified: 2026-05-19.
+
+---
+
+## Quando criar um MCP server
+
+Crie um MCP server quando você quer **expor capacidades do projeto** de forma padronizada para **agentes ou ferramentas externas** consumirem. O protocolo MCP garante interoperabilidade: qualquer agente compatível (Claude Code, outro agent MAF, VS Code Copilot, etc.) pode descobrir e usar as tools do servidor.
+
+**Crie um MCP server quando:**
+
+- Claude Code (ou outro agente externo) precisa executar queries/ações neste projeto
+- Outro projeto MAF precisa consumir lógica encapsulada aqui via protocolo padrão
+- Você quer expor capacidades de negócio de forma descobrível via `ListTools`
+- O projeto é um serviço de infraestrutura que deve ser consumível cross-framework
+
+**NÃO crie um MCP server quando:**
+
+- As tools são usadas apenas pelos agentes do próprio projeto → use tools nativas `[Description]`
+- É uma lógica de um único endpoint interno → `AIFunctionFactory.Create()` é suficiente
+- A integração é ponto-a-ponto com um único consumidor → DI direta ou A2A é mais simples
+
+---
+
+## A API
+
+**Packages:**
+
+```xml
+<!-- SDK cliente+servidor do protocolo MCP -->
+<PackageReference Include="ModelContextProtocol" Version="0.1.*" />
+
+<!-- Pacote base MAF (para AsAIAgent, AsAIFunction) -->
+<PackageReference Include="Microsoft.Agents.AI" Version="1.0.*" />
+
+<!-- Apenas se o transporte for HTTP (server-side) -->
+<PackageReference Include="ModelContextProtocol.AspNetCore" Version="0.1.*" />
+```
+
+> `ModelContextProtocol` versão 0.1.* (preview) — GA previsto. Verifique versão corrente no NuGet antes de travar.
+
+**Dois jeitos de declarar tools:**
+
+| Padrão | Quando usar |
+|--------|-------------|
+| Atributos `[McpServerToolType]` + `[McpServerTool]` | Tools são métodos estáticos do projeto — padrão canônico do SDK. Descoberta automática via `WithToolsFromAssembly()`. |
+| `McpServerTool.Create(...)` | Embrulhar um agente MAF (`agent.AsAIFunction()`) ou um `AIFunction` construído em runtime como tool. |
+
+**Padrão de servidor (stdio):**
+
+```
+Tools ([McpServerTool] ou McpServerTool.Create)
+    → services.AddMcpServer()            // registra o servidor
+    → .WithStdioServerTransport()        // transporte: stdio (Claude Code, subprocesso)
+    → .WithToolsFromAssembly()           // descobre [McpServerTool] no assembly
+       ou .WithTools([tool])             // registra tools criadas em runtime
+    → Host.Build().RunAsync()            // sobe o servidor
+```
+
+**Transport stdio** é o padrão para servidores locais (subprocessos, Claude Code tools). **HTTP server-side** usa o pacote `ModelContextProtocol.AspNetCore`: troque `WithStdioServerTransport()` por `WithHttpTransport(o => o.Stateless = true)` e exponha o endpoint com `app.MapMcp()` num `WebApplication`.
+
+---
+
+## Exemplo C# — tools por atributo (stdio)
+
+Padrão canônico: tools são métodos estáticos decorados, descobertos por assembly.
+
+```csharp
+using System.ComponentModel;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using ModelContextProtocol.Server;
+
+HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
+
+builder.Services
+    .AddMcpServer()
+    .WithStdioServerTransport()    // stdio: Claude Code / subprocesso
+    .WithToolsFromAssembly();      // descobre [McpServerToolType] neste assembly
+
+await builder.Build().RunAsync();
+
+// ─── Tool exposta via atributo ──────────────────────────────────────────────
+[McpServerToolType]
+public static class OrderTools
+{
+    [McpServerTool, Description("Returns the current status of an order given its ID")]
+    public static async Task<string> GetOrderStatus(
+        [Description("The order identifier")] string orderId,
+        CancellationToken ct)
+    {
+        // Validação de input antes de qualquer I/O — ver seção Segurança
+        if (string.IsNullOrWhiteSpace(orderId) || orderId.Length > 36)
+            return "Error: invalid orderId format.";
+
+        // lógica real do projeto aqui
+        return $"Order {orderId}: Confirmed";
+    }
+}
+```
+
+> Tools por atributo podem ser instância (não-estáticas) — nesse caso o tipo é resolvido via DI,
+> permitindo injetar repositories/serviços no construtor. Métodos estáticos são o caso mais simples.
+
+## Exemplo C# — agente MAF como tool (runtime)
+
+Quando a tool é um agente MAF, use `McpServerTool.Create` com `agent.AsAIFunction()`:
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using ModelContextProtocol.Server;
+
+// _modelRegistry vem de ModelRegistry injetado (ai-agents-providers-model-registry)
+AIAgent queryAgent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(
+        instructions: "You answer questions about project data using the available tools.",
+        name: "ProjectQueryAgent");
+
+McpServerTool agentTool = McpServerTool.Create(queryAgent.AsAIFunction());
+
+HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
+
+builder.Services
+    .AddMcpServer()
+    .WithStdioServerTransport()
+    .WithTools([agentTool]);       // tool criada em runtime → WithTools, não WithToolsFromAssembly
+
+await builder.Build().RunAsync();
+```
+
+## Exemplo C# — transport HTTP
+
+Para expor o MCP server via HTTP (consumível pela rede), use `ModelContextProtocol.AspNetCore`:
+
+```csharp
+using ModelContextProtocol.Server;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services
+    .AddMcpServer()
+    .WithHttpTransport(options => options.Stateless = true)  // stateless: escalável
+    .WithToolsFromAssembly();
+
+var app = builder.Build();
+
+app.MapMcp();   // expõe o endpoint MCP (Streamable HTTP)
+app.Run();
+```
+
+> `Stateless = true` é recomendado para servidores que não precisam de requests server-to-client
+> (sampling/elicitation) — escala melhor e dispensa gestão de sessão. Para HTTP em produção,
+> proteja `MapMcp()` com autenticação — ver seção Segurança.
+
+**Registrar no Claude Code (`settings.json` do projeto consumidor):**
+
+```json
+{
+  "mcpServers": {
+    "my-project-tools": {
+      "command": "dotnet",
+      "args": ["run", "--project", "src/MyProject.McpServer"]
+    }
+  }
+}
+```
+
+---
+
+## Tool nativa vs MCP server exposto
+
+| Dimensão | Tool nativa (`[Description]`) | MCP server exposto |
+|----------|------------------------------|--------------------|
+| **Consumidor** | Agentes do próprio projeto | Agentes externos (Claude Code, outros projetos) |
+| **Protocolo** | Chamada direta em processo | Protocolo MCP (stdio ou HTTP) |
+| **Descoberta** | Registro manual no agente | `ListTools` — autodescoberta |
+| **Quando usar** | Lógica interna do projeto | Capacidades que cruzam fronteiras de projeto/processo |
+| **Overhead** | Zero | Processo separado, IPC via stdio/HTTP |
+| **Testabilidade** | Unitária com xUnit/nSubstitute | Requer host em execução ou mock do transport |
+
+**Regra**: se o único consumidor é um agente do próprio projeto → tool nativa. Se o consumidor é externo → MCP server.
+
+---
+
+## Segurança
+
+Um MCP server exposto é uma **superfície de ataque real** — qualquer agente com acesso ao transporte pode invocar suas tools.
+
+**Obrigatório antes de expor:**
+
+- **Validação de input:** valide todos os parâmetros recebidos (IDs, datas, strings livres) antes de executar lógica de negócio. MCP não valida tipos por você.
+- **Escopo mínimo:** exponha apenas as tools necessárias. Não exponha operações de escrita se o consumidor só lê.
+- **Autenticação (HTTP transport):** se usar HTTP, exija bearer token ou API key via header. stdio é implicitamente restrito ao processo pai.
+- **Nunca expor secrets via tools:** tools não devem retornar API keys, tokens, ou dados de configuração interna.
+- **Rate limiting:** se o MCP server for exposto via HTTP em produção, adicione rate limiting na camada de transporte (reverse proxy / middleware ASP.NET).
+
+A validação de input é mostrada inline no exemplo `GetOrderStatus` acima — valide IDs/datas/strings
+**antes de qualquer I/O** e devolva uma mensagem de erro descritiva (o consumidor é um LLM, que
+corrige o argumento na próxima iteração). Para tools por atributo que precisam de repositories,
+prefira o tipo de instância resolvido por DI a métodos estáticos com estado global.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema | Solução |
+|-------------|---------|---------|
+| Criar MCP server para tools que só os agentes do próprio projeto usam | Overhead de processo + IPC sem benefício; mais difícil de testar | Tool nativa `[Description]` + `AIFunctionFactory.Create()` |
+| Expor tools sem validação de input | Agentes externos (ou alucinações de LLM) podem enviar dados malformados | Validar todos os parâmetros antes de qualquer I/O |
+| Tools sem escopo definido — expor tudo "por conveniência" | Superfície de ataque ampla; dificulta manutenção | Expor apenas o necessário; revisar a lista a cada release |
+| HTTP transport sem autenticação | Qualquer processo na rede pode invocar as tools | Bearer token / API key obrigatório em HTTP; stdio é suficiente para uso local |
+| Subir o MCP server no mesmo processo da aplicação principal | Acoplamento; falha no servidor MCP afeta a app | Projeto separado (`MyProject.McpServer`) com entrypoint próprio |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `ModelContextProtocol` e `Microsoft.Agents.AI` no `.csproj`; `ModelContextProtocol.AspNetCore` apenas se HTTP
+- [ ] Tools declaradas via `[McpServerToolType]` + `[McpServerTool]` (estáticas) ou `McpServerTool.Create(...)` (agente MAF / runtime)
+- [ ] `AddMcpServer()` com `WithStdioServerTransport()` (stdio) ou `WithHttpTransport(o => o.Stateless = true)` (HTTP)
+- [ ] `WithToolsFromAssembly()` para tools por atributo, ou `WithTools([...])` para tools de runtime
+- [ ] Entrypoint: `await builder.Build().RunAsync()` (stdio) ou `app.MapMcp(); app.Run()` (HTTP)
+- [ ] Agente criado via `_modelRegistry.GetChatClient("alias").AsAIAgent(...)` — provider-agnostic
+- [ ] Validação de input em todas as tools antes de executar lógica de negócio
+- [ ] Escopo mínimo: apenas tools necessárias para o consumidor externo
+- [ ] HTTP transport (se usado) protegido por autenticação
+- [ ] Nenhum `Guid.NewGuid()` — usar `Guid.CreateVersion7()` se IDs são necessários
+
+---
+
+## References
+
+- `ai-agents-setup` — pacotes base MAF, DI, quick start
+- `ai-agents-mcp-tools` — consumir MCP servers externos em um agente MAF
+- `ai-agents-production` — middleware pipeline, `ResilientToolMiddleware`, segurança
+- [ModelContextProtocol C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)
+- [Expose Agent as MCP Server — MAF docs](https://learn.microsoft.com/en-us/agent-framework/agents/tools/local-mcp-tools)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/mcp-server.md v1.0 (2026-05-19)*

package/framework/standards/ai-agents/mcp-tools.md

@@ -0,0 +1,197 @@
+# MCP Tools — Agent consuming MCP servers
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** mcp, model context protocol, mcp client, consume mcp server, mcp tools, external tools
+> **Read by Claude in:** implement (quando um agente usa tools de um MCP server externo)
+
+**Verified against:** MAF 1.0 GA + ModelContextProtocol C# SDK. Last-verified: 2026-05-19.
+
+---
+
+## O que é (no contexto de um agente MAF)
+
+MCP (Model Context Protocol) é um protocolo aberto que padroniza como um agente expõe e consome tools. Um agente MAF pode se conectar a qualquer **MCP server externo** (GitHub, filesystem, Postgres, ferramentas internas de outro projeto) e usar as tools desse servidor exatamente como se fossem tools nativas — o MAF trata tudo como `AITool`.
+
+Casos de uso típicos:
+
+- Agente de repositório que usa o GitHub MCP server para listar PRs e issues
+- Agente de dados que usa o PostgreSQL MCP server para rodar queries
+- Agente de documentação que usa o filesystem MCP server para ler arquivos locais
+- Agente corporativo que consome um MCP server interno de outro projeto
+
+---
+
+## A API
+
+**Package:**
+
+```xml
+<PackageReference Include="ModelContextProtocol" Version="0.1.*" />
+```
+
+> O pacote `ModelContextProtocol` é o SDK C# oficial do protocolo. Versão 0.1.* (preview) — GA previsto; verifique no NuGet antes de travar versão.
+
+**Fluxo de consumo:**
+
+1. `McpClientFactory.CreateAsync(transport)` — conecta ao MCP server e retorna um client `IDisposable`
+2. `mcpClient.ListToolsAsync()` — descobre as tools disponíveis no servidor
+3. `mcpTools.Cast<AITool>()` — converte para `AITool` (interface do MAF / `Microsoft.Extensions.AI`)
+4. Passa as tools ao agente via `AsAIAgent(..., tools: [.. mcpTools.Cast<AITool>()])`
+
+**Transports suportados:**
+
+| Transport | Classe | Quando usar |
+|-----------|--------|------------|
+| stdio | `StdioClientTransport` | MCP server local (processo filho — `npx`, executável) |
+| HTTP (SSE) | `SseClientTransport` | MCP server remoto via HTTP/SSE |
+
+**Regra importante:** use `await using` no `mcpClient` — o dispose fecha o transporte corretamente.
+
+---
+
+## Exemplo C#
+
+Agente que consome o GitHub MCP server e responde perguntas sobre repositórios:
+
+```csharp
+using ModelContextProtocol;
+using ModelContextProtocol.Client;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// 1. Conectar ao MCP server (GitHub via npx)
+await using var mcpClient = await McpClientFactory.CreateAsync(
+    new StdioClientTransport(new()
+    {
+        Name = "GitHubServer",
+        Command = "npx",
+        Arguments = ["-y", "--verbose", "@modelcontextprotocol/server-github"],
+    }));
+
+// 2. Descobrir as tools do servidor
+var mcpTools = await mcpClient.ListToolsAsync();
+
+// 3. Criar o agente MAF com as MCP tools registradas
+// _modelRegistry vem de IModelRegistry (ai-agents-providers-model-registry)
+AIAgent agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(
+        instructions: "You answer questions about GitHub repositories.",
+        tools: [.. mcpTools.Cast<AITool>()]);
+
+// 4. Usar o agente normalmente
+var response = await agent.RunAsync(
+    "Summarize the last 4 commits to microsoft/agent-framework");
+Console.WriteLine(response.Text);
+```
+
+**Variante com MCP server remoto (HTTP/SSE):**
+
+```csharp
+using ModelContextProtocol.Client;
+
+await using var mcpClient = await McpClientFactory.CreateAsync(
+    new SseClientTransport(new()
+    {
+        Name = "RemoteToolsServer",
+        Uri = new Uri("https://tools.example.com/mcp"),
+    }));
+
+var mcpTools = await mcpClient.ListToolsAsync();
+// Mesmo padrão para criar o agente...
+```
+
+**Múltiplos MCP servers:**
+
+```csharp
+// Conectar a dois servidores e combinar as tools
+await using var githubClient = await McpClientFactory.CreateAsync(
+    new StdioClientTransport(new()
+    {
+        Name = "GitHub",
+        Command = "npx",
+        Arguments = ["-y", "@modelcontextprotocol/server-github"],
+    }));
+
+await using var fsClient = await McpClientFactory.CreateAsync(
+    new StdioClientTransport(new()
+    {
+        Name = "Filesystem",
+        Command = "npx",
+        Arguments = ["-y", "@modelcontextprotocol/server-filesystem", "/repo"],
+    }));
+
+var allTools = (await githubClient.ListToolsAsync())
+    .Concat(await fsClient.ListToolsAsync())
+    .Cast<AITool>()
+    .ToArray();
+
+AIAgent agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(
+        instructions: "You help navigate the codebase.",
+        tools: allTools);
+```
+
+---
+
+## Popular MCP Servers
+
+| Server npm | Propósito |
+|-----------|-----------|
+| `@modelcontextprotocol/server-github` | Repos, issues, PRs do GitHub |
+| `@modelcontextprotocol/server-filesystem` | Operações no sistema de arquivos |
+| `@modelcontextprotocol/server-sqlite` | Acesso a banco de dados SQLite |
+| `@modelcontextprotocol/server-postgres` | Acesso a banco de dados PostgreSQL |
+
+---
+
+## MCP server vs tool nativa
+
+| Cenário | Decisão | Motivo |
+|---------|---------|--------|
+| O servidor existe e é mantido por terceiros (GitHub, Postgres...) | Consumir MCP server | Reutilização imediata; sem esforço de manutenção |
+| A lógica é específica deste projeto (ex.: buscar pedido no banco) | Escrever tool nativa `[Description]` | Mais simples, sem overhead de protocolo, testável diretamente |
+| O servidor interno já existe e está publicado como MCP | Consumir MCP server | Evita duplicar lógica |
+| Precisa de controle total de retries, logging, validação | Tool nativa + middleware MAF | Middleware `ResilientToolMiddleware` dá controle fino |
+
+**Regra**: prefira MCP server quando o servidor já existe e é mantido por terceiros. Prefira tool nativa quando a lógica é do próprio projeto.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema | Solução |
+|-------------|---------|---------|
+| Criar um MCP server próprio só para o agente do mesmo projeto chamar | Overhead desnecessário de protocolo e deploy | Escrever tool nativa com `[Description]` + `AIFunctionFactory.Create()` |
+| Não tratar indisponibilidade do MCP server | O MCP server pode estar offline ou lento; o agente quebra | Usar `ResilientToolMiddleware` para capturar `HttpRequestException` e `TimeoutException` (ver `ai-agents-production`) |
+| Não usar `await using` no `mcpClient` | Processo filho (npx) fica zumbi; leak de recursos | Sempre `await using var mcpClient = await McpClientFactory.CreateAsync(...)` |
+| Hardcodar o model diretamente (`new ChatClient("gpt-4o", key)`) | Viola provider-agnostic; difícil de trocar | Sempre `_modelRegistry.GetChatClient("alias")` (ver `ai-agents-providers-model-registry`) |
+
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `ModelContextProtocol` presente no `.csproj`
+- [ ] `await using var mcpClient` — dispose correto do transporte
+- [ ] `McpClientFactory.CreateAsync(new StdioClientTransport(...))` com `Name`, `Command`, `Arguments`
+- [ ] `ListToolsAsync()` chamado antes de criar o agente
+- [ ] `mcpTools.Cast<AITool>()` para registrar no agente
+- [ ] Agente criado via `_modelRegistry.GetChatClient("alias").AsAIAgent(...)` — provider-agnostic
+- [ ] `ResilientToolMiddleware` ou equivalente registrado (o MCP server pode ficar indisponível)
+- [ ] Nenhum `Guid.NewGuid()` — usar `Guid.CreateVersion7()` se IDs são necessários
+
+---
+
+## References
+
+- `ai-agents-setup` — pacotes base MAF, DI, quick start
+- `ai-agents-production` — panorama de MCP Integration, `ResilientToolMiddleware`, middleware pipeline
+- `ai-agents-mcp-server` — expor capacidades do próprio projeto como MCP server
+- `integration/mcp/mcp-tools.md` — MCPs no workflow do morph-spec (Playwright, Context7, Neon) — contexto complementar, escopo diferente
+- [ModelContextProtocol C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)
+- [Using MCP Tools — MAF docs](https://learn.microsoft.com/agent-framework/user-guide/model-context-protocol/using-mcp-tools)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/mcp-tools.md v1.0 (2026-05-19)*

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

@@ -0,0 +1,207 @@
+# Middleware Patterns — Intercepting agent behavior
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** middleware, agent middleware, function calling middleware, retry, anti-hallucination, resilience, telemetry middleware, agent run middleware
+> **Read by Claude in:** implement (when wiring cross-cutting behavior into an agent)
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Os 3 níveis de middleware
+
+| Tipo | Intercepts | Use Case |
+|------|-----------|----------|
+| **Agent Run** | Invocação completa do agent | Logging, auth, rate limiting |
+| **Function Calling** | Chamadas individuais de tools | Error handling, validação, auditoria |
+| **IChatClient** | Chamadas brutas ao LLM | Telemetry, caching, content filtering |
+
+Cada nível tem uma assinatura de delegate distinta. Os três podem coexistir no mesmo agent — cada um atua na sua camada sem interferir nos outros.
+
+---
+
+## Registrando middleware
+
+O registration point é sempre `.AsBuilder().Use(...).Build()`. Encadeie múltiplos middlewares antes de chamar `Build()`.
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// Obter o IChatClient via Model Registry — provider-agnostic
+IChatClient chatClient = _modelRegistry.GetChatClient("text-default");
+
+// IChatClient-level middleware (antes de criar o agent)
+IChatClient instrumentedClient = chatClient
+    .AsBuilder()
+        .Use(getResponseFunc: TelemetryMiddleware, getStreamingResponseFunc: null)
+    .Build();
+
+// Agent Run + Function Calling middleware
+AIAgent agent = instrumentedClient
+    .AsAIAgent(instructions: "You are a helpful assistant.")
+    .AsBuilder()
+        .Use(runFunc: LoggingMiddleware, runStreamingFunc: null)
+        .Use(ResilientToolMiddleware)   // function calling middleware
+    .Build();
+```
+
+> Se apenas middleware não-streaming for fornecido, chamadas streaming rodam em modo não-streaming.
+
+---
+
+## Pattern: telemetria
+
+IChatClient-level middleware que mede latência e token usage de cada chamada bruta ao LLM.
+
+```csharp
+using System.Diagnostics;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+async Task<ChatResponse> TelemetryMiddleware(
+    IEnumerable<ChatMessage> messages,
+    ChatOptions? options,
+    IChatClient innerChatClient,
+    CancellationToken cancellationToken)
+{
+    var sw = Stopwatch.StartNew();
+    var response = await innerChatClient.GetResponseAsync(messages, options, cancellationToken);
+    sw.Stop();
+    Console.WriteLine($"LLM call: {sw.ElapsedMilliseconds}ms, Tokens: {response.Usage?.TotalTokenCount}");
+    return response;
+}
+```
+
+Para o setup completo de OpenTelemetry (traces, métricas, Aspire Dashboard, `AgentOpenTelemetryConsts.DefaultSourceName`), consulte `ai-agents-production` §Observability. Não duplique aqui — este middleware é um ponto de entrada, não a solução completa.
+
+---
+
+## Pattern: resilência (retry + rate-limit)
+
+Function Calling middleware que intercepta erros de tools antes que o agent receba exceções brutas. Devolver uma string descritiva ao agent permite que ele se autocorrija ou informe o usuário adequadamente.
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+async ValueTask<object?> ResilientToolMiddleware(
+    AIAgent agent,
+    FunctionInvocationContext context,
+    Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
+    CancellationToken cancellationToken)
+{
+    try
+    {
+        return await next(context, cancellationToken);
+    }
+    catch (HttpRequestException ex) when (ex.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
+    {
+        return "Service is temporarily busy. Please try again in a moment.";
+    }
+    catch (TimeoutException)
+    {
+        return $"Tool '{context.Function.Name}' timed out. Try a simpler query.";
+    }
+    catch (Exception ex)
+    {
+        return $"Error in {context.Function.Name}: {ex.Message}";
+    }
+}
+```
+
+Template completo com registro e stub de anti-hallucination: `templates/code/dotnet/ai-agents/ResilientToolMiddleware.cs.template`.
+
+---
+
+## Pattern: anti-hallucination
+
+O LLM gera os argumentos de tool call baseado em linguagem natural — pode gerar formatos inválidos (datas malformadas, IDs fora de range, strings vazias). Validar **antes** de chamar `next()` permite que o agent se autocorrija na próxima iteração, sem precisar de retry externo.
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+async ValueTask<object?> AntiHallucinationMiddleware(
+    AIAgent agent,
+    FunctionInvocationContext context,
+    Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
+    CancellationToken cancellationToken)
+{
+    // Validate 'date' argument before calling the tool
+    if (context.Arguments.TryGetValue("date", out var dateArg)
+        && !DateTime.TryParse(dateArg?.ToString(), out _))
+    {
+        return $"Invalid date format for '{context.Function.Name}'. Expected ISO 8601 (e.g. 2026-01-31).";
+    }
+
+    // Validate 'orderId' is a positive integer
+    if (context.Arguments.TryGetValue("orderId", out var idArg)
+        && (!int.TryParse(idArg?.ToString(), out var id) || id <= 0))
+    {
+        return $"Invalid orderId '{idArg}' for '{context.Function.Name}'. Must be a positive integer.";
+    }
+
+    return await next(context, cancellationToken);
+}
+```
+
+**Princípio:** devolva uma mensagem de erro descritiva — o LLM vai corrigir o argumento na próxima iteração. Não lance exceção; não chame `next()` com argumento inválido.
+
+---
+
+## Decision tree
+
+```
+Precisa de middleware no agent?
+│
+├─ Logar / autorizar a invocação completa do agent?
+│   └─ Agent Run middleware
+│       .Use(runFunc: MyMiddleware, runStreamingFunc: null)
+│
+├─ Tratar falhas de tool / validar argumentos do LLM?
+│   └─ Function Calling middleware
+│       .Use(ResilientToolMiddleware)
+│
+└─ Medir / cachear / filtrar chamadas brutas ao LLM?
+    └─ IChatClient middleware
+        .Use(getResponseFunc: TelemetryMiddleware, getStreamingResponseFunc: null)
+        — aplicado no IChatClient.AsBuilder() ANTES de .AsAIAgent()
+```
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema |
+|--------------|---------|
+| Swallow exception sem retornar contexto ao agent | O agent não consegue se autocorrigir — para silenciosamente |
+| Middleware que muta estado global | Viola isolation; causa race conditions em requests concorrentes |
+| Fornecer apenas middleware não-streaming | Chamadas streaming rodam em modo não-streaming silenciosamente — downgrade imperceptível |
+| Lógica de negócio em middleware | Middleware é cross-cutting only; lógica de domínio pertence ao tool ou ao handler |
+| Registrar middleware depois de `Build()` | `Build()` finaliza o pipeline — chamadas após não têm efeito |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Middleware registrado via `.AsBuilder().Use(...).Build()` — nunca depois de `Build()`
+- [ ] IChatClient middleware aplicado no `chatClient.AsBuilder()` antes de `.AsAIAgent()`
+- [ ] Function Calling middleware retorna string descritiva em vez de lançar exceção
+- [ ] Anti-hallucination: argumentos validados antes de chamar `next()`
+- [ ] Nenhum middleware com `using Microsoft.SemanticKernel` — MAF 1.0 GA não usa SK
+- [ ] Streaming: se nenhum middleware streaming for fornecido, downgrade documentado como decisão consciente
+- [ ] Middleware que chama serviços externos tem timeout configurado
+
+---
+
+## References
+
+- `ai-agents-setup` — pacotes, DI, quick start
+- `ai-agents-production` — panorama completo: observability, A2A, MCP, caching, middleware-as-one-of-many-concerns
+- `ai-agents-providers-model-registry` — `_modelRegistry.GetChatClient(alias)`, provider-agnostic pattern
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/middleware-patterns.md v1.0 (2026-05-19)*