@polymorphism-tech/morph-spec 7.0.0 → 7.1.1

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

@@ -1,418 +1,244 @@
-# Microsoft Agent Framework - Setup Guide (.NET 10)
+# Microsoft Agent Framework — Setup Guide (.NET 10)
 
-> **Scope:** universal
-> **Layer:** 0 (always load)
-> **Keywords:** agent, ai, openai, setup, microsoft agents, chatclient
-> **Load When:** always
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 0 (always-load via persona maf-expert)
+> **Keywords:** maf setup, microsoft agents ai, chatclient, ai agent, agent framework, agent dotnet, AsAIAgent
+> **Read by Claude in:** plan (pra citar pacote em tasks.json) + implement (pra escrever .csproj e Program.cs)
 
-**IMPORTANT:** MORPH-SPEC uses **exclusively** Microsoft Agent Framework.
-Semantic Kernel is superseded. Do NOT use `Kernel`, `KernelFunction`, or `InvokePromptAsync`.
+**Verified against:** Microsoft.Agents.AI 1.0 GA (abril/2026). Last-verified: 2026-05-19.
 
 ---
 
-## Packages
+## Provider philosophy — direct models always
 
-```xml
-<!-- .csproj -->
-<!-- Microsoft.Extensions.AI — STABLE abstractions for IChatClient, AIFunctionFactory, tools -->
-<PackageReference Include="Microsoft.Extensions.AI" Version="9.5.0" />
-<PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.3.0-preview.*" />
+This framework is **provider-agnostic**. There is no "primary" provider hardcoded. Every model is reached as a **direct model** (you call the model API directly) — never via a hosted agent service. Hosted services lag 6-9 months on models and remove control.
 
-<!-- For Azure OpenAI -->
-<PackageReference Include="Azure.AI.OpenAI" Version="2.*" />
-<PackageReference Include="Azure.Identity" Version="1.*" />
+First-class providers: **OpenAI, Google (Gemini), Anthropic (Claude), Ollama** (local/on-prem).
+Azure OpenAI is also a direct model but is **not a default** — see note in §3.4.
 
-<!-- For A2A protocol hosting (when GA) -->
-<!-- <PackageReference Include="Microsoft.Agents.AI.Hosting.A2A.AspNetCore" Version="1.0.0-preview.*" /> -->
-```
+The concrete model choice lives in the project's Model Registry, not in this standard. See `ai-agents-providers-model-registry`.
+
+## Decision tree (when reading this in plan phase)
 
-> **Note:** The Microsoft Agent Framework (MAF) packages (`Microsoft.Agents.AI.*`) are **not yet published on NuGet**.
-> Use `Microsoft.Extensions.AI` as the primary package — it provides `IChatClient`, `AIFunctionFactory`,
-> and all abstractions shown in this guide. The MAF `ChatClientAgent`, `AsAIAgent()`, and `AgentWorkflowBuilder`
-> APIs documented here reflect the expected GA surface. Until MAF ships, implement agents using `IChatClient` directly.
+```
+Está adicionando um agente AI a um projeto .NET?
+├─ Sim → use este standard + ai-agents-sweet-spot + ai-agents-providers-model-registry
+│   ├─ Projeto tem >1 modelo ou >1 provider? → SEMPRE use Model Registry
+│   ├─ Provider OpenAI? → §3.1
+│   ├─ Provider Ollama (local)? → §3.2
+│   ├─ Provider Google / Anthropic? → §3.3
+│   └─ Provider Azure OpenAI (data residency)? → §3.4 (nota, não default)
+└─ Não → este standard não se aplica
+```
 
 ---
 
-## Quick Start (Minimal Agent)
+## 1. Packages (NuGet)
 
