Orquestrando múltiplos agentes com o Microsoft Agent Framework: workflows em grafo e o padrão sequencial em C#

Construir um agente de IA que responde a uma pergunta é a parte fácil. O desafio real aparece quando você precisa coordenar vários agentes especializados para cumprir um processo de negócio de ponta a ponta — com controle, previsibilidade e capacidade de auditoria. É exatamente esse o problema que o Microsoft Agent Framework (MAF) ataca com seu módulo de Workflows.

Agente x Workflow: duas camadas de abstração

Antes de orquestrar, vale separar dois conceitos que a documentação oficial trata como distintos:

• Agente: guiado por um LLM, decide dinamicamente quais passos e ferramentas usar. O caminho é imprevisível por natureza.
• Workflow: uma sequência explicitamente definida de operações, que pode ter agentes como componentes. O fluxo é controlado por você, não pelo modelo.

A ideia central: use o agente para o raciocínio aberto e o workflow para amarrar esse raciocínio a um processo com topologia conhecida.

O grafo por trás de tudo

No MAF, um workflow é um grafo dirigido. Os nós são executores (executors) — unidades de processamento que recebem uma mensagem, fazem algo e emitem outra. As arestas (edges) definem como as mensagens fluem entre eles, podendo carregar condições de roteamento. Um executor pode ser um agente de IA ou código determinístico puro (validação, formatação, chamada a uma API).

A execução segue um modelo baseado em supersteps (uma variação do modelo Pregel / Bulk Synchronous Parallel). Em cada superstep, o framework coleta as mensagens pendentes, roteia para os executores-alvo, roda todos em paralelo e só avança quando todos terminam — uma barreira de sincronização. Isso garante execução determinística e checkpoints confiáveis nas fronteiras de cada superstep.

Começando: pacotes e um agente

A orquestração vive no pacote NuGet Microsoft.Agents.AI.Workflows, complementado por Microsoft.Agents.AI e Microsoft.Extensions.AI (todos em prerelease no momento). Um agente é representado pela abstração AIAgent, cuja implementação principal é a ChatClientAgent, construída sobre um IChatClient:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// chatClient é um IChatClient (Azure OpenAI, OpenAI, GitHub Models...)
AIAgent redator = new ChatClientAgent(
    chatClient,
    new ChatClientAgentOptions
    {
        Name = "Redator",
        Instructions = "Escreva um parágrafo conciso respondendo ao pedido."
    });

// Rodando o agente isoladamente
var resposta = await redator.RunAsync("Explique o que é orquestração de agentes.");
Console.WriteLine(resposta.Text);

Orquestração sequencial: o pipeline de agentes

O padrão sequencial é o mais direto: os agentes formam um pipeline, e a saída de um alimenta o próximo. É ideal para revisão de documentos, refinamento progressivo ou pipelines de tradução — casos em que cada etapa constrói sobre a anterior.

O MAF oferece um atalho de alto nível: AgentWorkflowBuilder.BuildSequential(...), que monta o grafo de pipeline a partir de uma coleção de agentes. Por padrão, cada agente enxerga a conversa completa do anterior; dá para restringir isso apenas às respostas.

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

// Agentes especializados que trabalham em cadeia
ChatClientAgent pesquisador = new(chatClient,
    "Levante os pontos-chave do tema solicitado.", "Pesquisador", "Coleta fatos");

ChatClientAgent redator = new(chatClient,
    "Transforme os pontos em um texto claro.", "Redator", "Escreve o rascunho");

ChatClientAgent revisor = new(chatClient,
    "Revise gramática e clareza do texto anterior.", "Revisor", "Revisa");

// Constrói o workflow sequencial: pesquisador -> redator -> revisor
var workflow = AgentWorkflowBuilder.BuildSequential(
    [pesquisador, redator, revisor]);

// Executa em modo streaming
var mensagens = new List<ChatMessage> {
    new(ChatRole.User, "Escreva sobre orquestração de agentes com MAF.")
};

await using StreamingRun run =
    await InProcessExecution.RunStreamingAsync(workflow, mensagens);
await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

await foreach (WorkflowEvent evt in run.WatchStreamAsync())
{
    if (evt is AgentResponseUpdateEvent atualizacao)
    {
        Console.Write(atualizacao.Update.Text);
    }
    else if (evt is WorkflowOutputEvent saida)
    {
        var resultado = saida.As<List<ChatMessage>>()!;
        Console.WriteLine($"\nConcluído com {resultado.Count} mensagens.");
        break;
    }
}

Repare no fluxo de eventos: AgentResponseUpdateEvent traz os tokens conforme são gerados (com ExecutorId identificando qual agente falou), e WorkflowOutputEvent sinaliza o resultado final. Esse modelo de eventos é o que dá observabilidade real ao pipeline.

Humano no circuito, sem esforço extra

Um diferencial prático: se um agente usa uma ferramenta sensível envolvida em ApprovalRequiredAIFunction, o workflow pausa e emite um RequestInfoEvent com um ToolApprovalRequestContent. Um operador humano aprova ou rejeita, e a execução continua — tudo pelo mesmo fluxo de eventos, sem configuração adicional.

Grafos customizados: além da linha reta

Quando você precisa de topologias que não cabem num pipeline — ramificações condicionais, fan-out/fan-in, misturar agentes com código determinístico — usa-se a API de baixo nível WorkflowBuilder, conectando executores com AddEdge:

using Microsoft.Agents.AI.Workflows;

var processador = new DataProcessor();   // executor customizado
var validador   = new Validator();
var formatador  = new Formatter();

// O executor passado ao construtor é o ponto de partida
WorkflowBuilder builder = new(processador);
builder.AddEdge(processador, validador);
builder.AddEdge(validador, formatador);
var workflow = builder.Build();

// Execução não-streaming: aguarda a conclusão
Run resultado = await InProcessExecution.RunAsync(workflow, entrada);
foreach (WorkflowEvent evt in resultado.NewEvents)
{
    if (evt is WorkflowOutputEvent saida)
        Console.WriteLine($"Resultado final: {saida.Data}");
}

Ao construir o grafo, o framework valida compatibilidade de tipos entre executores conectados, conectividade (todos alcançáveis a partir do início) e arestas duplicadas. É a “type safety” que evita erros descobertos apenas em runtime.

Regra prática: comece pelo BuildSequential para pipelines lineares; migre para o WorkflowBuilder quando precisar de roteamento condicional, paralelismo real ou executores não-LLM no meio do caminho.

Quando usar cada abordagem

• Sequencial (BuildSequential): revisão em etapas, tradução em cadeia, refinamento progressivo.
• Grafo (WorkflowBuilder): topologias fixas com fan-out/fan-in, roteamento por condição e validação estrita de mensagens.
• Checkpointing: para processos longos, o MAF salva o estado nas fronteiras dos supersteps, permitindo retomar de onde parou.

O resultado é um modelo em que você ganha a flexibilidade cognitiva dos agentes sem abrir mão do controle de um processo bem definido — a combinação que faltava para levar sistemas multiagente do protótipo à produção.

Fontes

• Microsoft Learn — Workflows Orchestrations: Sequential
• Microsoft Learn — Workflow Builder & Execution
• GitHub — microsoft/agent-framework
• .NET Blog — Introducing Microsoft Agent Framework (Preview)