@polymorphism-tech/morph-spec 6.0.0 → 7.1.0

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

@@ -1,357 +1,187 @@
-# Microsoft Agent Framework - Workflow Orchestration Patterns
+# Microsoft Agent Framework — Workflow Orchestration
 
-> **Scope:** universal
-> **Layer:** 0 (always load)
-> **Keywords:** workflow, orchestration, sequential, parallel, conditional
-> **Load When:** always
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** workflow, orchestration, fan-in, fan-out, multi-agent workflow, sequential workflow
+> **Read by Claude in:** plan (only when a genuine fan-in/out or long-running need appears)
 
-**Ref:** `setup.md` — Core setup guide (packages, ChatClientAgent, tools)
-
-Workflows compose multiple agents and executors into coordinated pipelines using `AgentWorkflowBuilder`.
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
 
 ---
 
-## Core Concepts
-
-| Concept | Description |
-|---------|-------------|
-| **Executor** | Base processing unit. Implements `IMessageHandler<T>`. Agents are executors. |
-| **Edge** | Typed connection between executors defining message flow |
-| **Workflow** | Composition of executors + edges forming a processing graph |
-| **AIAgent** | Chat-based executor (most common type) |
-
-### Packages
+## Quando NÃO usar um Workflow
 
-```xml
-<!-- Microsoft.Extensions.AI — core abstractions -->
-<PackageReference Include="Microsoft.Extensions.AI" Version="9.5.0" />
-```
+Leia `ai-agents-sweet-spot` antes de continuar. A regra:
 
-> **Note:** Workflow orchestration APIs (`AgentWorkflowBuilder`, `BuildSequential`, `CreateGroupChatBuilderWith`)
-> are part of the MAF preview that is **not yet published on NuGet**. The patterns documented here reflect
-> the expected GA surface. Until MAF ships, implement sequential/parallel workflows manually using `IChatClient`.
+> "Tudo que Workflows fazem, código C# normal faz com menos complexidade."
+> — pesquisa sweet-spot (2026-05-18)
 
----
+Checklist de desqualificação — se qualquer item for verdadeiro, **não use Workflow**:
 
-## 5 Orchestration Patterns
+- [ ] A feature tem **um tópico + uma decisão** → single agent com tools resolve
+- [ ] O fan-in pode ser escrito como `foreach` + `LINQ Aggregate` sobre os resultados → escreva o `foreach`
+- [ ] Você quer "dividir responsabilidade" entre 2 agents → use **Agent-as-Tool** (ver `ai-agents-multi-agent-patterns` — Onda 2)
+- [ ] O workflow seria Sequential de 2 etapas → é só `await agent.RunAsync(await step1.RunAsync(input))`
 
-| Pattern | Topology | Use Case | Coordination |
-|---------|----------|----------|--------------|
-| **Sequential** | Linear chain | Pipelines, multi-stage processing | Ordered, dependent |
-| **Concurrent** | Broadcast | Parallel analysis, ensemble | Independent, aggregated |
-| **GroupChat** | Star (manager hub) | Iterative refinement, review | Manager-controlled |
-| **Handoff** | Mesh | Dynamic routing, escalation | Agent-decided |
-| **Magentic** | Star (planner) | Complex generalist collaboration | Planner-based |
+Workflows adicionam: classes extras, configuração de edges, streaming de eventos, coordenação de supersteps. Adicione esse custo somente quando os critérios abaixo se aplicarem.
 
 ---
 
