@polymorphism-tech/morph-spec 7.9.3 → 8.0.0

package/framework/standards/ai-agents/structured-output.md

@@ -1,249 +1,249 @@
-# Structured Output — Typed agent responses
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 0 (always-load via persona maf-expert)
-> **Keywords:** structured output, typed response, response format, schema validated output, record output, JSON schema agent, RunAsync generic
-> **Read by Claude in:** implement (sempre que um agente produz saída consumida por outro sistema)
-
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
-
----
-
-## Por que sempre Structured Output
-
-Texto livre de LLM é não-determinístico. Dois runs da mesma prompt podem retornar formatações diferentes, campos com nomes diferentes, ou dados em posições diferentes. Você não consegue plugar isso num pipeline downstream de forma confiável.
-
-Um `sealed record` tipado é um contrato: o front-end, o banco, o próximo agente sabem exatamente a shape. O runtime MAF gera o JSON Schema a partir do tipo, envia para o modelo, e deserializa o retorno automaticamente. Se o modelo devolver algo fora do schema, a call falha rápido e com mensagem clara — muito melhor que descobrir um bug de parsing em produção.
-
-**Regra prática:** 90%+ das chamadas a LLM em produção precisam de structured output. A única exceção é saída puramente textual para display final (ex: resposta de chatbot para o usuário). Se a saída vai ser lida por código, use `RunAsync<T>`.
-
----
-
-## A API (MAF 1.0 GA)
-
-### Form 1 — `RunAsync<T>` (recomendada)
-
-```csharp
-AgentResponse<CityInfo> response = await agent.RunAsync<CityInfo>("Provide information about Tokyo.");
-CityInfo tokyo = response.Result;
-```
-
-O runtime MAF:
-1. Gera o JSON Schema a partir de `T` automaticamente.
-2. Seta `ResponseFormat` na chamada ao modelo.
-3. Deserializa a resposta JSON diretamente em `.Result`.
-
-**Use Form 1 por default.** É a forma mais simples e a que menos expõe detalhes de provider.
-
----
-
-### Form 2 — `ChatResponseFormat.ForJsonSchema<T>()` (quando precisar de ChatOptions)
-
-```csharp
-AIAgent agent = _modelRegistry.GetChatClient("text-heavy").AsAIAgent(new ChatClientAgentOptions
-{
-    Name = "ProposalAgent",
-    ChatOptions = new()
-    {
-        Instructions = "You are a commercial proposal specialist.",
-        ResponseFormat = ChatResponseFormat.ForJsonSchema<ProposalDraft>()
-    }
-});
-
-AgentResponse response = await agent.RunAsync("Draft a proposal for a SaaS migration project.");
-ProposalDraft draft = response.Deserialize<ProposalDraft>(JsonSerializerOptions.Web);
-```
-
-**Use Form 2 quando:**
-- Você precisa setar `ResponseFormat` junto com outras `ChatOptions` (ex: temperatura, system prompt por invocação).
-- Você quer reusar o mesmo agente para múltiplos tipos de saída, trocando o format por chamada via `ChatClientAgentRunOptions`.
-
-**Setando ResponseFormat por invocação (sem recriar o agente):**
-
-```csharp
-var runOptions = new ChatClientAgentRunOptions
-{
-    ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<ProposalDraft>() }
-};
-
-AgentResponse response = await agent.RunAsync("Draft a proposal.", runOptions);
-ProposalDraft draft = response.Deserialize<ProposalDraft>(JsonSerializerOptions.Web);
-```
-
----
-
-## Definindo o tipo de saída
-
-Use `sealed class` ou `sealed record`. Regras:
-
-1. `[Description("...")]` **na classe/record** — descreve ao modelo o que o objeto representa. Sem isso, o modelo depende só do nome do tipo.
-2. `[JsonPropertyName("snake_case")]` **em CADA propriedade** — sem isso, o modelo pode retornar `camelCase`, `PascalCase`, ou `snake_case` dependendo do provider e da versão. Quando o provider muda, o desserializador quebra silenciosamente.
-3. Tipos de propriedade devem ser **nullable** (`string?`, `int?`) em classes; em records posicionais use nullable quando o campo pode estar ausente.
-4. Para listas: `IReadOnlyList<T>` — imutável por padrão, previne mutação acidental após desserialização.
-
-**Exemplo realista — `ProposalDraft`:**
-
-```csharp
-using System.ComponentModel;
-using System.Text.Json.Serialization;
-
-[Description("A structured commercial proposal draft")]
-public sealed record ProposalDraft(
-    [property: JsonPropertyName("headline")] string Headline,
-    [property: JsonPropertyName("client_pain_point")] string ClientPainPoint,
-    [property: JsonPropertyName("sections")] IReadOnlyList<DeliverableSection> Sections,
-    [property: JsonPropertyName("total_price")] decimal TotalPrice,
-    [property: JsonPropertyName("validity_days")] int ValidityDays);
-
-[Description("One deliverable section of a proposal")]
-public sealed record DeliverableSection(
-    [property: JsonPropertyName("title")] string Title,
-    [property: JsonPropertyName("description")] string Description);
-```
-
-> Prefer `record` sobre `class` para tipos de saída — imutável, `==` por valor, `ToString()` útil para logs. Use `class` somente se o tipo precisar de lógica de mutação pós-desserialização.
-
----
-
-## Exemplo C# completo
-
-Um agente que recebe dados de cliente e retorna um `ProposalDraft` usando Form 1 (`RunAsync<T>`):
-
-```csharp
-using System.ComponentModel;
-using System.Text.Json.Serialization;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-// --- Tipos de saída ---
-
-[Description("A structured commercial proposal draft")]
-public sealed record ProposalDraft(
-    [property: JsonPropertyName("headline")] string Headline,
-    [property: JsonPropertyName("client_pain_point")] string ClientPainPoint,
-    [property: JsonPropertyName("sections")] IReadOnlyList<DeliverableSection> Sections,
-    [property: JsonPropertyName("total_price")] decimal TotalPrice,
-    [property: JsonPropertyName("validity_days")] int ValidityDays);
-
-[Description("One deliverable section of a proposal")]
-public sealed record DeliverableSection(
-    [property: JsonPropertyName("title")] string Title,
-    [property: JsonPropertyName("description")] string Description);
-
-// --- Agente ---
-
-public sealed class ProposalDraftingAgent
-{
-    private readonly AIAgent _agent;
-
-    public ProposalDraftingAgent(ModelRegistry modelRegistry)
-    {
-        _agent = modelRegistry.GetChatClient("text-heavy").AsAIAgent(new ChatClientAgentOptions
-        {
-            Name = "ProposalDraftingAgent",
-            ChatOptions = new()
-            {
-                Instructions = """
-                    You are a senior commercial proposal specialist.
-                    Always produce a structured proposal based on the client context provided.
-                    The total_price must reflect realistic market pricing for the scope described.
-                    validity_days must be between 15 and 90.
-                    """
-            }
-        });
-    }
-
-    public async Task<ProposalDraft> DraftAsync(string clientContext, CancellationToken ct = default)
-    {
-        AgentResponse<ProposalDraft> response = await _agent.RunAsync<ProposalDraft>(
-            $"Draft a commercial proposal for the following client context:\n\n{clientContext}",
-            cancellationToken: ct);
-
-        return response.Result;
-    }
-}
-```
-
-**Consumindo `.Result`:**
-
-```csharp
-var agent = new ProposalDraftingAgent(modelRegistry);
-ProposalDraft draft = await agent.DraftAsync("Client: RetailCo. Need: Migrate 5 legacy Java services to .NET 10.");
-
-Console.WriteLine(draft.Headline);          // ex: "Modernization of RetailCo's Core Services"
-Console.WriteLine(draft.TotalPrice);        // ex: 87500.00
-Console.WriteLine(draft.Sections.Count);    // ex: 4
-```
-
-> **Model Registry alias `"text-heavy"`:** resolves to the project's configured high-quality model (ex: `gpt-4o`, `gemini-1.5-pro`, `claude-opus-4-5`). Nunca hardcode o nome do modelo — veja `ai-agents-providers-model-registry`.
-
----
-
-## Validação pós-call
-
-O JSON schema garante a **shape** da resposta, não a **semântica**. O modelo pode retornar um `TotalPrice` de `0` ou `ValidityDays` de `-1` e ainda conformar ao schema.
-
-**Sempre valide regras de negócio depois de `RunAsync<T>`:**
-
-```csharp
-public async Task<Result<ProposalDraft>> DraftValidatedAsync(string clientContext, CancellationToken ct = default)
-{
-    AgentResponse<ProposalDraft> response = await _agent.RunAsync<ProposalDraft>(
-        $"Draft a commercial proposal for:\n\n{clientContext}",
-        cancellationToken: ct);
-
-    ProposalDraft draft = response.Result;
-
-    // Validação semântica — schema não cobre isso
-    if (draft.TotalPrice <= 0)
-        return Result.Failure<ProposalDraft>("Agent returned zero or negative price.");
-
-    if (draft.ValidityDays is < 15 or > 90)
-        return Result.Failure<ProposalDraft>($"ValidityDays {draft.ValidityDays} is out of range [15, 90].");
-
-    if (draft.Sections is null || draft.Sections.Count == 0)
-        return Result.Failure<ProposalDraft>("Agent returned proposal with no deliverable sections.");
-
-    if (string.IsNullOrWhiteSpace(draft.Headline))
-        return Result.Failure<ProposalDraft>("Agent returned proposal with empty headline.");
-
-    return Result.Success(draft);
-}
-```
-
-> Se a validação falhar, você pode re-prompt com o erro como contexto, ou retornar um domain error para o caller decidir. Nunca lance exception como fluxo de controle — use `Result<T>` ou equivalente.
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Por quê é errado | Jeito certo |
-|--------------|-----------------|-------------|
-| Retornar texto livre e parsear com regex | LLM output é não-determinístico; regex quebra quando o modelo muda a formatação | Use `RunAsync<T>` com um `sealed record` tipado |
-| Usar `dynamic` ou `JsonNode` em vez de um record tipado | Perde type-safety, IntelliSense e validação em compile time; erros surgem em runtime em produção | Defina um `sealed record` com `[JsonPropertyName]` em cada propriedade |
-| Tipo de saída sem `[JsonPropertyName]` em cada propriedade | Quando o provider muda de versão ou o casing da resposta varia, `JsonSerializer` silenciosamente atribui `null` sem erro | Decore CADA propriedade com `[JsonPropertyName("snake_case")]` |
-| Confiar apenas no JSON schema para garantir corretude | Schema valida shape, não semântica — `TotalPrice = 0` e `ValidityDays = -1` são válidos no schema | Sempre valide regras de negócio após `RunAsync<T>` e retorne `Result<T>` em caso de falha |
-| Criar o `ChatClient` diretamente com model string hardcoded | Quebra troca de provider; o nome do modelo fica espalhado pelo codebase | Sempre use `_modelRegistry.GetChatClient("alias")` — veja `ai-agents-providers-model-registry` |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] Todo agente que alimenta outro sistema (front-end, banco, pipeline, outro agente) usa `RunAsync<T>` ou `ResponseFormat` — nenhum retorna `response.Text` para parsing downstream.
-- [ ] O tipo de saída é um `sealed record` ou `sealed class` decorado com `[Description("...")]`.
-- [ ] CADA propriedade do tipo de saída tem `[JsonPropertyName("...")]` explícito.
-- [ ] Validação de regras de negócio existe após `RunAsync<T>` — o resultado é verificado além da shape do schema.
-- [ ] O agente é construído a partir de `_modelRegistry.GetChatClient("alias")` — nenhum model name hardcoded.
-
----
-
-## References
-
-- `ai-agents-setup` — packages, DI, e setup mínimo de agente
-- `ai-agents-sweet-spot` — quando usar agente, quando não usar
-- `ai-agents-providers-model-registry` — como registrar e resolver modelos por alias
-- Microsoft Agent Framework docs: https://learn.microsoft.com/agent-framework/
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/structured-output.md v1.0 (2026-05-19)*
+# Structured Output — Typed agent responses
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 0 (always-load via persona maf-expert)
+> **Keywords:** structured output, typed response, response format, schema validated output, record output, JSON schema agent, RunAsync generic
+> **Read by Claude in:** implement (sempre que um agente produz saída consumida por outro sistema)
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Por que sempre Structured Output
+
+Texto livre de LLM é não-determinístico. Dois runs da mesma prompt podem retornar formatações diferentes, campos com nomes diferentes, ou dados em posições diferentes. Você não consegue plugar isso num pipeline downstream de forma confiável.
+
+Um `sealed record` tipado é um contrato: o front-end, o banco, o próximo agente sabem exatamente a shape. O runtime MAF gera o JSON Schema a partir do tipo, envia para o modelo, e deserializa o retorno automaticamente. Se o modelo devolver algo fora do schema, a call falha rápido e com mensagem clara — muito melhor que descobrir um bug de parsing em produção.
+
+**Regra prática:** 90%+ das chamadas a LLM em produção precisam de structured output. A única exceção é saída puramente textual para display final (ex: resposta de chatbot para o usuário). Se a saída vai ser lida por código, use `RunAsync<T>`.
+
+---
+
+## A API (MAF 1.0 GA)
+
+### Form 1 — `RunAsync<T>` (recomendada)
+
+```csharp
+AgentResponse<CityInfo> response = await agent.RunAsync<CityInfo>("Provide information about Tokyo.");
+CityInfo tokyo = response.Result;
+```
+
+O runtime MAF:
+1. Gera o JSON Schema a partir de `T` automaticamente.
+2. Seta `ResponseFormat` na chamada ao modelo.
+3. Deserializa a resposta JSON diretamente em `.Result`.
+
+**Use Form 1 por default.** É a forma mais simples e a que menos expõe detalhes de provider.
+
+---
+
+### Form 2 — `ChatResponseFormat.ForJsonSchema<T>()` (quando precisar de ChatOptions)
+
+```csharp
+AIAgent agent = _modelRegistry.GetChatClient("text-heavy").AsAIAgent(new ChatClientAgentOptions
+{
+    Name = "ProposalAgent",
+    ChatOptions = new()
+    {
+        Instructions = "You are a commercial proposal specialist.",
+        ResponseFormat = ChatResponseFormat.ForJsonSchema<ProposalDraft>()
+    }
+});
+
+AgentResponse response = await agent.RunAsync("Draft a proposal for a SaaS migration project.");
+ProposalDraft draft = response.Deserialize<ProposalDraft>(JsonSerializerOptions.Web);
+```
+
+**Use Form 2 quando:**
+- Você precisa setar `ResponseFormat` junto com outras `ChatOptions` (ex: temperatura, system prompt por invocação).
+- Você quer reusar o mesmo agente para múltiplos tipos de saída, trocando o format por chamada via `ChatClientAgentRunOptions`.
+
+**Setando ResponseFormat por invocação (sem recriar o agente):**
+
+```csharp
+var runOptions = new ChatClientAgentRunOptions
+{
+    ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<ProposalDraft>() }
+};
+
+AgentResponse response = await agent.RunAsync("Draft a proposal.", runOptions);
+ProposalDraft draft = response.Deserialize<ProposalDraft>(JsonSerializerOptions.Web);
+```
+
+---
+
+## Definindo o tipo de saída
+
+Use `sealed class` ou `sealed record`. Regras:
+
+1. `[Description("...")]` **na classe/record** — descreve ao modelo o que o objeto representa. Sem isso, o modelo depende só do nome do tipo.
+2. `[JsonPropertyName("snake_case")]` **em CADA propriedade** — sem isso, o modelo pode retornar `camelCase`, `PascalCase`, ou `snake_case` dependendo do provider e da versão. Quando o provider muda, o desserializador quebra silenciosamente.
+3. Tipos de propriedade devem ser **nullable** (`string?`, `int?`) em classes; em records posicionais use nullable quando o campo pode estar ausente.
+4. Para listas: `IReadOnlyList<T>` — imutável por padrão, previne mutação acidental após desserialização.
+
+**Exemplo realista — `ProposalDraft`:**
+
+```csharp
+using System.ComponentModel;
+using System.Text.Json.Serialization;
+
+[Description("A structured commercial proposal draft")]
+public sealed record ProposalDraft(
+    [property: JsonPropertyName("headline")] string Headline,
+    [property: JsonPropertyName("client_pain_point")] string ClientPainPoint,
+    [property: JsonPropertyName("sections")] IReadOnlyList<DeliverableSection> Sections,
+    [property: JsonPropertyName("total_price")] decimal TotalPrice,
+    [property: JsonPropertyName("validity_days")] int ValidityDays);
+
+[Description("One deliverable section of a proposal")]
+public sealed record DeliverableSection(
+    [property: JsonPropertyName("title")] string Title,
+    [property: JsonPropertyName("description")] string Description);
+```
+
+> Prefer `record` sobre `class` para tipos de saída — imutável, `==` por valor, `ToString()` útil para logs. Use `class` somente se o tipo precisar de lógica de mutação pós-desserialização.
+
+---
+
+## Exemplo C# completo
+
+Um agente que recebe dados de cliente e retorna um `ProposalDraft` usando Form 1 (`RunAsync<T>`):
+
+```csharp
+using System.ComponentModel;
+using System.Text.Json.Serialization;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// --- Tipos de saída ---
+
+[Description("A structured commercial proposal draft")]
+public sealed record ProposalDraft(
+    [property: JsonPropertyName("headline")] string Headline,
+    [property: JsonPropertyName("client_pain_point")] string ClientPainPoint,
+    [property: JsonPropertyName("sections")] IReadOnlyList<DeliverableSection> Sections,
+    [property: JsonPropertyName("total_price")] decimal TotalPrice,
+    [property: JsonPropertyName("validity_days")] int ValidityDays);
+
+[Description("One deliverable section of a proposal")]
+public sealed record DeliverableSection(
+    [property: JsonPropertyName("title")] string Title,
+    [property: JsonPropertyName("description")] string Description);
+
+// --- Agente ---
+
+public sealed class ProposalDraftingAgent
+{
+    private readonly AIAgent _agent;
+
+    public ProposalDraftingAgent(ModelRegistry modelRegistry)
+    {
+        _agent = modelRegistry.GetChatClient("text-heavy").AsAIAgent(new ChatClientAgentOptions
+        {
+            Name = "ProposalDraftingAgent",
+            ChatOptions = new()
+            {
+                Instructions = """
+                    You are a senior commercial proposal specialist.
+                    Always produce a structured proposal based on the client context provided.
+                    The total_price must reflect realistic market pricing for the scope described.
+                    validity_days must be between 15 and 90.
+                    """
+            }
+        });
+    }
+
+    public async Task<ProposalDraft> DraftAsync(string clientContext, CancellationToken ct = default)
+    {
+        AgentResponse<ProposalDraft> response = await _agent.RunAsync<ProposalDraft>(
+            $"Draft a commercial proposal for the following client context:\n\n{clientContext}",
+            cancellationToken: ct);
+
+        return response.Result;
+    }
+}
+```
+
+**Consumindo `.Result`:**
+
+```csharp
+var agent = new ProposalDraftingAgent(modelRegistry);
+ProposalDraft draft = await agent.DraftAsync("Client: RetailCo. Need: Migrate 5 legacy Java services to .NET 10.");
+
+Console.WriteLine(draft.Headline);          // ex: "Modernization of RetailCo's Core Services"
+Console.WriteLine(draft.TotalPrice);        // ex: 87500.00
+Console.WriteLine(draft.Sections.Count);    // ex: 4
+```
+
+> **Model Registry alias `"text-heavy"`:** resolves to the project's configured high-quality model (ex: `gpt-4o`, `gemini-1.5-pro`, `claude-opus-4-5`). Nunca hardcode o nome do modelo — veja `ai-agents-providers-model-registry`.
+
+---
+
+## Validação pós-call
+
+O JSON schema garante a **shape** da resposta, não a **semântica**. O modelo pode retornar um `TotalPrice` de `0` ou `ValidityDays` de `-1` e ainda conformar ao schema.
+
+**Sempre valide regras de negócio depois de `RunAsync<T>`:**
+
+```csharp
+public async Task<Result<ProposalDraft>> DraftValidatedAsync(string clientContext, CancellationToken ct = default)
+{
+    AgentResponse<ProposalDraft> response = await _agent.RunAsync<ProposalDraft>(
+        $"Draft a commercial proposal for:\n\n{clientContext}",
+        cancellationToken: ct);
+
+    ProposalDraft draft = response.Result;
+
+    // Validação semântica — schema não cobre isso
+    if (draft.TotalPrice <= 0)
+        return Result.Failure<ProposalDraft>("Agent returned zero or negative price.");
+
+    if (draft.ValidityDays is < 15 or > 90)
+        return Result.Failure<ProposalDraft>($"ValidityDays {draft.ValidityDays} is out of range [15, 90].");
+
+    if (draft.Sections is null || draft.Sections.Count == 0)
+        return Result.Failure<ProposalDraft>("Agent returned proposal with no deliverable sections.");
+
+    if (string.IsNullOrWhiteSpace(draft.Headline))
+        return Result.Failure<ProposalDraft>("Agent returned proposal with empty headline.");
+
+    return Result.Success(draft);
+}
+```
+
+> Se a validação falhar, você pode re-prompt com o erro como contexto, ou retornar um domain error para o caller decidir. Nunca lance exception como fluxo de controle — use `Result<T>` ou equivalente.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é errado | Jeito certo |
+|--------------|-----------------|-------------|
+| Retornar texto livre e parsear com regex | LLM output é não-determinístico; regex quebra quando o modelo muda a formatação | Use `RunAsync<T>` com um `sealed record` tipado |
+| Usar `dynamic` ou `JsonNode` em vez de um record tipado | Perde type-safety, IntelliSense e validação em compile time; erros surgem em runtime em produção | Defina um `sealed record` com `[JsonPropertyName]` em cada propriedade |
+| Tipo de saída sem `[JsonPropertyName]` em cada propriedade | Quando o provider muda de versão ou o casing da resposta varia, `JsonSerializer` silenciosamente atribui `null` sem erro | Decore CADA propriedade com `[JsonPropertyName("snake_case")]` |
+| Confiar apenas no JSON schema para garantir corretude | Schema valida shape, não semântica — `TotalPrice = 0` e `ValidityDays = -1` são válidos no schema | Sempre valide regras de negócio após `RunAsync<T>` e retorne `Result<T>` em caso de falha |
+| Criar o `ChatClient` diretamente com model string hardcoded | Quebra troca de provider; o nome do modelo fica espalhado pelo codebase | Sempre use `_modelRegistry.GetChatClient("alias")` — veja `ai-agents-providers-model-registry` |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Todo agente que alimenta outro sistema (front-end, banco, pipeline, outro agente) usa `RunAsync<T>` ou `ResponseFormat` — nenhum retorna `response.Text` para parsing downstream.
+- [ ] O tipo de saída é um `sealed record` ou `sealed class` decorado com `[Description("...")]`.
+- [ ] CADA propriedade do tipo de saída tem `[JsonPropertyName("...")]` explícito.
+- [ ] Validação de regras de negócio existe após `RunAsync<T>` — o resultado é verificado além da shape do schema.
+- [ ] O agente é construído a partir de `_modelRegistry.GetChatClient("alias")` — nenhum model name hardcoded.
+
+---
+
+## References
+
+- `ai-agents-setup` — packages, DI, e setup mínimo de agente
+- `ai-agents-sweet-spot` — quando usar agente, quando não usar
+- `ai-agents-providers-model-registry` — como registrar e resolver modelos por alias
+- Microsoft Agent Framework docs: https://learn.microsoft.com/agent-framework/
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/structured-output.md v1.0 (2026-05-19)*