-```csharp
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Extensions.AI;
-
-AIAgent agent = new AzureOpenAIClient(
-    new Uri("https://your-resource.openai.azure.com/"),
-    new AzureCliCredential())
-  .GetChatClient("gpt-4o-mini")
-  .AsAIAgent(instructions: "You are a helpful assistant.");
+**Required for any MAF project:**
 
-Console.WriteLine(await agent.RunAsync("Analyze this order."));
+```xml
+<PackageReference Include="Microsoft.Agents.AI" Version="1.0.*" />
 ```
 
----
-
-## Setup by Provider
+**Provider-specific (escolha conforme o Model Registry do projeto):**
 
-### Azure OpenAI (Production)
+```xml
+<!-- OpenAI direct -->
+<PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.*" />
+<PackageReference Include="OpenAI" Version="2.*" />
 
-```csharp
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Extensions.AI;
+<!-- Ollama (local / on-prem) — usa o mesmo OpenAI-compatible client -->
+<PackageReference Include="OpenAI" Version="2.*" />
 
-builder.Services.AddSingleton<IChatClient>(sp =>
-{
-    var cfg = sp.GetRequiredService<IConfiguration>();
-    return new AzureOpenAIClient(
-            new Uri(cfg["AzureOpenAI:Endpoint"]!),
-            new DefaultAzureCredential())  // Managed Identity
-        .GetChatClient(cfg["AzureOpenAI:DeploymentName"] ?? "gpt-4o-mini")
-        .AsIChatClient();
-});
+<!-- Google Gemini — SDK verificado no standard model-registry.md -->
+<!-- Anthropic Claude — SDK verificado no standard model-registry.md -->
+<!-- Azure OpenAI (somente se data residency exigir) — Azure.AI.OpenAI 2.* + Azure.Identity 1.* -->
 ```
 
-### GitHub Models (Development)
+> The `.AsIChatClient()` extension on `OpenAI.ChatClient` comes from `Microsoft.Agents.AI.OpenAI`. The `IChatClient` abstraction itself lives in `Microsoft.Extensions.AI` (a transitive dependency of `Microsoft.Agents.AI`) — code that uses `IChatClient` needs `using Microsoft.Extensions.AI;`.
 
-```csharp
-using OpenAI;
-using Microsoft.Extensions.AI;
+> Os pacotes de Google e Anthropic mudam de nome/versão com frequência. O standard `ai-agents-providers-model-registry` mantém a lista verificada com data. Não trave SDK aqui.
 
-builder.Services.AddSingleton<IChatClient>(sp =>
-{
-    var cfg = sp.GetRequiredService<IConfiguration>();
-    return new ChatClient(
-            "gpt-4o-mini",
-            new ApiKeyCredential(cfg["GitHub:Token"]!),
-            new OpenAIClientOptions { Endpoint = new Uri("https://models.github.ai/inference") })
-        .AsIChatClient();
-});
-```
+**Optional (only when feature requires):**
 
-### Ollama (Local)
+```xml
+<!-- Hosting helpers (AddAIAgent, AddSequentialWorkflow) -->
+<PackageReference Include="Microsoft.Agents.AI.Hosting" Version="1.0.*" />
 
-```csharp
-builder.Services.AddSingleton<IChatClient>(sp =>
-    new ChatClient("llama3.2:3b",
-        endpoint: new Uri("http://localhost:11434"))
-    .AsIChatClient());
+<!-- A2A protocol -->
+<PackageReference Include="Microsoft.Agents.AI.A2A" Version="1.0.*" />
 ```
 
----
+**Forbidden in new MAF projects:**
 
-## Agent Pattern (Required)
+- `Microsoft.SemanticKernel.*` — superseded by MAF, do not introduce.
+- `Microsoft.Extensions.AI.OpenAI` 9.* — replaced by `Microsoft.Agents.AI.OpenAI` in GA.
+- Hosted agent services (Foundry Agent Service, etc.) — use direct models.
 
-### Using ChatClientAgent
+---
+
+## 2. Quick Start (canonical minimal agent)
 
 ```csharp
+using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Chat;
 