-## 1. Sequential Workflow
-
-Agents execute in order — each agent receives the output of the previous one.
-
-```
-[Writer] → [Editor] → [Output]
-```
-
-```csharp
-using Microsoft.Extensions.AI;
-
-AIAgent writer = new ChatClientAgent(chatClient, new ChatClientAgentOptions
-{
-    Name = "Writer",
-    Instructions = "Write stories that are engaging and creative."
-});
-
-AIAgent editor = new ChatClientAgent(chatClient, new ChatClientAgentOptions
-{
-    Name = "Editor",
-    Instructions = "Make the story more engaging, fix grammar, and enhance plot."
-});
+## Quando um Workflow É justificado
 
-Workflow workflow = AgentWorkflowBuilder.BuildSequential(writer, editor);
+| Critério | Exemplo realista |
+|----------|------------------|
+| **Fan-in genuíno sobre N inputs** | Relatório mensal que agrega análises de N documentos em paralelo |
+| **Fan-out para > 2 agents especializados independentes** | Code review: security + perf + readability ao mesmo tempo |
+| **Long-running com human-in-the-loop (HITL)** | Fluxo de aprovação onde um humano intervém entre etapas |
 
-AIAgent workflowAgent = await workflow.AsAgentAsync();
-AgentRunResponse response = await workflowAgent.RunAsync(
-    "Write a short story about a haunted house.");
-
-Console.WriteLine(response.Text);
-```
+Se sua feature não se encaixa nesses critérios, volte ao single agent.
 
 ---
 
-## 2. Concurrent Workflow (Fan-Out / Fan-In)
+## Packages
 
-Same input sent to multiple agents in parallel, results aggregated.
+Workflow APIs (`AgentWorkflowBuilder`, `WorkflowBuilder`, `InProcessExecution`) estão no pacote GA principal:
 
+```xml
+<PackageReference Include="Microsoft.Agents.AI" Version="1.0.*" />
 ```
-           ┌→ [Agent B1] →┐
-[Input] → Fan-Out → [Agent B2] → Fan-In → [Aggregator]
-           └→ [Agent B3] →┘
-```
-
-```csharp
-// Create specialized analysis agents
-AIAgent securityAnalyst = chatClient.AsAIAgent(
-    instructions: "Analyze code for security vulnerabilities.",
-    name: "SecurityAnalyst");
 
-AIAgent performanceAnalyst = chatClient.AsAIAgent(
-    instructions: "Analyze code for performance issues.",
-    name: "PerformanceAnalyst");
+Para DI helpers (`AddAIAgent`):
 
-AIAgent readabilityAnalyst = chatClient.AsAIAgent(
-    instructions: "Analyze code for readability and maintainability.",
-    name: "ReadabilityAnalyst");
-
-// Fan-out to all analysts, fan-in results
-// Use AddFanOutEdge / AddFanInEdge for custom executors
+```xml
+<PackageReference Include="Microsoft.Agents.AI.Hosting" Version="1.0.*" />
 ```
 
-**Note:** All executors in the same superstep must complete before downstream executors begin.
-
----
-
-## 3. GroupChat Workflow
-
-Manager-controlled round-robin conversation between agents.
-
-```csharp
-Workflow workflow = AgentWorkflowBuilder
-    .CreateGroupChatBuilderWith(agents =>
-        new AgentWorkflowBuilder.RoundRobinGroupChatManager(agents)
-        {
-            MaximumIterationCount = 2  // Max rounds
-        })
-    .AddParticipants(writer, editor)
-    .Build();
-
-AIAgent workflowAgent = await workflow.AsAgentAsync();
-AgentRunResponse response = await workflowAgent.RunAsync(prompt);
-```
+> Sem pacotes "preview" separados. Sem `Microsoft.Extensions.AI 9.x`. As APIs de Workflow são parte do `Microsoft.Agents.AI` 1.0 GA.
 
 ---
 
-## 4. Handoff Workflow
+## Exemplo canônico — Fan-In Concurrent
 
-Agents dynamically pass control based on routing rules. Mesh topology — no central orchestrator.
+Caso realista: analisar o mesmo documento com 3 agents especializados em paralelo, depois agregar.
 
 ```
-[Triage] ──┬→ [Math Tutor] ──→ [Triage]
-           └→ [History Tutor] → [Triage]
-```
-
-```csharp
-// Define specialized agents
-ChatClientAgent historyTutor = new(chatClient,
-    "You provide help with historical queries. Only respond about history.",
-    "history_tutor",
-    "Specialist agent for historical questions");
-
-ChatClientAgent mathTutor = new(chatClient,
-    "You provide help with math problems. Only respond about math.",
-    "math_tutor",
-    "Specialist agent for math questions");
-
-ChatClientAgent triageAgent = new(chatClient,
-    "You determine which agent to use. ALWAYS handoff to another agent.",
-    "triage_agent",
-    "Routes messages to the appropriate specialist");
-
-// Build handoff workflow
-var workflow = AgentWorkflowBuilder.StartHandoffWith(triageAgent)
-    .WithHandoffs(triageAgent, [mathTutor, historyTutor])
-    .WithHandoff(mathTutor, triageAgent)
-    .WithHandoff(historyTutor, triageAgent)
-    .Build();
+[Input] ──┬→ [SecurityAnalyst]  ──┐
+          ├→ [PerfAnalyst]       ──┤→ [Aggregator]
+          └→ [QualityAnalyst]   ──┘
 ```
 
