@polymorphism-tech/morph-spec 7.0.0 → 7.1.1

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

@@ -1,157 +1,71 @@
-# Microsoft Agent Framework - Production Patterns
+# Microsoft Agent Framework — Production Patterns
 
-> **Scope:** universal
-> **Layer:** 0 (always load)
-> **Keywords:** middleware, a2a, mcp, caching, production, observability
-> **Load When:** always
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** middleware, observability, telemetry, mcp, a2a, caching, anti-hallucination, production agent
+> **Read by Claude in:** implement (when wiring middleware/telemetry/MCP into an agent)
 
-**Ref:** `setup.md` — Core setup | `workflows.md` — Orchestration
-
-Middleware, A2A protocol, MCP integration, caching, and observability for production agents.
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
 
 ---
 
 ## Middleware Pipeline
 
-Three middleware types intercept agent behavior at different layers:
+Três tipos de middleware interceptam o comportamento do agent em camadas distintas:
 
-| Type | Intercepts | Use Case |
+| Tipo | Intercepts | Use Case |
 |------|-----------|----------|
-| **Agent Run** | Full agent invocation | Logging, auth, rate limiting |
-| **Function Calling** | Individual tool calls | Error handling, validation, auditing |
-| **IChatClient** | Raw LLM calls | Telemetry, caching, content filtering |
-
-### Agent Run Middleware
-
-```csharp
-async Task<AgentResponse> LoggingMiddleware(
-    IEnumerable<ChatMessage> messages,
-    AgentSession? session,
-    AgentRunOptions? options,
-    AIAgent innerAgent,
-    CancellationToken cancellationToken)
-{
-    Console.WriteLine($"Input messages: {messages.Count()}");
-    var response = await innerAgent.RunAsync(messages, session, options, cancellationToken);
-    Console.WriteLine($"Output messages: {response.Messages.Count}");
-    return response;
-}
-```
-
-### Function Calling Middleware (Error Handling)
-
-```csharp
-async ValueTask<object?> ErrorHandlingMiddleware(
-    AIAgent agent,
-    FunctionInvocationContext context,
-    Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
-    CancellationToken cancellationToken)
-{
-    try
-    {
-        Console.WriteLine($"Calling: {context.Function.Name}");
-        var result = await next(context, cancellationToken);
-        Console.WriteLine($"Result: {result}");
-        return result;
-    }
-    catch (Exception ex)
-    {
-        // Return error message the agent can understand
-        return $"Error calling {context.Function.Name}: {ex.Message}. Try a different approach.";
-    }
-}
-```
+| **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 |
 
-### IChatClient Middleware
+O **tratamento canônico** de middleware — código dos 3 níveis, registro via `.AsBuilder().Use(...)`,
+e os patterns de telemetria, resilência (retry + rate-limit) e anti-hallucination — está em
+**`ai-agents-middleware-patterns`**. Não duplicado aqui.
 
-```csharp
-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;
-}
-```
-
-### Registering Middleware
-
-```csharp
-// On an existing agent
-var middlewareAgent = originalAgent
-    .AsBuilder()
-        .Use(runFunc: LoggingMiddleware, runStreamingFunc: LoggingStreamingMiddleware)
-        .Use(ErrorHandlingMiddleware)  // Function calling
-    .Build();
-
-// On the chat client (before agent creation)
-var chatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
-    .GetChatClient(deploymentName)
-    .AsIChatClient()
-    .AsBuilder()
-        .Use(getResponseFunc: TelemetryMiddleware, getStreamingResponseFunc: null)
-    .Build();
-
-// Via factory method on AsAIAgent
-var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent("You are a helpful assistant.", clientFactory: (chatClient) => chatClient
-        .AsBuilder()
-            .Use(getResponseFunc: TelemetryMiddleware, getStreamingResponseFunc: null)
-        .Build());
-```
-
-**Important:** If only non-streaming middleware is provided, streaming calls run in non-streaming mode.
+> Em produção: registre `ResilientToolMiddleware` (ou equivalente) em qualquer agent que chame
+> APIs externas, e um middleware de telemetria no `IChatClient`. Ver `ai-agents-middleware-patterns`
+> para o código e a decision tree de qual nível usar.
 
 ---
 
 ## A2A Protocol (Agent-to-Agent)
 
-Expose agents as interoperable web services using the standardized A2A protocol.
+Exponha agents como serviços web interoperáveis via protocolo A2A padronizado.
 
-### Packages
+**Package (GA):**
 
 ```xml
-<!-- A2A hosting — not yet published on NuGet, uncomment when GA -->
-<!-- <PackageReference Include="Microsoft.Agents.AI.Hosting.A2A.AspNetCore" Version="1.0.0-preview.*" /> -->
+<PackageReference Include="Microsoft.Agents.AI.A2A" Version="1.0.*" />
 ```
 