-public class OrderAnalysisAgent
-{
-    private readonly IChatClient _chatClient;
-    private readonly ILogger<OrderAnalysisAgent> _logger;
-
-    public OrderAnalysisAgent(IChatClient chatClient, ILogger<OrderAnalysisAgent> logger)
-    {
-        _chatClient = chatClient;
-        _logger = logger;
-    }
-
-    public async Task<string> AnalyzeAsync(Order order, CancellationToken ct = default)
-    {
-        var agent = new ChatClientAgent(
-            _chatClient,
-            new ChatClientAgentOptions
-            {
-                Name = "OrderAnalyzer",
-                Instructions = """
-                    You are an e-commerce order analyst.
-                    Analyze the order and return:
-                    1. Summary
-                    2. Upsell suggestions
-                    3. Cancellation risk (low/medium/high)
-                    Be concise.
-                    """
-            });
-
-        _logger.LogInformation("Analyzing order {OrderNumber}", order.OrderNumber);
-
-        var response = await agent.RunAsync(
-            $"Order: {order.OrderNumber}, Total: {order.Total:C}, Items: {order.Items.Count}",
-            cancellationToken: ct);
-
-        return response.Text;
-    }
-}
-```
-
-### Using AsAIAgent (Shorthand)
-
-```csharp
-AIAgent agent = chatClient.AsAIAgent(
-    instructions: "You are a helpful assistant.",
-    name: "MyAgent");
+AIAgent agent = new ChatClient(model: "gpt-4o-mini", apiKey: "<from-config>")
+    .AsIChatClient()
+    .AsAIAgent(instructions: "You are a helpful assistant.");
 
-var response = await agent.RunAsync("Hello!", cancellationToken: ct);
+var response = await agent.RunAsync("Analyze this order.");
 Console.WriteLine(response.Text);
 ```
 
+This snippet is the baseline. In a real project you never hardcode the model — use the Model Registry (`ai-agents-providers-model-registry`). Anything more complex (DI, tools, structured output, RAG) layers on top via the other ai-agents standards.
+
 ---
 
-## Tools (Function Calling)
+## 3. Setup by Provider
+
+> In any project with >1 model or >1 provider, **do not register `IChatClient` directly** — use the Model Registry (`ai-agents-providers-model-registry`). The snippets below show the raw client construction the registry wraps.
 
-### Define Tools with AIFunctionFactory
+### 3.1 OpenAI direct (most common)
 
 ```csharp
+using OpenAI;
+using OpenAI.Chat;
 using Microsoft.Extensions.AI;
 
-public class WeatherFunctions
+builder.Services.AddSingleton<IChatClient>(sp =>
 {
-    private readonly IWeatherService _weatherService;
-
-    public WeatherFunctions(IWeatherService weatherService) => _weatherService = weatherService;
-
-    [Description("Gets current weather for a city")]
-    public async Task<string> GetWeatherAsync(
-        [Description("City name")] string city,
-        CancellationToken ct = default)
-    {
-        var weather = await _weatherService.GetCurrentAsync(city, ct);
-        return $"Temp: {weather.Temperature}°C, Condition: {weather.Condition}";
-    }
-
-    [Description("Gets weather forecast for upcoming days")]
-    public async Task<string> GetForecastAsync(
-        [Description("City name")] string city,
-        [Description("Number of days")] int days = 3,
-        CancellationToken ct = default)
-    {
-        var forecast = await _weatherService.GetForecastAsync(city, days, ct);
-        return string.Join("\n", forecast.Select(f => $"{f.Date:dd/MM}: {f.Temperature}°C"));
-    }
-}
+    var cfg = sp.GetRequiredService<IConfiguration>();
+    return new ChatClient(
+            model: cfg["OpenAI:Model"] ?? "gpt-4o-mini",
+            apiKey: cfg["OpenAI:ApiKey"]!)
+        .AsIChatClient();
+});
 ```
 
-### Register Agent with Tools
+### 3.2 Ollama (local dev / on-prem)
+
+Ollama exposes an OpenAI-compatible endpoint — use the same `ChatClient`:
 
 ```csharp