-### Running Handoff with Streaming Events
-
 ```csharp
-List<ChatMessage> messages = new();
-messages.Add(new(ChatRole.User, "What is the derivative of x^2?"));
-
-StreamingRun run = await InProcessExecution.StreamAsync(workflow, messages);
-await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
-
-await foreach (WorkflowEvent evt in run.WatchStreamAsync())
-{
-    if (evt is AgentResponseUpdateEvent e)
-        Console.WriteLine($"{e.ExecutorId}: {e.Data}");
-    else if (evt is WorkflowOutputEvent outputEvt)
-    {
-        messages.AddRange(((List<ChatMessage>)outputEvt.Data!).Skip(messages.Count));
-        break;
-    }
-}
-```
-
-**Handoff characteristics:**
-- Receiving agent takes full task ownership
-- Full conversation history passed to receiving agent
-- Only supports `ChatAgent` with local tool execution
-
----
-
-## 5. Magentic Workflow
-
-Planner-based variant of GroupChat. A manager agent dynamically selects which agent acts next based on planning.
-
-| Aspect | GroupChat | Magentic |
-|--------|-----------|----------|
-| Turn order | Fixed (round-robin) | Dynamic (planner decides) |
-| Manager | Simple rotation | LLM-based planner |
-| Best for | Predictable workflows | Complex, adaptive tasks |
-
----
-
-## Workflow-as-Agent
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
 
-Any workflow can be encapsulated as a single agent for composition:
+// --- 1. Agents (via Model Registry — nunca hardcode o modelo) ---
+IChatClient chatClient = _modelRegistry.GetChatClient("text-default");
 
-```csharp
-Workflow workflow = AgentWorkflowBuilder.BuildSequential(writer, editor);
-AIAgent workflowAgent = await workflow.AsAgentAsync();
+AIAgent securityAnalyst = chatClient.AsAIAgent(
+    instructions: "Analyze code for security vulnerabilities. Be concise.",
+    name: "SecurityAnalyst");
 
-// Use like any other agent
-var response = await workflowAgent.RunAsync("Write a report.");
+AIAgent perfAnalyst = chatClient.AsAIAgent(
+    instructions: "Analyze code for performance bottlenecks. Be concise.",
+    name: "PerfAnalyst");
 
-// Can be composed into larger workflows
-Workflow outerWorkflow = AgentWorkflowBuilder.BuildSequential(workflowAgent, reviewer);
-```
+AIAgent qualityAnalyst = chatClient.AsAIAgent(
+    instructions: "Analyze code for readability and maintainability. Be concise.",
+    name: "QualityAnalyst");
 
----
+AIAgent aggregator = chatClient.AsAIAgent(
+    instructions: "You receive multiple analysis reports. Produce a unified summary with key findings.",
+    name: "Aggregator");
 
-## Web API Integration
+// --- 2. Build fan-out / fan-in workflow ---
+WorkflowBuilder builder = new(securityAnalyst);
+builder.AddEdge(securityAnalyst, aggregator);
 
-```csharp
-// Program.cs
-builder.AddAIAgent("Writer", (sp, key) =>
-{
-    var chatClient = sp.GetRequiredService<IChatClient>();
-    return new ChatClientAgent(chatClient, name: key,
-        instructions: "You are a creative writing assistant.");
-});
-
-builder.AddAIAgent("Editor",
-    instructions: "You improve a writer's draft.");
-
-app.MapGet("/agent/chat", async (
-    [FromKeyedServices("Writer")] AIAgent writer,
-    [FromKeyedServices("Editor")] AIAgent editor,
-    string prompt) =>
-{
-    Workflow workflow = AgentWorkflowBuilder.BuildSequential(writer, editor);
-    AIAgent workflowAgent = await workflow.AsAgentAsync();
-    var response = await workflowAgent.RunAsync(prompt);
-    return Results.Ok(response.Text);
-});
-```
+builder.AddInputEdge(perfAnalyst);          // also receives the original input
+builder.AddEdge(perfAnalyst, aggregator);
 
