@polymorphism-tech/morph-spec 7.2.0 → 7.4.0

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

@@ -1,244 +1,258 @@
-# Microsoft Agent Framework — Setup Guide (.NET 10)
-
-> **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)
-
-**Verified against:** Microsoft.Agents.AI 1.0 GA (abril/2026). Last-verified: 2026-05-19.
-
----
-
-## Provider philosophy — direct models always
-
-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.
-
-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.
-
-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)
-
-```
-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
-```
-
----
-
-## 1. Packages (NuGet)
-
-**Required for any MAF project:**
-
-```xml
-<PackageReference Include="Microsoft.Agents.AI" Version="1.0.*" />
-```
-
-**Provider-specific (escolha conforme o Model Registry do projeto):**
-
-```xml
-<!-- OpenAI direct -->
-<PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.*" />
-<PackageReference Include="OpenAI" Version="2.*" />
-
-<!-- Ollama (local / on-prem) — usa o mesmo OpenAI-compatible client -->
-<PackageReference Include="OpenAI" Version="2.*" />
-
-<!-- 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.* -->
-```
-
-> 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;`.
-
-> 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.
-
-**Optional (only when feature requires):**
-
-```xml
-<!-- Hosting helpers (AddAIAgent, AddSequentialWorkflow) -->
-<PackageReference Include="Microsoft.Agents.AI.Hosting" Version="1.0.*" />
-
-<!-- A2A protocol -->
-<PackageReference Include="Microsoft.Agents.AI.A2A" Version="1.0.*" />
-```
-
-**Forbidden in new MAF projects:**
-
-- `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.
-
----
-
-## 2. Quick Start (canonical minimal agent)
-
-```csharp
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using OpenAI;
-using OpenAI.Chat;
-
-AIAgent agent = new ChatClient(model: "gpt-4o-mini", apiKey: "<from-config>")
-    .AsIChatClient()
-    .AsAIAgent(instructions: "You are a helpful assistant.");
-
-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.
-
----
-
-## 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.
-
-### 3.1 OpenAI direct (most common)
-
-```csharp
-using OpenAI;
-using OpenAI.Chat;
-using Microsoft.Extensions.AI;
-
-builder.Services.AddSingleton<IChatClient>(sp =>
-{
-    var cfg = sp.GetRequiredService<IConfiguration>();
-    return new ChatClient(
-            model: cfg["OpenAI:Model"] ?? "gpt-4o-mini",
-            apiKey: cfg["OpenAI:ApiKey"]!)
-        .AsIChatClient();
-});
-```
-
-### 3.2 Ollama (local dev / on-prem)
-
-Ollama exposes an OpenAI-compatible endpoint — use the same `ChatClient`:
-
-```csharp
-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());
-```
-
-> Models < 3B params often fail tool calling. Use Ollama only for non-tool agents in dev.
-
-### 3.3 Google (Gemini) / Anthropic (Claude)
-
-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()`.
-
----
-
-## 4. DI Registration (keyed agents)
-
-> 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>();
-    return new ChatClientAgent(
-        chatClient,
-        name: key,
-        instructions: "You are an order analysis expert.");
-});
-```
-
-Inject by key:
-
-```csharp
-public class AgentController(
-    [FromKeyedServices("OrderAnalyzer")] AIAgent orderAgent) : ControllerBase { ... }
-```
-
-For agents with tools and structured output, see `ai-agents-multi-agent-patterns` and `ai-agents-structured-output` (Onda 2).
-
----
-
-## 5. OpenTelemetry
-
-```csharp
-using OpenTelemetry;
-using OpenTelemetry.Trace;
-using Microsoft.Agents.AI;
-
-using var tracerProvider = Sdk.CreateTracerProviderBuilder()
-    .AddSource(AgentOpenTelemetryConsts.DefaultSourceName)
-    .AddOtlpExporter()
-    .Build();
-
-// Wrap any agent (e.g. the `agent` from §2)
-var instrumented = agent.WithOpenTelemetry();
-```
-
-> **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.
-
----
-
-## 6. Security checklist
-
-- [ ] 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).
-
----
-
-## 7. What NOT to do (anti-patterns)
-
-| 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 |
-
----
-
-## 8. Checklist (verifiable by morph-eval)
-
-- [ ] `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
-
----
-
-## 9. References
-
-- `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 — ai-agents/setup.md v2.0 (2026-05-19)*
+# Microsoft Agent Framework — Setup Guide (.NET 10)
+
+> **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)
+
+**Verified against:** Microsoft.Agents.AI 1.0 GA (abril/2026). Last-verified: 2026-05-19.
+
+---
+
+## Provider philosophy — direct models always
+
+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.
+
+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.
+
+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)
+
+```
+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
+```
+
+---
+
+## 1. Packages (NuGet)
+
+**Required for any MAF project:**
+
+```xml
+<PackageReference Include="Microsoft.Agents.AI" Version="1.0.*" />
+```
+
+**Provider-specific (escolha conforme o Model Registry do projeto):**
+
+```xml
+<!-- OpenAI direct -->
+<PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.*" />
+<PackageReference Include="OpenAI" Version="2.*" />
+
+<!-- Ollama (local / on-prem) — usa o mesmo OpenAI-compatible client -->
+<PackageReference Include="OpenAI" Version="2.*" />
+
+<!-- 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.* -->
+```
+
+> 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;`.
+
+> 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.
+
+**Optional (only when feature requires):**
+
+```xml
+<!-- Hosting helpers (AddAIAgent, AddSequentialWorkflow) -->
+<PackageReference Include="Microsoft.Agents.AI.Hosting" Version="1.0.*" />
+
+<!-- A2A protocol -->
+<PackageReference Include="Microsoft.Agents.AI.A2A" Version="1.0.*" />
+```
+
+**Forbidden in new MAF projects:**
+
+- `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.
+
+---
+
+## 2. Quick Start (canonical minimal agent)
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Chat;
+
+AIAgent agent = new ChatClient(model: "gpt-4o-mini", apiKey: "<from-config>")
+    .AsIChatClient()
+    .AsAIAgent(instructions: "You are a helpful assistant.");
+
+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.
+
+---
+
+## 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.
+
+### 3.1 OpenAI direct (most common)
+
+```csharp
+using OpenAI;
+using OpenAI.Chat;
+using Microsoft.Extensions.AI;
+
+builder.Services.AddSingleton<IChatClient>(sp =>
+{
+    var cfg = sp.GetRequiredService<IConfiguration>();
+    var apiKey = cfg["OpenAI:ApiKey"];
+    if (string.IsNullOrWhiteSpace(apiKey))
+    {
+        throw new InvalidOperationException(
+            "OpenAI:ApiKey is required. Bind it from an environment variable or secret store.");
+    }
+    return new ChatClient(
+            model: cfg["OpenAI:Model"] ?? "gpt-4o-mini",
+            apiKey: apiKey)
+        .AsIChatClient();
+});
+```
+
+> **Why explicit `string.IsNullOrWhiteSpace` instead of `?? throw` or `!`?**
+> `IConfiguration` returns the **empty string** (not `null`) for keys that
+> exist with blank values — which is the common shape of a checked-in
+> `appsettings.json` placeholder (`"OpenAI": { "ApiKey": "" }`). A
+> `?? throw` guard against `null` therefore never fires; the program
+> proceeds to `new ChatClient(model, "")` and crashes much later with
+> an opaque OpenAI SDK error. Always check whitespace.
+
+### 3.2 Ollama (local dev / on-prem)
+
+Ollama exposes an OpenAI-compatible endpoint — use the same `ChatClient`:
+
+```csharp
+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());
+```
+
+> Models < 3B params often fail tool calling. Use Ollama only for non-tool agents in dev.
+
+### 3.3 Google (Gemini) / Anthropic (Claude)
+
+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()`.
+
+---
+
+## 4. DI Registration (keyed agents)
+
+> 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>();
+    return new ChatClientAgent(
+        chatClient,
+        name: key,
+        instructions: "You are an order analysis expert.");
+});
+```
+
+Inject by key:
+
+```csharp
+public class AgentController(
+    [FromKeyedServices("OrderAnalyzer")] AIAgent orderAgent) : ControllerBase { ... }
+```
+
+For agents with tools and structured output, see `ai-agents-multi-agent-patterns` and `ai-agents-structured-output` (Onda 2).
+
+---
+
+## 5. OpenTelemetry
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+using Microsoft.Agents.AI;
+
+using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    .AddSource(AgentOpenTelemetryConsts.DefaultSourceName)
+    .AddOtlpExporter()
+    .Build();
+
+// Wrap any agent (e.g. the `agent` from §2)
+var instrumented = agent.WithOpenTelemetry();
+```
+
+> **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.
+
+---
+
+## 6. Security checklist
+
+- [ ] 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).
+
+---
+
+## 7. What NOT to do (anti-patterns)
+
+| 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 |
+
+---
+
+## 8. Checklist (verifiable by morph-eval)
+
+- [ ] `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
+
+---
+
+## 9. References
+
+- `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 — ai-agents/setup.md v2.0 (2026-05-19)*