-var weatherFunctions = new WeatherFunctions(weatherService);
-
-var agent = new ChatClientAgent(
-    chatClient,
-    new ChatClientAgentOptions
-    {
-        Name = "WeatherAssistant",
-        Instructions = "You help with weather questions. Use available tools.",
-        ChatOptions = new ChatOptions
-        {
-            Tools =
-            [
-                AIFunctionFactory.Create(weatherFunctions.GetWeatherAsync),
-                AIFunctionFactory.Create(weatherFunctions.GetForecastAsync)
-            ]
-        }
-    });
+using OpenAI;
+using OpenAI.Chat;
+using System.ClientModel;
+using Microsoft.Extensions.AI;
+
+builder.Services.AddSingleton<IChatClient>(sp =>
+    new ChatClient(
+            model: "llama3.2:3b",
+            credential: new ApiKeyCredential("ollama"),  // any non-empty string
+            options: new OpenAIClientOptions { Endpoint = new Uri("http://localhost:11434/v1") })
+        .AsIChatClient());
 ```
 
-### Static Function Tools
+> Models < 3B params often fail tool calling. Use Ollama only for non-tool agents in dev.
 
-```csharp
-[Description("Gets the current date and time")]
-static string GetCurrentDateTime() => DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss");
+### 3.3 Google (Gemini) / Anthropic (Claude)
 
-var agent = chatClient.AsAIAgent(
-    instructions: "You are a helpful assistant.",
-    tools: [AIFunctionFactory.Create(GetCurrentDateTime)]);
-```
+Both are first-class providers reached as direct models. The exact NuGet SDK and client construction are documented (with verification date) in `ai-agents-providers-model-registry` §providers — that standard is the single source of truth for provider SDKs, since they change names/versions often.
+
+### 3.4 Azure OpenAI (note — not a default)
+
+Azure OpenAI is also a direct model, but requires an Azure resource + deployment per model. It is **not a default provider** in this framework — projects deploy to VPS, not Azure. Add an Azure branch to the Model Registry only when a client explicitly requires data residency in a specific Azure region. The pattern: `new AzureOpenAIClient(endpoint, credential).GetChatClient(deployment).AsIChatClient()`.
 
 ---
 
-## Dependency Injection (Web API / Blazor)
+## 4. DI Registration (keyed agents)
 
-### Register Agents with Keyed Services
+> The `builder.AddAIAgent(...)` extension requires the `Microsoft.Agents.AI.Hosting` package (see §1 Optional). For projects that register agents manually without `AddAIAgent`, the base `Microsoft.Agents.AI` package is enough.
 
 ```csharp
 // Program.cs
 builder.AddAIAgent("OrderAnalyzer", (sp, key) =>
 {
     var chatClient = sp.GetRequiredService<IChatClient>();
-    var orderFunctions = sp.GetRequiredService<OrderFunctions>();
-
     return new ChatClientAgent(
         chatClient,
         name: key,
-        instructions: "You are an order analysis expert.",
-        tools:
-        [
-            AIFunctionFactory.Create(orderFunctions.GetOrderAsync),
-            AIFunctionFactory.Create(orderFunctions.CalculateDiscountAsync)
-        ]);
+        instructions: "You are an order analysis expert.");
 });
-
-// Simple agent (no tools)
-builder.AddAIAgent(
-    name: "Editor",
-    instructions: "You are an editor who improves text quality.");
 ```
 
-### Inject in Controllers / Blazor Components
+Inject by key:
 
 ```csharp