----
+builder.AddInputEdge(qualityAnalyst);
+builder.AddEdge(qualityAnalyst, aggregator);
 
-## Custom Executors
+builder.WithOutputFrom(aggregator);
+Workflow workflow = builder.Build();
 
-For non-agent processing steps (data transformation, external API calls):
+// --- 3. Run with streaming events ---
+string codeSnippet = /* input from request */;
+await using StreamingRun run =
+    await InProcessExecution.RunStreamingAsync(workflow, codeSnippet);
 
-```csharp
-public class PhotoCritiqueExecutor : BaseExecutor, IMessageHandler<WorkflowMessage>
+await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 {
-    public async Task HandleAsync(
-        WorkflowMessage message,
-        WorkflowContext context,
-        CancellationToken cancellationToken)
+    switch (evt)
     {
-        var client = GetVisionClient();
-        var prompt = await GetPromptAsync("critique-prompt.md");
-
-        var dataContent = new DataContent(
-            await File.ReadAllBytesAsync(message.ImagePath),
-            "image/jpeg");
-
-        var fullPrompt = new PromptBuilder()
-            .AddText(prompt)
-            .AddImage(dataContent)
-            .Build();
-
-        var response = await client.GetResponseAsync(fullPrompt);
-        await context.SendAsync(new CritiqueResult(response));
+        case AgentResponseUpdateEvent update:
+            Console.WriteLine($"[{update.Update.AuthorName}] {update.Update.Text}");
+            break;
+        case WorkflowErrorEvent error:
+            Console.Error.WriteLine($"Workflow error: {error.Exception?.Message}");
+            break;
     }
 }
 ```
 
----
-
-## Client Types
-
-| Type | Method | Input / Output | Use Case |
-|------|--------|---------------|----------|
-| Conversational | `GetConversationalClient()` | Text → Text | Chat, analysis, generation |
-| Vision | `GetVisionClient()` | Image → Text | Image analysis, OCR |
-| Image Generation | `GetImageClient()` | Text → Image | Mockups, visualizations |
+**Key points:**
+- `AddInputEdge(agent)` — agent recebe o input original (fan-out)
+- `AddEdge(from, to)` — conecta um executor ao próximo
+- `WithOutputFrom(aggregator)` — define quem produz o output final
+- O Aggregator só executa após todos os analysts completarem (superstep boundary)
+- Agents criados via Model Registry alias — não hardcode modelo ou provider
 
 ---
 
-## Prompt Engineering for Workflows
-
-Store prompts in external markdown files for:
-- Versioning without recompilation
-- Independent iteration and testing
-- Reuse across agents
+## Outros padrões — tabela de referência rápida
 
-```csharp
-var prompt = await File.ReadAllTextAsync("prompts/analysis.md");
-var agent = chatClient.AsAIAgent(instructions: prompt, name: "Analyst");
-```
+Use esta tabela para decidir qual padrão pesquisar. Não escreva código de todos aqui.
 
----
+| Padrão | Topologia | Quando usar |
+|--------|-----------|-------------|
+| **Sequential** | Cadeia linear | Pipeline simples onde cada etapa depende da anterior. Muitas vezes substituível por chamadas encadeadas. |
+| **Handoff** | Mesh dinâmico | Roteamento dinâmico — agents passam controle conforme o contexto. Ver `ai-agents-multi-agent-patterns` (Onda 2). |
+| **GroupChat** | Estrela (manager) | Refinamento iterativo entre agents com rodadas fixas. `AgentWorkflowBuilder.CreateGroupChatBuilderWith(...)`. |
+| **Magentic** | Estrela (planner LLM) | Variante de GroupChat onde o manager é um LLM que decide dinamicamente quem age. |
+| **Agent-as-Tool** | Ferramental | **Não é um Workflow** — o agent chama outro como tool via `AIFunctionFactory`. Opção mais simples; cobre 80% dos casos multi-agent. Ver `ai-agents-multi-agent-patterns` (Onda 2). |
 