-> **Note:** The A2A hosting package is part of the MAF preview and is **not yet available on NuGet**.
-> The patterns below reflect the expected API surface. Until GA, implement A2A manually via HTTP endpoints.
-
-### Expose Agent via A2A
+### Expor um agent via A2A
 
 ```csharp
 // Program.cs
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.A2A;
+using Microsoft.Extensions.AI;
+
 var builder = WebApplication.CreateBuilder(args);
 
-IChatClient chatClient = new AzureOpenAIClient(
-        new Uri(endpoint), new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsIChatClient();
+// Registrar agent via Model Registry
+IChatClient chatClient = /* from ModelRegistry singleton */;
 builder.Services.AddSingleton(chatClient);
 
-// Register agents
-var mathAgent = builder.AddAIAgent("math", instructions: "You are a math expert.");
-var historyAgent = builder.AddAIAgent("history", instructions: "You are a history expert.");
+builder.AddAIAgent("math", instructions: "You are a math expert.");
+builder.AddAIAgent("history", instructions: "You are a history expert.");
 
 var app = builder.Build();
 
-// Expose via A2A protocol
-app.MapA2A(mathAgent, path: "/a2a/math", agentCard: new()
+app.MapA2A("math", path: "/a2a/math", agentCard: new()
 {
     Name = "Math Agent",
     Description = "Expert in mathematics and calculations.",
     Version = "1.0"
 });
 
-app.MapA2A(historyAgent, path: "/a2a/history", agentCard: new()
+app.MapA2A("history", path: "/a2a/history", agentCard: new()
 {
     Name = "History Agent",
     Description = "Expert in world history.",
@@ -161,103 +75,80 @@ app.MapA2A(historyAgent, path: "/a2a/history", agentCard: new()
 app.Run();
 ```
 
-### Agent Card Discovery
-
-```
-GET /a2a/math/v1/card    → Returns agent metadata (name, description, capabilities)
-POST /a2a/math/v1/message:stream  → Send message, get streaming response
-```
+### Consumir um agent A2A remoto
 
-### A2A Key Features
-
-| Feature | Description |
-|---------|-------------|
-| Agent Discovery | Standardized Agent Cards with metadata |
-| Cross-Framework | .NET agent can talk to Python agent and vice versa |
-| Context Persistence | `contextId` maintains conversation across messages |
-| Streaming | Server-Sent Events for real-time responses |
-| Long-Running Tasks | Async task support for extended operations |
+```csharp
+using Microsoft.Agents.AI.A2A;
 
----
+// Wrap a remote A2A endpoint as a local AIAgent
+AIAgent remoteAgent = new A2AClient(new Uri("https://agents.example.com/a2a/math"))
+    .AsAIAgent();
 
-## MCP Integration (Model Context Protocol)
-
-Connect agents to external tools and data sources via MCP servers.
+var response = await remoteAgent.RunAsync("What is the integral of x^2?");
+```
 
-### Package
+### Agent Card Discovery
 
-```bash
-dotnet add package ModelContextProtocol --prerelease
+```
+GET /a2a/math/v1/card         → metadata (name, description, capabilities)
+POST /a2a/math/v1/message:stream  → send message, get streaming response
 ```
 
-### Use MCP Tools in an Agent
+| Feature A2A | Descrição |
+|-------------|-----------|
+| Agent Discovery | Agent Cards com metadados padronizados |
+| Cross-Framework | Agent .NET pode conversar com agent Python |
+| Context Persistence | `contextId` mantém conversa entre mensagens |
+| Streaming | Server-Sent Events para respostas em tempo real |
 
-```csharp
-using ModelContextProtocol;
-using ModelContextProtocol.Client;
+---
 
-// Connect to an MCP server (e.g., GitHub)
-await using var mcpClient = await McpClientFactory.CreateAsync(
-    new StdioClientTransport(new()
-    {
-        Name = "GitHubServer",
-        Command = "npx",
-        Arguments = ["-y", "--verbose", "@modelcontextprotocol/server-github"],
-    }));
+## MCP Integration (Model Context Protocol)
 
-// Get available tools
-var mcpTools = await mcpClient.ListToolsAsync();
+Agents MAF podem consumir tools de **MCP servers externos** (GitHub, filesystem, Postgres,
+servidores internos) e expor capacidades do projeto **como** um MCP server.
 
-// Create agent with MCP tools
-AIAgent agent = chatClient.AsAIAgent(
-    instructions: "You answer questions about GitHub repositories.",
-    tools: [.. mcpTools.Cast<AITool>()]);
+Esses dois casos têm tratamento canônico em standards dedicados — **não duplicado aqui**:
 
