@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/framework/standards/ai-agents/multi-agent-patterns.md

@@ -1,155 +1,211 @@
-# Multi-Agent Patterns — Composing agents
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 1 (on-keyword)
-> **Keywords:** multi-agent, agent as tool, agent composition, sequential agents, handoff, sub-agent, agent orchestration
-> **Read by Claude in:** plan (quando ai-agents-sweet-spot indica multi-agent) + implement
-
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
-
----
-
-## Quando multi-agent (e quando não)
-
-Leia `ai-agents-sweet-spot` antes de continuar. O default é **single agent**.
-
-Multi-agent só se justifica quando:
-
-1. Existem **tópicos genuinamente distintos** que um único prompt não gerencia bem (ex: classificar *e* redigir com especialização independente).
-2. Há um **handoff claro** entre responsabilidades — não apenas "dividir o código em dois agents".
-3. Um Agent-as-Tool não resolve (o sub-agent precisa ser invocado *várias vezes* ou em paralelo).
-
-> "Em dúvida → single agent. Escalate quando dói, não antes."
-
----
-
-## Agent-as-Tool (padrão recomendado)
-
-**O padrão mais simples de composição.** O agent pai decide *quando* chamar o agent filho — exatamente como chama qualquer outra tool. Não é um Workflow; sem edges, sem builders.
-
-### Caso canônico: classifier + drafter (suporte)
-
-Um `ClassifierAgent` categoriza o ticket. Um `DrafterAgent` recebe a categoria e escreve a resposta. O Drafter não precisa saber de classificação — só recebe a categoria como contexto.
-
-```csharp
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-// --- 1. Agents via Model Registry alias (nunca hardcode modelo ou provider) ---
-IChatClient chatClient = _modelRegistry.GetChatClient("text-default");
-
-AIAgent classifierAgent = chatClient.AsAIAgent(
-    instructions: "Classify the support ticket into one of: billing, technical, general. Reply with only the category.",
-    name: "ClassifierAgent");
-
-// --- 2. Expõe o classifier como tool usando .AsAIFunction() ---
-AIFunction classifierTool = classifierAgent.AsAIFunction();
-
-// --- 3. Drafter recebe o classifier como tool ---
-AIAgent drafterAgent = chatClient.AsAIAgent(
-    instructions: """
-        You are a support reply writer. When you receive a ticket:
-        1. Call ClassifierAgent to get the category.
-        2. Write a concise, professional reply appropriate for that category.
-        """,
-    name: "DrafterAgent",
-    tools: [classifierTool]);
-
-// --- 4. Executa --- o Drafter chama o Classifier automaticamente quando necessário ---
-AgentResponse response = await drafterAgent.RunAsync(ticketText);
-string reply = response.Text;
-```
-
-**Key points:**
-- `agent.AsAIFunction()` — método direto para expor um `AIAgent` local como tool.
-- Use `AIFunctionFactory.Create(...)` quando precisar sobrescrever o nome/descrição da tool ou encapsular lógica adicional ao chamar o agent.
-- O agent pai decide *se* e *quando* invocar o filho — o LLM controla o fluxo.
-- Ambos os agents usam o mesmo alias do Model Registry; podem usar aliases distintos se o caso de uso justificar.
-
----
-
-## Sequential (cadeia fixa)
-
-Quando a ordem é fixa A→B→C e cada etapa depende da anterior.
-
-**Na maioria dos casos, C# imperativo é mais simples que um Workflow:**
-
-```csharp
-// classifierAgent, drafterAgent, reviewerAgent — each built from _modelRegistry.GetChatClient(...) as shown above
-// Sem Workflow, sem builders — só chamadas encadeadas
-AgentResponse classified = await classifierAgent.RunAsync(ticketText);
-AgentResponse drafted    = await drafterAgent.RunAsync(classified.Text);
-AgentResponse reviewed   = await reviewerAgent.RunAsync(drafted.Text);
-string finalReply = reviewed.Text;
-```
-
-Use `AgentWorkflowBuilder.BuildSequential(agent1, agent2, ...)` quando precisar de **streaming de eventos** entre as etapas da cadeia (ex: exibir progresso passo a passo no front-end). Ver `ai-agents-workflows`.
-
----
-
-## Handoff (roteamento dinâmico)
-
-Um agent de triagem decide qual especialista assume o controle com base no contexto. Útil quando há N especialistas e a decisão de roteamento é complexa demais para uma tool simples.
-
-Para handoff baseado em Workflow: `AgentWorkflowBuilder.CreateHandoffBuilderWith(triageAgent).WithHandoffs(...)`. Ver `ai-agents-workflows` para o padrão completo.
-
-> Para roteamento simples (2-3 caminhos), considere Agent-as-Tool com um agent por caminho antes de ir para Handoff Workflow.
-
----
-
-## Decision tree
-
-```
-Tenho múltiplos agents — qual padrão usar?
-
-├─ Fan-in/out genuíno sobre N inputs (paralelo)?
-│   └─ Workflow (ai-agents-workflows)
-│
-├─ Ordem fixa A→B→C, cada etapa depende da anterior?
-│   ├─ Preciso de streaming de eventos entre etapas?
-│   │   └─ SIM → AgentWorkflowBuilder.BuildSequential (ai-agents-workflows)
-│   └─ NÃO → chamadas encadeadas imperativas em C#
-│
-├─ Sub-task consultada sob demanda pelo agent pai?
-│   └─ Agent-as-Tool (agent.AsAIFunction())  ← padrão mais comum
-│
-└─ Roteamento por intenção, especialistas distintos?
-    └─ Handoff (AgentWorkflowBuilder.CreateHandoffBuilderWith)
-```
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Por que é errado | O que fazer |
-|---|---|---|
-| Usar multi-agent quando um único agent resolve | Adiciona latência, custo e superfície de erro sem ganho | Single agent com tools. Ver `ai-agents-sweet-spot`. |
-| Usar Workflow quando Agent-as-Tool basta | Workflow traz edges, builders, streaming — complexidade desnecessária | `agent.AsAIFunction()` primeiro |
-| Passar histórico de conversa bruto entre agents | Output do LLM é não-determinístico; o outro agent não sabe o que fazer com histórico livre | Structured Output entre agents. Ver `ai-agents-structured-output`. |
-| Nesting profundo (agent A chama B chama C chama D) | Dificulta debug, amplifica latência, falhas em cascata | Achate a composição: Agent-as-Tool com o agent folha direto no pai. |
-| Agents com responsabilidades sobrepostas | Nenhum dos dois sabe quando agir; o LLM fica confuso | Fronteiras claras de responsabilidade; documente em `decisions.md`. |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] Foi verificado em `decisions.md` que single agent não resolve?
-- [ ] O padrão escolhido é o mais simples que atende ao requisito? (Tool < Sequential imperativo < Workflow)
-- [ ] `agent.AsAIFunction()` usado para composição local (não `AIFunctionFactory.Create` desnecessariamente)?
-- [ ] Agents usando alias do Model Registry — nenhum model string hardcoded?
-- [ ] Structured Output entre agents onde o output de um é input do outro?
-- [ ] Nesting máximo de 2 níveis (pai → filho) sem cascata profunda?
-
----
-
-## References
-
-- `ai-agents-sweet-spot` — single agent é o default; leia antes deste documento
-- `ai-agents-workflows` — Workflow (fan-in/out, Sequential com streaming, Handoff completo)
-- `ai-agents-setup` — pacotes, DI, `AsAIAgent`
-- `ai-agents-structured-output` — output tipado entre agents
-- `ai-agents-providers-model-registry` — Model Registry alias pattern
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/multi-agent-patterns.md v1.0 (2026-05-19)*
+# Multi-Agent Patterns — Composing agents
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** multi-agent, agent as tool, agent composition, sequential agents, handoff, sub-agent, agent orchestration, agente auxiliar, nesting
+> **Read by Claude in:** plan (quando ai-agents-sweet-spot indica multi-agent) + implement
+
+**Verified against:** Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08) + Microsoft.Agents.AI.Workflows 1.20.0 (**fora do pin**; versão apurada no nuget.org em 2026-09-08). **Verificação documental**, sem cláusula `provado por` — o ai-kit não compõe agentes. As assinaturas de `AgentWorkflowBuilder`/`HandoffWorkflowBuilder` e a **ausência** do atributo `[Experimental]` no Handoff foram **medidas por reflexão sobre a assembly 1.20.0** em 2026-09-08. Last-verified: 2026-09-08.
+
+---
+
+## Quando multi-agent (e quando não)
+
+Leia `ai-agents-sweet-spot` antes de continuar. O default é **single agent**.
+
+Multi-agent só se justifica quando:
+
+1. Existem **tópicos genuinamente distintos** que um único prompt não gerencia bem (ex: classificar *e* redigir com especialização independente).
+2. Há um **handoff claro** entre responsabilidades — não apenas "dividir o código em dois agents".
+3. Um Agent-as-Tool não resolve (o sub-agent precisa ser invocado *várias vezes* ou em paralelo).
+
+> "Em dúvida → single agent. Escalate quando dói, não antes."
+
+---
+
+## Agent-as-Tool (padrão recomendado)
+
+**O padrão mais simples de composição.** O agent pai decide *quando* chamar o agent filho — exatamente como chama qualquer outra tool. Não é um Workflow; sem edges, sem builders.
+
+### Caso canônico: classifier + drafter (suporte)
+
+Um `ClassifierAgent` categoriza o ticket. Um `DrafterAgent` recebe a categoria e escreve a resposta. O Drafter não precisa saber de classificação — só recebe a categoria como contexto.
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// --- 1. Agents via Model Registry alias (nunca hardcode modelo ou provider) ---
+IChatClient chatClient = _modelRegistry.GetChatClient("text-default");
+
+AIAgent classifierAgent = chatClient.AsAIAgent(
+    instructions: "Classify the support ticket into one of: billing, technical, general. Reply with only the category.",
+    name: "ClassifierAgent");
+
+// --- 2. Expõe o classifier como tool usando .AsAIFunction() ---
+AIFunction classifierTool = classifierAgent.AsAIFunction();
+
+// --- 3. Drafter recebe o classifier como tool ---
+AIAgent drafterAgent = chatClient.AsAIAgent(
+    instructions: """
+        You are a support reply writer. When you receive a ticket:
+        1. Call ClassifierAgent to get the category.
+        2. Write a concise, professional reply appropriate for that category.
+        """,
+    name: "DrafterAgent",
+    tools: [classifierTool]);
+
+// --- 4. Executa --- o Drafter chama o Classifier automaticamente quando necessário ---
+AgentResponse response = await drafterAgent.RunAsync(ticketText);
+string reply = response.Text;
+```
+
+**Key points:**
+- `agent.AsAIFunction()` — método direto para expor um `AIAgent` local como tool.
+- Use `AIFunctionFactory.Create(...)` quando precisar sobrescrever o nome/descrição da tool ou encapsular lógica adicional ao chamar o agent.
+- O agent pai decide *se* e *quando* invocar o filho — o LLM controla o fluxo.
+- Ambos os agents usam o mesmo alias do Model Registry; podem usar aliases distintos se o caso de uso justificar.
+
+---
+
+## Sequential (cadeia fixa)
+
+Quando a ordem é fixa A→B→C e cada etapa depende da anterior.
+
+**Na maioria dos casos, C# imperativo é mais simples que um Workflow:**
+
+```csharp
+// classifierAgent, drafterAgent, reviewerAgent — each built from _modelRegistry.GetChatClient(...) as shown above
+// Sem Workflow, sem builders — só chamadas encadeadas
+AgentResponse classified = await classifierAgent.RunAsync(ticketText);
+AgentResponse drafted    = await drafterAgent.RunAsync(classified.Text);
+AgentResponse reviewed   = await reviewerAgent.RunAsync(drafted.Text);
+string finalReply = reviewed.Text;
+```
+
+Use `AgentWorkflowBuilder.BuildSequential(agent1, agent2, ...)` quando precisar de **streaming de eventos** entre as etapas da cadeia (ex: exibir progresso passo a passo no front-end). Ver `ai-agents-workflows`.
+
+---
+
+## Handoff (roteamento dinâmico)
+
+Um agent de triagem decide qual especialista assume o controle com base no contexto. Útil quando há N especialistas e a decisão de roteamento é complexa demais para uma tool simples.
+
+**Status: graduou.** O Handoff era marcado experimental no 1.0 e foi anunciado como *"graduating to release"* no BUILD 2026 (2026-06-03). **Medido em 2026-09-08:** `Microsoft.Agents.AI.Workflows.HandoffWorkflowBuilder` e `AgentWorkflowBuilder` **não carregam** `[Experimental]` na assembly 1.20.0 — a graduação está no binário, não só no anúncio.
+
+Para handoff baseado em Workflow: `AgentWorkflowBuilder.CreateHandoffBuilderWith(triageAgent)`. Ver `ai-agents-workflows` para o padrão completo.
+
+**Limites documentados, e o que cada um evita** (assinaturas medidas em `HandoffWorkflowBuilderCore<TBuilder>`):
+
+| Limite | Como | O que evita |
+|---|---|---|
+| Teto de turnos | `.WithAutonomousMode(turnLimit: 8)` — aceita também `agentTurnLimits` por agente | Loop infinito de dois agentes se devolvendo a conversa |
+| Condição de término | `.WithTerminationCondition(...)` | O mesmo, por critério de conteúdo em vez de contagem |
+| `Id` estável por agente | Cada `AIAgent` com `Id` fixo (não regenerado a cada boot) | Handoff que aponta para um agente que "sumiu" entre reinícios |
+| Group chat pequeno | ≤ **3** agentes por group chat | Acima disso o gerente gasta mais turnos escolhendo quem fala do que resolvendo |
+
+> Para roteamento simples (2-3 caminhos), considere Agent-as-Tool com um agent por caminho antes de ir para Handoff Workflow.
+
+---
+
+## Agente auxiliar: em SEQUÊNCIA, nunca dentro de uma tool
+
+**Anti-padrão medido em campo.** É tentador embrulhar um agente auxiliar (resumidor, classificador, extrator) numa tool do agente principal: parece composição barata. Não é.
+
+```csharp
+// ERRADO — o auxiliar roda DENTRO da tool do principal.
+AIFunction summarize = AIFunctionFactory.Create(async (string text) =>
+{
+    var r = await _summarizerAgent.RunAsync(text);   // agente aninhado na tool
+    return r.Text;
+});
+```
+
+**Dois problemas concretos:**
+
+1. **`CallId` com tools encadeadas.** O agente auxiliar tem o próprio ciclo de tool calling. Rodando dentro da tool do principal, dois laços de function-calling se sobrepõem no mesmo turno, e a reconciliação de `CallId` entre pedido e resultado passa a depender da ordem em que os dois laços terminam.
+2. **O loop do principal fica aberto enquanto o auxiliar roda.** O principal está no meio de um turno, com uma chamada pendente, esperando algo que pode levar várias voltas de LLM. Timeout, retry e telemetria do turno principal passam a medir a soma dos dois.
+
+**O contrato correto são DUAS chamadas visíveis, em sequência:**
+
+```csharp
+// CERTO — o auxiliar roda FORA, e o resultado entra como dado no turno seguinte.
+AgentResponse summary = await _summarizerAgent.RunAsync(text);
+AgentResponse answer  = await _mainAgent.RunAsync(
+    $"Resumo do documento:
+{summary.Text}
+
+Pergunta: {question}", session);
+```
+
+Cada chamada tem o próprio span, o próprio custo e o próprio timeout — e o orquestrador é o **código**, não o modelo. É o mesmo princípio do compositor determinístico em `ai-agents-context-providers`.
+
+**A exceção, com regra:** `agent.AsAIFunction()` é a composição barata **antes** de qualquer orquestração — e serve exatamente quando o LLM principal precisa **decidir** se chama o auxiliar. Nesse caso vale o teto: **aninhamento ≤ 2 níveis** (pai → filho). Um terceiro nível é sinal de que a composição devia ser sequência no código.
+
+---
+
+## Decision tree
+
+```
+Tenho múltiplos agents — qual padrão usar?
+
+├─ Fan-in/out genuíno sobre N inputs (paralelo)?
+│   └─ Workflow (ai-agents-workflows)
+│
+├─ Ordem fixa A→B→C, cada etapa depende da anterior?
+│   ├─ Preciso de streaming de eventos entre etapas?
+│   │   └─ SIM → AgentWorkflowBuilder.BuildSequential (ai-agents-workflows)
+│   └─ NÃO → chamadas encadeadas imperativas em C#
+│
+├─ Sub-task consultada sob demanda pelo agent pai?
+│   └─ Agent-as-Tool (agent.AsAIFunction())  ← padrão mais comum
+│
+└─ Roteamento por intenção, especialistas distintos?
+    └─ Handoff (AgentWorkflowBuilder.CreateHandoffBuilderWith)
+```
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por que é errado | O que fazer |
+|---|---|---|
+| Usar multi-agent quando um único agent resolve | Adiciona latência, custo e superfície de erro sem ganho | Single agent com tools. Ver `ai-agents-sweet-spot`. |
+| Usar Workflow quando Agent-as-Tool basta | Workflow traz edges, builders, streaming — complexidade desnecessária | `agent.AsAIFunction()` primeiro |
+| Passar histórico de conversa bruto entre agents | Output do LLM é não-determinístico; o outro agent não sabe o que fazer com histórico livre | Structured Output entre agents. Ver `ai-agents-structured-output`. |
+| Nesting profundo (agent A chama B chama C chama D) | Dificulta debug, amplifica latência, falhas em cascata | Achate a composição: Agent-as-Tool com o agent folha direto no pai; teto de **2** níveis. |
+| **Agente auxiliar aninhado dentro de uma tool** | Dois laços de function-calling no mesmo turno (reconciliação de `CallId`) e o turno do principal aberto enquanto o auxiliar roda | Duas chamadas visíveis, auxiliar **em sequência**, fora da tool |
+| Handoff sem `turnLimit` nem condição de término | Dois agentes devolvem a conversa um ao outro indefinidamente | `.WithAutonomousMode(turnLimit:)` ou `.WithTerminationCondition(...)` |
+| `Id` de agente gerado a cada boot num workflow de handoff | O destino do handoff deixa de existir entre reinícios | `Id` estável, vindo de configuração |
+| Group chat com 5+ agentes | O gerente gasta os turnos escolhendo quem fala | ≤ 3 agentes; acima disso, repense a decomposição |
+| Agents com responsabilidades sobrepostas | Nenhum dos dois sabe quando agir; o LLM fica confuso | Fronteiras claras de responsabilidade; documente em `decisions.md`. |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Foi verificado em `decisions.md` que single agent não resolve?
+- [ ] O padrão escolhido é o mais simples que atende ao requisito? (Tool < Sequential imperativo < Workflow)
+- [ ] `agent.AsAIFunction()` usado para composição local (não `AIFunctionFactory.Create` desnecessariamente)?
+- [ ] Agents usando alias do Model Registry — nenhum model string hardcoded?
+- [ ] Structured Output entre agents onde o output de um é input do outro?
+- [ ] Nesting máximo de 2 níveis (pai → filho) sem cascata profunda?
+- [ ] Nenhum agente auxiliar roda dentro de uma tool de outro agente — auxiliares são chamadas em sequência, no código?
+- [ ] Todo workflow de handoff tem `turnLimit` **ou** condição de término, e os agentes têm `Id` estável?
+- [ ] Group chat (se houver) tem no máximo 3 agentes?
+
+---
+
+## References
+
+- `ai-agents-sweet-spot` — single agent é o default; leia antes deste documento
+- `ai-agents-workflows` — Workflow (fan-in/out, Sequential com streaming, Handoff completo)
+- `ai-agents-setup` — pacotes, DI, `AsAIAgent`
+- `ai-agents-structured-output` — output tipado entre agents
+- `ai-agents-providers-model-registry` — Model Registry alias pattern
+- `ai-agents-context-providers` — o compositor determinístico: o código decide o modo, o LLM classifica
+- `ai-agents-observability-patterns` — por que "uma chamada, um span" importa para medir latência
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/multi-agent-patterns.md v2.0 (2026-09-08)*