@polymorphism-tech/morph-spec 8.29.0 → 8.32.0

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

@@ -1,155 +1,155 @@
-# 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
+> **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)*