-Console.WriteLine(await agent.RunAsync(
-    "Summarize the last 4 commits to microsoft/agent-framework"));
-```
+| Caso | Standard |
+|------|----------|
+| Agente MAF consome um MCP server externo | `ai-agents-mcp-tools` (`McpClientFactory.CreateAsync`, transports, `await using`) |
+| Projeto expõe capacidades como MCP server | `ai-agents-mcp-server` (`[McpServerTool]`, `AddMcpServer`, stdio/HTTP) |
 
-### Popular MCP Servers
-
-| Server | Purpose |
-|--------|---------|
-| `@modelcontextprotocol/server-github` | GitHub repos, issues, PRs |
-| `@modelcontextprotocol/server-filesystem` | File system operations |
-| `@modelcontextprotocol/server-sqlite` | SQLite database access |
-| Azure MCP Server | Azure resource management |
+> Em produção, lembre: MCP client sempre com `await using` (dispose do transporte); MCP server
+> exposto via HTTP exige autenticação. Detalhes nos standards acima.
 
 ---
 
-## Caching Patterns for AI
+## Caching Patterns
 
 ### Semantic Caching (Redis)
 
-Cache LLM responses by semantic similarity — avoid repeated inference costs.
+Cache de respostas LLM por similaridade semântica — evita inferências repetidas.
+
+> **Illustrative pseudo-code** — the exact Redis vector-search calls depend on your Redis client. For a complete, working semantic-search implementation see `ai-agents-rag-custom-pgvector` (Onda 2). The point of this section is the *pattern*: embed the query, vector-search a cache, return on a similarity hit.
 
 ```csharp
 public async Task<string?> GetCachedResponseAsync(string question)
 {
     var questionEmbedding = await _embedding.GenerateAsync(question);
 
-    var results = await _redis.ExecuteAsync("FT.SEARCH",
-        "idx:semantic_cache",
-        $"*=>[KNN 1 @embedding $vec AS score]",
-        "PARAMS", "2", "vec", questionEmbedding.ToByteArray(),
-        "SORTBY", "score", "DIALECT", "2");
+    // pseudo-code: perform a KNN vector search against the cache index
+    var (similarityScore, cachedResponse) = await VectorSearchCacheAsync(
+        "idx:semantic_cache", questionEmbedding);
 
-    if (results.Score < 0.95)  // 95% similar
-        return results.Response;
+    if (similarityScore >= 0.95)   // cosine similarity: higher = more similar
+        return cachedResponse;
 
-    return null;  // Cache miss
+    return null;  // cache miss
 }
 ```
 
-**Cost savings:** Embedding call ~$0.0001/1K tokens vs inference ~$0.01-0.03/1K tokens = **100-300x savings**.
+**Cost savings:** embedding ~$0.0001/1K tokens vs inferência ~$0.01-0.03/1K tokens = **100-300x savings**.
 
 ### Hybrid Cache (L1 + L2)
 
 ```csharp
-// Program.cs
 builder.Services.AddHybridCache(options =>
 {
     options.DefaultEntryOptions = new HybridCacheEntryOptions
@@ -267,7 +158,7 @@ builder.Services.AddHybridCache(options =>
     };
 });
 
-// Usage — tool with caching
+// Uso num tool
 [Description("Gets weather for a location")]
 public async Task<WeatherResponse> GetWeatherAsync(
     string location, string date, CancellationToken ct)