-// Controller
 public class AgentController(
-    [FromKeyedServices("OrderAnalyzer")] AIAgent orderAgent) : ControllerBase
-{
-    [HttpPost("analyze")]
-    public async Task<IActionResult> Analyze(OrderRequest request)
-    {
-        var response = await orderAgent.RunAsync(request.Prompt);
-        return Ok(response.Text);
-    }
-}
-
-// Blazor component
-@inject IServiceProvider ServiceProvider
-@code {
-    private AIAgent _agent = default!;
-
-    protected override void OnInitialized()
-    {
-        _agent = ServiceProvider.GetRequiredKeyedService<AIAgent>("OrderAnalyzer");
-    }
-}
-```
-
----
-
-## Streaming
-
-```csharp
-await foreach (var update in agent.RunStreamingAsync(
-    "Write a detailed analysis.",
-    cancellationToken: ct))
-{
-    if (update is AgentResponseUpdateEvent e)
-    {
-        Console.Write(e.Data);
-    }
-}
+    [FromKeyedServices("OrderAnalyzer")] AIAgent orderAgent) : ControllerBase { ... }
 ```
 
----
-
-## Recommended Models
-
-| Use Case | Model | Provider | Cost (per 1M input tokens) |
-|----------|-------|----------|---------------------------|
-| Simple tasks (default) | gpt-4o-mini | Azure OpenAI | $0.15 |
-| Complex analysis | gpt-4o | Azure OpenAI | $2.50 |
-| Embeddings | text-embedding-3-small | Azure OpenAI | $0.02 |
-| Local development | llama3.2:3b | Ollama | Free |
-| Cloud development | gpt-4o-mini | GitHub Models | Free (preview) |
-
-**MORPH-SPEC default:** `gpt-4o-mini` for production.
+For agents with tools and structured output, see `ai-agents-multi-agent-patterns` and `ai-agents-structured-output` (Onda 2).
 
 ---
 
-## Security
-
-### API Keys in Azure Key Vault
+## 5. OpenTelemetry
 
 ```csharp
