@polymorphism-tech/morph-spec 7.8.1 → 7.9.0

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

@@ -1,275 +1,275 @@
-# Microsoft Agent Framework — Production Patterns
-
-> **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)
-
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
-
----
-
-## Middleware Pipeline
-
-Três tipos de middleware interceptam o comportamento do agent em camadas distintas:
-
-| 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 |
-
-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.
-
-> 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)
-
-Exponha agents como serviços web interoperáveis via protocolo A2A padronizado.
-
-**Package (GA):**
-
-```xml
-<PackageReference Include="Microsoft.Agents.AI.A2A" Version="1.0.*" />
-```
-
-### 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);
-
-// Registrar agent via Model Registry
-IChatClient chatClient = /* from ModelRegistry singleton */;
-builder.Services.AddSingleton(chatClient);
-
-builder.AddAIAgent("math", instructions: "You are a math expert.");
-builder.AddAIAgent("history", instructions: "You are a history expert.");
-
-var app = builder.Build();
-
-app.MapA2A("math", path: "/a2a/math", agentCard: new()
-{
-    Name = "Math Agent",
-    Description = "Expert in mathematics and calculations.",
-    Version = "1.0"
-});
-
-app.MapA2A("history", path: "/a2a/history", agentCard: new()
-{
-    Name = "History Agent",
-    Description = "Expert in world history.",
-    Version = "1.0"
-});
-
-app.Run();
-```
-
-### Consumir um agent A2A remoto
-
-```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();
-
-var response = await remoteAgent.RunAsync("What is the integral of x^2?");
-```
-
-### Agent Card Discovery
-
-```
-GET /a2a/math/v1/card         → metadata (name, description, capabilities)
-POST /a2a/math/v1/message:stream  → send message, get streaming response
-```
-
-| 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 |
-
----
-
-## MCP Integration (Model Context Protocol)
-
-Agents MAF podem consumir tools de **MCP servers externos** (GitHub, filesystem, Postgres,
-servidores internos) e expor capacidades do projeto **como** um MCP server.
-
-Esses dois casos têm tratamento canônico em standards dedicados — **não duplicado aqui**:
-
-| 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) |
-
-> 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
-
-### Semantic Caching (Redis)
-
-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);
-
-    // pseudo-code: perform a KNN vector search against the cache index
-    var (similarityScore, cachedResponse) = await VectorSearchCacheAsync(
-        "idx:semantic_cache", questionEmbedding);
-
-    if (similarityScore >= 0.95)   // cosine similarity: higher = more similar
-        return cachedResponse;
-
-    return null;  // cache miss
-}
-```
-
-**Cost savings:** embedding ~$0.0001/1K tokens vs inferência ~$0.01-0.03/1K tokens = **100-300x savings**.
-
-### Hybrid Cache (L1 + L2)
-
-```csharp
-builder.Services.AddHybridCache(options =>
-{
-    options.DefaultEntryOptions = new HybridCacheEntryOptions
-    {
-        Expiration = TimeSpan.FromMinutes(10),
-        LocalCacheExpiration = TimeSpan.FromMinutes(1)
-    };
-});
-
-// Uso num tool
-[Description("Gets weather for a location")]
-public async Task<WeatherResponse> GetWeatherAsync(
-    string location, string date, CancellationToken ct)
-{
-    return await _cache.GetOrCreateAsync(
-        $"weather:{location}:{date}",
-        async token => await FetchFromApiAsync(location, date, token),
-        cancellationToken: ct);
-}
-```
-
-| Level | Location | Speed | Scope |
-|-------|----------|-------|-------|
-| L1 | Process memory | Fastest | Per instance |
-| L2 | Redis | Very fast | Distributed |
-
----
-
-## Observability / OpenTelemetry
-
-```csharp
-using OpenTelemetry;
-using OpenTelemetry.Trace;
-using OpenTelemetry.Metrics;
-using Microsoft.Agents.AI;
-
-// Enable on individual agents
-agent.WithOpenTelemetry();
-
-// Program.cs — full setup
-builder.Services.AddOpenTelemetry()
-    .WithTracing(tracing =>
-    {
-        tracing.AddSource(AgentOpenTelemetryConsts.DefaultSourceName);   // MAF 1.0 GA source
-        tracing.AddSource(builder.Environment.ApplicationName);
-        tracing.AddAspNetCoreInstrumentation();
-        tracing.AddHttpClientInstrumentation();
-        tracing.AddOtlpExporter();
-    })
-    .WithMetrics(metrics =>
-    {
-        metrics.AddMeter(AgentOpenTelemetryConsts.DefaultSourceName);    // MAF 1.0 GA meter
-        metrics.AddAspNetCoreInstrumentation();
-        metrics.AddHttpClientInstrumentation();
-        metrics.AddRuntimeInstrumentation();
-    });
-```
-
-> **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
-
-Visualiza traces de agents incluindo:
-- Fluxo completo de conversas entre agents
-- Tool call cycles (Model → Tool → Model)
-- Token usage e latência por chamada
-- Error traces e retry patterns
-
-### What to Monitor
-
-| Metric | Purpose | Alert Threshold |
-|--------|---------|----------------|
-| Token usage per request | Cost control | > 10K tokens/request |
-| Latency per agent call | Performance | > 5s for simple tasks |
-| Tool call failure rate | Reliability | > 5% failures |
-| Cache hit rate | Cost optimization | < 50% (tune strategy) |
-| Model drift | Quality | Evaluation score drop > 10% |
-
----
-
-## Security Checklist (verifiable by morph-eval)
-
-- [ ] 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
-
----
-
-## Production Checklist (verifiable by morph-eval)
-
-- [ ] `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)
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/production.md v2.1 (2026-05-19)*
+# Microsoft Agent Framework — Production Patterns
+
+> **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)
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Middleware Pipeline
+
+Três tipos de middleware interceptam o comportamento do agent em camadas distintas:
+
+| 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 |
+
+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.
+
+> 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)
+
+Exponha agents como serviços web interoperáveis via protocolo A2A padronizado.
+
+**Package (GA):**
+
+```xml
+<PackageReference Include="Microsoft.Agents.AI.A2A" Version="1.0.*" />
+```
+
+### 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);
+
+// Registrar agent via Model Registry
+IChatClient chatClient = /* from ModelRegistry singleton */;
+builder.Services.AddSingleton(chatClient);
+
+builder.AddAIAgent("math", instructions: "You are a math expert.");
+builder.AddAIAgent("history", instructions: "You are a history expert.");
+
+var app = builder.Build();
+
+app.MapA2A("math", path: "/a2a/math", agentCard: new()
+{
+    Name = "Math Agent",
+    Description = "Expert in mathematics and calculations.",
+    Version = "1.0"
+});
+
+app.MapA2A("history", path: "/a2a/history", agentCard: new()
+{
+    Name = "History Agent",
+    Description = "Expert in world history.",
+    Version = "1.0"
+});
+
+app.Run();
+```
+
+### Consumir um agent A2A remoto
+
+```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();
+
+var response = await remoteAgent.RunAsync("What is the integral of x^2?");
+```
+
+### Agent Card Discovery
+
+```
+GET /a2a/math/v1/card         → metadata (name, description, capabilities)
+POST /a2a/math/v1/message:stream  → send message, get streaming response
+```
+
+| 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 |
+
+---
+
+## MCP Integration (Model Context Protocol)
+
+Agents MAF podem consumir tools de **MCP servers externos** (GitHub, filesystem, Postgres,
+servidores internos) e expor capacidades do projeto **como** um MCP server.
+
+Esses dois casos têm tratamento canônico em standards dedicados — **não duplicado aqui**:
+
+| 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) |
+
+> 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
+
+### Semantic Caching (Redis)
+
+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);
+
+    // pseudo-code: perform a KNN vector search against the cache index
+    var (similarityScore, cachedResponse) = await VectorSearchCacheAsync(
+        "idx:semantic_cache", questionEmbedding);
+
+    if (similarityScore >= 0.95)   // cosine similarity: higher = more similar
+        return cachedResponse;
+
+    return null;  // cache miss
+}
+```
+
+**Cost savings:** embedding ~$0.0001/1K tokens vs inferência ~$0.01-0.03/1K tokens = **100-300x savings**.
+
+### Hybrid Cache (L1 + L2)
+
+```csharp
+builder.Services.AddHybridCache(options =>
+{
+    options.DefaultEntryOptions = new HybridCacheEntryOptions
+    {
+        Expiration = TimeSpan.FromMinutes(10),
+        LocalCacheExpiration = TimeSpan.FromMinutes(1)
+    };
+});
+
+// Uso num tool
+[Description("Gets weather for a location")]
+public async Task<WeatherResponse> GetWeatherAsync(
+    string location, string date, CancellationToken ct)
+{
+    return await _cache.GetOrCreateAsync(
+        $"weather:{location}:{date}",
+        async token => await FetchFromApiAsync(location, date, token),
+        cancellationToken: ct);
+}
+```
+
+| Level | Location | Speed | Scope |
+|-------|----------|-------|-------|
+| L1 | Process memory | Fastest | Per instance |
+| L2 | Redis | Very fast | Distributed |
+
+---
+
+## Observability / OpenTelemetry
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+using OpenTelemetry.Metrics;
+using Microsoft.Agents.AI;
+
+// Enable on individual agents
+agent.WithOpenTelemetry();
+
+// Program.cs — full setup
+builder.Services.AddOpenTelemetry()
+    .WithTracing(tracing =>
+    {
+        tracing.AddSource(AgentOpenTelemetryConsts.DefaultSourceName);   // MAF 1.0 GA source
+        tracing.AddSource(builder.Environment.ApplicationName);
+        tracing.AddAspNetCoreInstrumentation();
+        tracing.AddHttpClientInstrumentation();
+        tracing.AddOtlpExporter();
+    })
+    .WithMetrics(metrics =>
+    {
+        metrics.AddMeter(AgentOpenTelemetryConsts.DefaultSourceName);    // MAF 1.0 GA meter
+        metrics.AddAspNetCoreInstrumentation();
+        metrics.AddHttpClientInstrumentation();
+        metrics.AddRuntimeInstrumentation();
+    });
+```
+
+> **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
+
+Visualiza traces de agents incluindo:
+- Fluxo completo de conversas entre agents
+- Tool call cycles (Model → Tool → Model)
+- Token usage e latência por chamada
+- Error traces e retry patterns
+
+### What to Monitor
+
+| Metric | Purpose | Alert Threshold |
+|--------|---------|----------------|
+| Token usage per request | Cost control | > 10K tokens/request |
+| Latency per agent call | Performance | > 5s for simple tasks |
+| Tool call failure rate | Reliability | > 5% failures |
+| Cache hit rate | Cost optimization | < 50% (tune strategy) |
+| Model drift | Quality | Evaluation score drop > 10% |
+
+---
+
+## Security Checklist (verifiable by morph-eval)
+
+- [ ] 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
+
+---
+
+## Production Checklist (verifiable by morph-eval)
+
+- [ ] `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)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/production.md v2.1 (2026-05-19)*