@@ -284,17 +175,16 @@ public async Task<WeatherResponse> GetWeatherAsync(
 | L1 | Process memory | Fastest | Per instance |
 | L2 | Redis | Very fast | Distributed |
 
-### MCP Tool Routing Cache
-
-Store tool description embeddings in Redis. On user query, find relevant tools by vector similarity — reduces tokens sent to LLM.
-
 ---
 
-## Observability
-
-### OpenTelemetry Integration
+## Observability / OpenTelemetry
 
 ```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+using OpenTelemetry.Metrics;
+using Microsoft.Agents.AI;
+
 // Enable on individual agents
 agent.WithOpenTelemetry();
 
@@ -302,39 +192,31 @@ agent.WithOpenTelemetry();
 builder.Services.AddOpenTelemetry()
     .WithTracing(tracing =>
     {
-        tracing.AddSource("Experimental.Microsoft.Extensions.AI.*");
+        tracing.AddSource(AgentOpenTelemetryConsts.DefaultSourceName);   // MAF 1.0 GA source
         tracing.AddSource(builder.Environment.ApplicationName);
         tracing.AddAspNetCoreInstrumentation();
         tracing.AddHttpClientInstrumentation();
+        tracing.AddOtlpExporter();
     })
     .WithMetrics(metrics =>
     {
-        metrics.AddMeter("Experimental.Microsoft.Extensions.AI.*");
+        metrics.AddMeter(AgentOpenTelemetryConsts.DefaultSourceName);    // MAF 1.0 GA meter
         metrics.AddAspNetCoreInstrumentation();
         metrics.AddHttpClientInstrumentation();
         metrics.AddRuntimeInstrumentation();
     });
-
-// Enable sensitive data in development
-builder.AddAzureChatCompletionsClient("chat", settings =>
-{
-    settings.EnableSensitiveTelemetryData = builder.Environment.IsDevelopment();
-});
 ```
 
+> **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.
+
 ### Aspire Dashboard
 
-Visualizes agent traces including:
-- Full conversation flow between agents
+Visualiza traces de agents incluindo:
+- Fluxo completo de conversas entre agents
 - Tool call cycles (Model → Tool → Model)
-- Token usage and latency per call
-- Error traces and retry patterns
-
-```csharp
-// AppHost/Program.cs
-var redis = builder.AddAzureRedisEnterprise("cache");
-var api = builder.AddProject<Projects.Api>().WithReference(redis);
-```
+- Token usage e latência por chamada
+- Error traces e retry patterns
 
 ### What to Monitor
 
@@ -348,72 +230,46 @@ var api = builder.AddProject<Projects.Api>().WithReference(redis);
 
 ---
 
-## Error Handling Strategy
-
-### Centralized via Middleware
-
-```csharp
-// Function calling middleware catches tool errors
-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)
-    {
-        // Rate limit — return friendly message so agent can retry
-        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)
-    {
-        // Log and return error context to agent
-        return $"Error in {context.Function.Name}: {ex.Message}";
-    }
-}
-```
-
-### HAX Framework Principles for Production
+## Security Checklist (verifiable by morph-eval)
 
-| Principle | Implementation |
-|-----------|---------------|
-| Progressive disclosure | Start simple, add detail on request |
-| Transparent agency | Log and expose agent decisions |
-| Failure visibility | Never silently swallow errors |
-| Intervention opportunities | HITL checkpoints when confidence is low |
+- [ ] API keys nunca em `appsettings.json` no repositório — bind de environment variables ou secret store
+- [ ] Variáveis de provider (`OpenAI__ApiKey`, `Google__ApiKey`, `Anthropic__ApiKey`) em env vars / Docker secrets
+- [ ] Input validation middleware registrado em agents públicos (PII detection, injection prevention)
+- [ ] Output filtering / guardrails para conteúdo prejudicial
+- [ ] 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
 
 ---
 
-## Security Checklist
+## Production Checklist (verifiable by morph-eval)
 
-- [ ] API keys in Key Vault (never in appsettings)
-- [ ] Managed Identity for Azure services
-- [ ] Input validation middleware (PII detection, injection prevention)
-- [ ] Output filtering (guardrails for harmful content)
-- [ ] Typed message edges for data isolation between agents
-- [ ] Rate limiting middleware on public-facing agents
-- [ ] A2A endpoints behind authentication
+- [ ] `Microsoft.Agents.AI` 1.0.* no `.csproj`; nenhum pacote `Experimental.*` ou SK
+- [ ] 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`)
+- [ ] A2A endpoints com `MapA2A` protegidos por auth se expostos na internet
+- [ ] MCP client `await using` para dispose correto do transporte
 
 ---
 
 ## References
 
+- `ai-agents-setup` — pacotes, DI, quick start
+- `ai-agents-sweet-spot` — decisão de arquitetura antes de middleware
+- `ai-agents-providers-model-registry` — Model Registry para `_modelRegistry.GetChatClient(...)`
+- `ai-agents-middleware-patterns` — **tratamento canônico** de middleware (código dos 3 níveis, telemetria, resilência, anti-hallucination)
+- `ai-agents-mcp-tools` — agente MAF consumindo MCP servers externos
+- `ai-agents-mcp-server` — projeto expondo capacidades como MCP server
+- `ai-agents-rag-custom-pgvector` — implementação completa de busca semântica (referida em Caching)
 - [Agent Middleware](https://learn.microsoft.com/agent-framework/user-guide/agents/agent-middleware)
 - [A2A Integration](https://learn.microsoft.com/agent-framework/user-guide/hosting/agent-to-agent-integration)
 - [Using MCP Tools](https://learn.microsoft.com/agent-framework/user-guide/model-context-protocol/using-mcp-tools)
 - [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)
-- [Build MCP Server in C#](https://devblogs.microsoft.com/dotnet/build-a-model-context-protocol-mcp-server-in-csharp/)
-- `setup.md` — Core setup
-- `workflows.md` — Orchestration patterns
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/production.md v2.1 (2026-05-19)*