-## When to Use Which Pattern
-
-| Scenario | Pattern | Why |
-|----------|---------|-----|
-| ETL / data pipeline | Sequential | Each step depends on previous |
-| Code review (security + perf + style) | Concurrent | Independent analyses |
-| Content creation + editing | GroupChat | Iterative refinement |
-| Customer support routing | Handoff | Dynamic expert selection |
-| Complex research tasks | Magentic | Adaptive planning |
-| Composing sub-workflows | Workflow-as-Agent | Abstraction |
+Para Sequential simples, `AgentWorkflowBuilder.BuildSequential(agent1, agent2)` é suficiente.
+Para Handoff, `AgentWorkflowBuilder.CreateHandoffBuilderWith(entryAgent)` + `.WithHandoffs(...)`.
 
 ---
 
-## Development Tools
+## Executando um Workflow (resumo da API)
+
+| Método | Retorno | Quando usar |
+|--------|---------|-------------|
+| `InProcessExecution.RunStreamingAsync(workflow, input)` | `StreamingRun` | Input conhecido de antemão, streama eventos |
+| `InProcessExecution.OpenStreamingAsync(workflow)` | `StreamingRun` | Input enviado depois via `TrySendMessageAsync` (ex: chat interativo) |
+| `InProcessExecution.RunAsync(workflow, input)` | `Run` | Sem streaming, acumula todos os eventos |
 
-| Tool | Purpose |
-|------|---------|
-| Mermaid diagrams | Auto-generated workflow visualization |
-| Aspire Dashboard | Trace inter-agent calls and performance |
-| `dotnet new webapi-ai` | Template: Web API with Agent Framework |
-| `dotnet new mcp-server` | Template: MCP Server |
+Sempre use `await using` no `StreamingRun` / `Run` — é `IAsyncDisposable`.
 
 ---
 
-## Checklist
+## Checklist (verifiable by morph-eval)
 
-- [ ] `Microsoft.Extensions.AI` package installed
-- [ ] Orchestration pattern selected and justified
-- [ ] Agents have clear, single responsibilities
-- [ ] Workflow built with `AgentWorkflowBuilder`
-- [ ] Streaming events handled for real-time UI
-- [ ] OpenTelemetry enabled for workflow tracing
-- [ ] Prompts stored externally (markdown files)
-- [ ] Error handling defined per executor
+- [ ] Foi verificado que um `foreach` ou single agent não resolve o problema?
+- [ ] O critério de fan-in/out genuíno ou HITL está documentado em `decisions.md`?
+- [ ] `Microsoft.Agents.AI` 1.0.* presente no `.csproj` (sem pacotes preview separados)?
+- [ ] Agents referenciando alias do Model Registry (não model strings hardcoded)?
+- [ ] `await using` no `StreamingRun` / `Run`?
+- [ ] `WorkflowErrorEvent` tratado no loop de eventos?
+- [ ] OpenTelemetry habilitado para rastrear chamadas inter-agent?
 
 ---
 
 ## References
 
-- [Workflow Orchestrations Overview](https://learn.microsoft.com/agent-framework/user-guide/workflows/orchestrations/overview)
-- [Handoff Pattern](https://learn.microsoft.com/agent-framework/user-guide/workflows/orchestrations/handoff)
-- [Agents in Workflows](https://learn.microsoft.com/agent-framework/tutorials/workflows/agents-in-workflows)
-- [GitHub Samples: Workflows](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/Workflows)
-- `setup.md` — Core setup
-- `production.md` — Middleware, A2A, MCP
+- `ai-agents-setup` — pacotes, `ChatClientAgent`, tools
+- `ai-agents-sweet-spot` — decisão single agent vs workflow
+- `ai-agents-multi-agent-patterns` (Onda 2) — Agent-as-Tool, Handoff patterns
+- `ai-agents-providers-model-registry` — Model Registry para alias de provider
+- MAF Workflows docs: https://learn.microsoft.com/agent-framework/
+- MAF Workflow samples: https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/03-workflows
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/workflows.md v2.0 (2026-05-19)*