@polymorphism-tech/morph-spec 7.5.0 → 7.6.0

package/framework/standards/ai-agents/vector-data-extensions.md

@@ -0,0 +1,170 @@
+# Microsoft.Extensions.VectorData & DataIngestion — Official Vector Store Abstractions
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** microsoft extensions vectordata, vectorstorecollection, vector store abstraction, data ingestion, ingestion pipeline, semantic kernel connectors exception, pgvector connector, vectorstorewriter
+> **Read by Claude in:** plan (when choosing a RAG storage backend) + implement (when deciding whether to adopt VectorData over custom pgvector)
+
+**Verified against:** Microsoft.Extensions.VectorData.Abstractions GA (`dotnet/extensions`, transferred from the Semantic Kernel repo) + Microsoft.Extensions.DataIngestion 10.0.1-preview.1.25571.5 + Microsoft.SemanticKernel.Connectors.PgVector 1.74.0-preview. Last-verified: 2026-07-06.
+
+---
+
+## O que é
+
+`Microsoft.Extensions.VectorData.Abstractions` is the official, GA, provider-agnostic abstraction over vector stores — the vector-store equivalent of `IChatClient` for chat models. Core API:
+
+```csharp
+VectorStoreCollection<TKey, TRecord> collection = new SomeVectorStore<TKey, TRecord>(...);
+
+await collection.CreateCollectionAsync();
+await collection.UpsertAsync(record);
+
+await foreach (var result in collection.SearchAsync(queryText, top: 5))
+{
+    var record = result.Record;
+}
+```
+
+A single `VectorStoreCollection<TKey, TRecord>` shape works identically whether the backing store is in-memory, SQLite, Postgres (pgvector), Qdrant, Azure AI Search, Cosmos DB, or SQL Server — switching backends is a constructor swap, not a rewrite.
+
+`Microsoft.Extensions.DataIngestion` is a companion library (still **preview**) that provides the ETL building blocks around it: `IngestionDocumentReader` (Markdown/MarkItDown/Markdig), `IngestionChunker<T>` (header, section, `SemanticSimilarityChunker`), chunk/document enrichers (`SummaryEnricher`, `SentimentEnricher`, `KeywordEnricher`, `ImageAlternativeTextEnricher`), and `VectorStoreWriter<T>` — chained together via `IngestionPipeline<T>`.
+
+---
+
+## A pegadinha de nomenclatura (crítico — leia antes de tudo)
+
+The concrete vector-store **connectors** — the packages that actually implement `VectorStoreCollection` against a real backend — ship under `Microsoft.SemanticKernel.Connectors.*` package names (`Microsoft.SemanticKernel.Connectors.PgVector`, `.Qdrant`, `.SqlServer`, `.CosmosNoSQL`, `.InMemory`, etc.), even though `Microsoft.Extensions.VectorData.Abstractions` itself has been transferred out of the Semantic Kernel repo into `dotnet/extensions` and is fully independent of SK orchestration.
+
+Microsoft's own docs are explicit about this:
+
+> "Despite the inclusion of 'SemanticKernel' in the package names, these providers have nothing to do with Semantic Kernel and are usable anywhere in .NET, including Agent Framework." — [Data ingestion - .NET | Microsoft Learn](https://learn.microsoft.com/en-us/dotnet/ai/conceptual/data-ingestion)
+
+**Exceção explícita à regra "Forbidden" de `ai-agents-setup`:** the ban on `Microsoft.SemanticKernel.*` in `ai-agents-setup` §1/§7 targets the SK **orchestration** surface — `Kernel`, `KernelFunction`, `[KernelFunction]`, `ChatHistory`, `Kernel.InvokePromptAsync()`. It does **not** apply to `Microsoft.SemanticKernel.Connectors.*` packages when used purely as `Microsoft.Extensions.VectorData` backend connectors — those carry zero SK orchestration code. Never import the `Microsoft.SemanticKernel` core package itself; that remains forbidden.
+
+---
+
+## Maturidade atual (verificado 2026-07-06)
+
+| Package | Status |
+|---------|--------|
+| `Microsoft.Extensions.VectorData.Abstractions` | **GA** |
+| `Microsoft.Extensions.AI` / `Microsoft.Extensions.AI.Abstractions` | **GA** |
+| `Microsoft.SemanticKernel.Connectors.PgVector` (Postgres/pgvector connector) | **Prerelease** (1.74.0-preview, requires `--prerelease`) |
+| `Microsoft.SemanticKernel.Connectors.InMemory` / other connectors | Verify current status via context7/NuGet before adding — connector GA timing lags the abstractions package |
+| `Microsoft.Extensions.DataIngestion` | **Preview** (10.0.1-preview.1.25571.5) |
+
+Preview packages are subject to breaking API changes before GA (see the May 2025 rename `PostgresVectorStoreRecordCollection` → `PostgresCollection` as precedent).
+
+---
+
+## Decision matrix — custom pgvector vs VectorData
+
+| Situation | Use |
+|-----------|-----|
+| Default production RAG on Neon/Postgres (this framework's default stack) | **`ai-agents-rag-custom-pgvector`** — GA-quality, zero preview dependencies, framework-owned raw SQL, already the checklisted default |
+| Project needs genuine portability across >1 vector backend (e.g., a client contract requires swapping Postgres for Qdrant or Azure AI Search later) | `Microsoft.Extensions.VectorData` with the relevant connector — document the choice in `decisions.md` |
+| Prototyping, tests, or demos where an in-memory GA-quality store is enough | `Microsoft.Extensions.VectorData` + an in-memory/SQLite connector |
+| Team explicitly accepts a preview dependency for the Postgres connector today | Allowed, but record the acceptance + a revisit-at-GA note in `decisions.md`; do not silently swap the default |
+
+Do not migrate the existing `ai-agents-rag-custom-pgvector` implementation to the preview PgVector connector as a default — that would trade a working, GA-quality, framework-owned implementation for an unstable dependency, contradicting this framework's no-preview-by-default stance (see `ai-agents-setup` §1).
+
+---
+
+## Exemplo mínimo (backend GA — sem depender de pacote preview)
+
+```csharp
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.VectorData;
+
+// embeddingGenerator wired via the project's Model Registry `embeddings` alias
+// (see ai-agents-providers-model-registry) — any IEmbeddingGenerator works here.
+IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator = /* from Model Registry */;
+
+VectorStoreCollection<string, KnowledgeChunk> collection =
+    new SomeGaBackedVectorStore<string, KnowledgeChunk>(
+        connectionOptions,
+        "kb_chunks",
+        new VectorStoreCollectionOptions { EmbeddingGenerator = embeddingGenerator });
+
+await collection.EnsureCollectionExistsAsync();
+await collection.UpsertAsync(chunk);
+
+await foreach (var result in collection.SearchAsync(question, top: 5))
+{
+    Console.WriteLine(result.Record.Content);
+}
+
+public sealed record KnowledgeChunk
+{
+    [VectorStoreKey] public required string Id { get; init; }
+    [VectorStoreData] public required string Content { get; init; }
+    [VectorStoreVector(1536)] public required ReadOnlyMemory<float> Embedding { get; init; }
+}
+```
+
+> Replace `SomeGaBackedVectorStore` with the connector matching the chosen backend — verify its current package name and GA/preview status via context7 before adding it to a project, per the maturity table above.
+
+---
+
+## Microsoft.Extensions.DataIngestion (preview) — pipeline pattern para adoção futura
+
+Not adopted as default today (preview), but documented so a future migration is straightforward once it reaches GA:
+
+```csharp
+IngestionDocumentReader reader = new MarkdownReader();
+
+IngestionChunker<string> chunker = new SemanticSimilarityChunker(
+    embeddingGenerator,
+    new IngestionChunkerOptions(TiktokenTokenizer.CreateForModel("gpt-5")));
+
+using VectorStoreWriter<string> writer = new(vectorStore, dimensionCount: 1536);
+
+using IngestionPipeline<string> pipeline = new(reader, chunker, writer)
+{
+    ChunkProcessors = { summaryEnricher },
+};
+
+await foreach (var result in pipeline.ProcessAsync(new DirectoryInfo("./knowledge-base"), searchPattern: "*.md"))
+{
+    Console.WriteLine($"Completed '{result.DocumentId}'. Succeeded: {result.Succeeded}.");
+}
+```
+
+This maps conceptually onto the existing custom pattern: `IngestionDocumentReader` ≈ the project's document loading step, `IngestionChunker<T>` ≈ the strategies in `data-vector-search-rag-chunking`, `VectorStoreWriter<T>` ≈ `EmbeddingService` + the `kb_embeddings` insert in `ai-agents-rag-custom-pgvector`. `IngestionPipeline<T>.ProcessAsync` returns `IAsyncEnumerable<IngestionResult>` — a single document failure does not abort the whole run (partial success by design).
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Right way |
+|--------------|----------------|-----------|
+| Refusing to add `Microsoft.SemanticKernel.Connectors.PgVector` because of the "Forbidden: Microsoft.SemanticKernel.*" rule | The rule targets SK orchestration, not VectorData connectors — see the naming-trap section above | Read this standard's exception note before treating any `Microsoft.SemanticKernel.Connectors.*` package as forbidden |
+| Migrating the working custom pgvector implementation to VectorData "because it's official" | The Postgres connector is still prerelease — trades a stable implementation for an unstable one with no functional gain by default | Keep `ai-agents-rag-custom-pgvector` as the default; adopt VectorData only per the decision matrix |
+| Treating `Microsoft.Extensions.DataIngestion` as production-ready | It ships as `10.0.1-preview.1` — breaking changes are expected before GA | Track it for future adoption; do not wire it into a shipped feature today |
+| Importing `Microsoft.SemanticKernel` (the core orchestration package) to "just get the vector store types" | Pulls in the full SK orchestration surface this framework has deliberately moved away from | Import only `Microsoft.Extensions.VectorData.Abstractions` + the specific `*.Connectors.*` package needed |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] If `Microsoft.SemanticKernel.Connectors.*` appears in a `.csproj`, it is used only for `VectorStoreCollection`/`VectorStore` types — no `Kernel`, `KernelFunction`, or `ChatHistory` usage anywhere in the project.
+- [ ] No plain `Microsoft.SemanticKernel` (core) package reference.
+- [ ] If VectorData was chosen over custom pgvector, the reason is recorded in `decisions.md` per the decision matrix.
+- [ ] If a preview package (`Microsoft.SemanticKernel.Connectors.*` or `Microsoft.Extensions.DataIngestion`) was adopted, `decisions.md` records the preview-acceptance and a revisit-at-GA note.
+- [ ] Embedding model/dimensions consistent between the `VectorStoreVector(N)` attribute and the chosen embedding model.
+
+---
+
+## References
+
+- `ai-agents-rag-custom-pgvector` — the default, GA-quality custom RAG implementation this standard complements
+- `ai-agents-setup` — the `Microsoft.SemanticKernel.*` "Forbidden" rule this standard carves an exception into
+- `ai-agents-providers-model-registry` — `embeddings` alias, `IEmbeddingGenerator` wiring
+- `data-vector-search-rag-chunking` — chunk strategies (conceptual counterpart to `IngestionChunker<T>`)
+- Data ingestion - .NET | Microsoft Learn: https://learn.microsoft.com/en-us/dotnet/ai/conceptual/data-ingestion
+- AI and Vector Data Extensions GA announcement: https://devblogs.microsoft.com/dotnet/ai-vector-data-dotnet-extensions-ga/
+- Introducing Data Ingestion Building Blocks (Preview): https://devblogs.microsoft.com/dotnet/introducing-data-ingestion-building-blocks-preview/
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/vector-data-extensions.md v1.0 (2026-07-06)*

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

@@ -1,187 +1,190 @@
-# Microsoft Agent Framework — Workflow Orchestration
-
-> **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)
-
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
-
----
-
-## Quando NÃO usar um Workflow
-
-Leia `ai-agents-sweet-spot` antes de continuar. A regra:
-
-> "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**:
-
-- [ ] 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))`
-
-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.
-
----
-
-## Quando um Workflow É justificado
-
-| 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 |
-
-Se sua feature não se encaixa nesses critérios, volte ao single agent.
-
----
-
-## Packages
-
-Workflow APIs (`AgentWorkflowBuilder`, `WorkflowBuilder`, `InProcessExecution`) estão no pacote GA principal:
-
-```xml
-<PackageReference Include="Microsoft.Agents.AI" Version="1.0.*" />
-```
-
-Para DI helpers (`AddAIAgent`):
-
-```xml
-<PackageReference Include="Microsoft.Agents.AI.Hosting" Version="1.0.*" />
-```
-
-> Sem pacotes "preview" separados. Sem `Microsoft.Extensions.AI 9.x`. As APIs de Workflow são parte do `Microsoft.Agents.AI` 1.0 GA.
-
----
-
-## Exemplo canônico — Fan-In Concurrent
-
-Caso realista: analisar o mesmo documento com 3 agents especializados em paralelo, depois agregar.
-
-```
-[Input] ──┬→ [SecurityAnalyst]  ──┐
-          ├→ [PerfAnalyst]       ──┤→ [Aggregator]
-          └→ [QualityAnalyst]   ──┘
-```
-
-```csharp
-using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Workflows;
-using Microsoft.Extensions.AI;
-
-// --- 1. Agents (via Model Registry — nunca hardcode o modelo) ---
-IChatClient chatClient = _modelRegistry.GetChatClient("text-default");
-
-AIAgent securityAnalyst = chatClient.AsAIAgent(
-    instructions: "Analyze code for security vulnerabilities. Be concise.",
-    name: "SecurityAnalyst");
-
-AIAgent perfAnalyst = chatClient.AsAIAgent(
-    instructions: "Analyze code for performance bottlenecks. Be concise.",
-    name: "PerfAnalyst");
-
-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");
-
-// --- 2. Build fan-out / fan-in workflow ---
-WorkflowBuilder builder = new(securityAnalyst);
-builder.AddEdge(securityAnalyst, aggregator);
-
-builder.AddInputEdge(perfAnalyst);          // also receives the original input
-builder.AddEdge(perfAnalyst, aggregator);
-
-builder.AddInputEdge(qualityAnalyst);
-builder.AddEdge(qualityAnalyst, aggregator);
-
-builder.WithOutputFrom(aggregator);
-Workflow workflow = builder.Build();
-
-// --- 3. Run with streaming events ---
-string codeSnippet = /* input from request */;
-await using StreamingRun run =
-    await InProcessExecution.RunStreamingAsync(workflow, codeSnippet);
-
-await foreach (WorkflowEvent evt in run.WatchStreamAsync())
-{
-    switch (evt)
-    {
-        case AgentResponseUpdateEvent update:
-            Console.WriteLine($"[{update.Update.AuthorName}] {update.Update.Text}");
-            break;
-        case WorkflowErrorEvent error:
-            Console.Error.WriteLine($"Workflow error: {error.Exception?.Message}");
-            break;
-    }
-}
-```
-
-**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
-
----
-
-## Outros padrões — tabela de referência rápida
-
-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). |
-
-Para Sequential simples, `AgentWorkflowBuilder.BuildSequential(agent1, agent2)` é suficiente.
-Para Handoff, `AgentWorkflowBuilder.CreateHandoffBuilderWith(entryAgent)` + `.WithHandoffs(...)`.
-
----
-
-## 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 |
-
-Sempre use `await using` no `StreamingRun` / `Run` — é `IAsyncDisposable`.
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] 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
-
-- `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 — ai-agents/workflows.md v2.0 (2026-05-19)*
+# Microsoft Agent Framework — Workflow Orchestration
+
+> **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)
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Quando NÃO usar um Workflow
+
+Leia `ai-agents-sweet-spot` antes de continuar. A regra:
+
+> "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**:
+
+- [ ] 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))`
+
+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.
+
+---
+
+## Quando um Workflow É justificado
+
+| 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 |
+
+Se sua feature não se encaixa nesses critérios, volte ao single agent.
+
+Para o critério de HITL/long-running acima, a implementação (`RequestPort`, `CheckpointManager`, resume após restart) está em `ai-agents-durable-workflows-hitl` — leia esse standard antes de escrever o código de aprovação humana ou de checkpoint.
+
+---
+
+## Packages
+
+Workflow APIs (`AgentWorkflowBuilder`, `WorkflowBuilder`, `InProcessExecution`) estão no pacote GA principal:
+
+```xml
+<PackageReference Include="Microsoft.Agents.AI" Version="1.0.*" />
+```
+
+Para DI helpers (`AddAIAgent`):
+
+```xml
+<PackageReference Include="Microsoft.Agents.AI.Hosting" Version="1.0.*" />
+```
+
+> Sem pacotes "preview" separados. Sem `Microsoft.Extensions.AI 9.x`. As APIs de Workflow são parte do `Microsoft.Agents.AI` 1.0 GA.
+
+---
+
+## Exemplo canônico — Fan-In Concurrent
+
+Caso realista: analisar o mesmo documento com 3 agents especializados em paralelo, depois agregar.
+
+```
+[Input] ──┬→ [SecurityAnalyst]  ──┐
+          ├→ [PerfAnalyst]       ──┤→ [Aggregator]
+          └→ [QualityAnalyst]   ──┘
+```
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+// --- 1. Agents (via Model Registry — nunca hardcode o modelo) ---
+IChatClient chatClient = _modelRegistry.GetChatClient("text-default");
+
+AIAgent securityAnalyst = chatClient.AsAIAgent(
+    instructions: "Analyze code for security vulnerabilities. Be concise.",
+    name: "SecurityAnalyst");
+
+AIAgent perfAnalyst = chatClient.AsAIAgent(
+    instructions: "Analyze code for performance bottlenecks. Be concise.",
+    name: "PerfAnalyst");
+
+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");
+
+// --- 2. Build fan-out / fan-in workflow ---
+WorkflowBuilder builder = new(securityAnalyst);
+builder.AddEdge(securityAnalyst, aggregator);
+
+builder.AddInputEdge(perfAnalyst);          // also receives the original input
+builder.AddEdge(perfAnalyst, aggregator);
+
+builder.AddInputEdge(qualityAnalyst);
+builder.AddEdge(qualityAnalyst, aggregator);
+
+builder.WithOutputFrom(aggregator);
+Workflow workflow = builder.Build();
+
+// --- 3. Run with streaming events ---
+string codeSnippet = /* input from request */;
+await using StreamingRun run =
+    await InProcessExecution.RunStreamingAsync(workflow, codeSnippet);
+
+await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+{
+    switch (evt)
+    {
+        case AgentResponseUpdateEvent update:
+            Console.WriteLine($"[{update.Update.AuthorName}] {update.Update.Text}");
+            break;
+        case WorkflowErrorEvent error:
+            Console.Error.WriteLine($"Workflow error: {error.Exception?.Message}");
+            break;
+    }
+}
+```
+
+**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
+
+---
+
+## Outros padrões — tabela de referência rápida
+
+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). |
+
+Para Sequential simples, `AgentWorkflowBuilder.BuildSequential(agent1, agent2)` é suficiente.
+Para Handoff, `AgentWorkflowBuilder.CreateHandoffBuilderWith(entryAgent)` + `.WithHandoffs(...)`.
+
+---
+
+## 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 |
+
+Sempre use `await using` no `StreamingRun` / `Run` — é `IAsyncDisposable`.
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] 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
+
+- `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
+- `ai-agents-durable-workflows-hitl` — `RequestPort`, `CheckpointManager`, resume após restart
+- 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 — ai-agents/workflows.md v2.0 (2026-05-19)*