-if (builder.Environment.IsProduction())
-{
-    var keyVaultUri = new Uri(builder.Configuration["KeyVault:Uri"]!);
-    builder.Configuration.AddAzureKeyVault(keyVaultUri, new DefaultAzureCredential());
-}
-```
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+using Microsoft.Agents.AI;
 
-### Managed Identity (Recommended)
+using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    .AddSource(AgentOpenTelemetryConsts.DefaultSourceName)
+    .AddOtlpExporter()
+    .Build();
 
-```csharp
-// Use DefaultAzureCredential — works with Managed Identity in production,
-// AzureCliCredential in development
-var client = new AzureOpenAIClient(
-    new Uri(config["AzureOpenAI:Endpoint"]!),
-    new DefaultAzureCredential());
+// Wrap any agent (e.g. the `agent` from §2)
+var instrumented = agent.WithOpenTelemetry();
 ```
 
----
-
-## Observability
-
-```csharp
-// Enable OpenTelemetry on agents
-agent.WithOpenTelemetry();
-
-// Program.cs — Aspire Dashboard integration
-builder.Services.AddOpenTelemetry()
-    .WithTracing(tracing =>
-    {
-        tracing.AddSource("Experimental.Microsoft.Extensions.AI.*");
-        tracing.AddAspNetCoreInstrumentation();
-    })
-    .WithMetrics(metrics =>
-    {
-        metrics.AddMeter("Experimental.Microsoft.Extensions.AI.*");
-        metrics.AddAspNetCoreInstrumentation();
-    });
-```
+> **Note:** Source name is `AgentOpenTelemetryConsts.DefaultSourceName` from `Microsoft.Agents.AI`. **Do NOT** use the old `Experimental.Microsoft.Extensions.AI.*` source — it belongs to a previous package family.
 
 ---
 
-## Limitations & Troubleshooting
+## 6. Security checklist
 
-| Problem | Cause | Solution |
-|---------|-------|----------|
-| Tool calling fails | Model < 3B params | Use gpt-4o-mini minimum |
-| Rate limit errors | Too many requests | Add retry middleware (see production.md) |
-| Tools not invoked | Missing `[Description]` | Add `[Description]` to method AND parameters |
-| Agent returns empty | No instructions | Always set `Instructions` in agent options |
+- [ ] API keys never in source. Bind from environment variables / secret store (the VPS deploy uses env vars; Docker secrets or a vault are fine too).
+- [ ] `appsettings.json` checked into git never contains real keys — only placeholder/empty values.
+- [ ] Provider keys (`OpenAI:ApiKey`, `Google:ApiKey`, `Anthropic:ApiKey`) bound from environment.
+- [ ] No agent receives raw user input without input-validation middleware (see `ai-agents-middleware-patterns` — Onda 2).
 
 ---
 
-## Checklist
+## 7. What NOT to do (anti-patterns)
 
-- [ ] `Microsoft.Extensions.AI` + `Microsoft.Extensions.AI.OpenAI` installed
-- [ ] `IChatClient` registered as singleton via DI
-- [ ] Agents created with `ChatClientAgent` or `AsAIAgent()`
-- [ ] Agents registered with `builder.AddAIAgent()` (keyed services)
-- [ ] Tools use `AIFunctionFactory.Create()` + `[Description]`
-- [ ] API keys in Key Vault (production)
-- [ ] Managed Identity configured
-- [ ] gpt-4o-mini as default model
-- [ ] OpenTelemetry enabled on agents
-- [ ] Error handling via middleware (see `production.md`)
+| Wrong | Right |
+|-------|-------|
+| `using Microsoft.SemanticKernel` | `using Microsoft.Agents.AI` |
+| `Kernel.InvokePromptAsync()` | `agent.RunAsync()` |
+| `[KernelFunction]` | `[Description]` on method + parameters; register via `AIFunctionFactory.Create()` |
+| `ChatHistory` | `IEnumerable<ChatMessage>` |
+| Hardcoded model strings spread across codebase | Single source via Model Registry (see `ai-agents-providers-model-registry`) |
+| `Microsoft.Extensions.AI.OpenAI` 9.* | `Microsoft.Agents.AI.OpenAI` 1.* GA |
+| Hosted agent service "to simplify" | Direct models always |
 
 ---
 
-## What NOT To Do
+## 8. Checklist (verifiable by morph-eval)
 
-| Wrong | Correct |
-|-------|---------|
-| `using Microsoft.SemanticKernel` | `using Microsoft.Extensions.AI` |
-| `Kernel.InvokePromptAsync()` | `agent.RunAsync()` |
-| `[KernelFunction]` | `AIFunctionFactory.Create()` |
-| `[AgentTool]` attribute | `[Description]` + `AIFunctionFactory` |
-| `AgentTool.FromMethod()` | `AIFunctionFactory.Create(method)` |
-| `_chatClient.CreateAgent()` | `new ChatClientAgent()` or `.AsAIAgent()` |
-| `agent.CreateThreadAsync()` | Use session/conversation management |
-| `ChatHistory` | `IEnumerable<ChatMessage>` |
-| Hardcoded API keys | Key Vault / Managed Identity |
-| Models < 3B for tools | gpt-4o-mini minimum |
+- [ ] `Microsoft.Agents.AI` package present in `.csproj`
+- [ ] No `Microsoft.SemanticKernel.*` references
+- [ ] `IChatClient` registered (either directly or via Model Registry)
+- [ ] At least one `AIAgent` created via `AsAIAgent()` or `new ChatClientAgent()`
+- [ ] OpenTelemetry source name is `AgentOpenTelemetryConsts.DefaultSourceName` (if telemetry wired)
+- [ ] Models reference Model Registry alias when project has >1 model use case
 
 ---
 
-## References
+## 9. References
 
-- [Agent Framework Quick Start](https://learn.microsoft.com/agent-framework/tutorials/quick-start)
-- [Agent Tools](https://learn.microsoft.com/agent-framework/user-guide/agents/agent-tools)
-- [Microsoft.Extensions.AI](https://learn.microsoft.com/dotnet/ai/ai-extensions)
-- [GitHub: microsoft/agent-framework](https://github.com/microsoft/agent-framework)
-- `workflows.md` — Orchestration patterns
-- `production.md` — Middleware, A2A, MCP, caching
-- `blazor-ui.md` — Natural Language First UI patterns
+- `ai-agents-sweet-spot` — when to use agents vs workflows
+- `ai-agents-providers-model-registry` — provider-agnostic pattern
+- `ai-agents-structured-output` (Onda 2) — typed responses
+- `ai-agents-middleware-patterns` (Onda 2) — telemetry, retry, anti-hallucination, streaming agent responses
+- Microsoft.Agents.AI docs: https://learn.microsoft.com/agent-framework/
+- Verified packages list (context7 /microsoft/agent-framework): retrieved 2026-05-19
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/setup.md v2.0 (2026-05-19)*