Multi-Agent | The .NET Blog

O Padrão Handoff: Quando Um Agente Não É Suficiente

Emiliano Montesdeoca — Mon, 01 Jun 2026 00:00:00 +0000

Em algum momento, todo sistema multi-agente supera um roteador simples. O primeiro sinal é geralmente quando um agente especialista precisa fazer uma pergunta de acompanhamento, ou percebe no meio do turno que outro agente deveria continuar. Um pipeline fixo falha aí. Um roteador de passagem única falha aí.

Exatamente para isso é que o padrão de orquestração Handoff no Microsoft Agent Framework foi projetado.

Como Handoff Funciona

O desenvolvedor declara um grafo: aqui estão os agentes, aqui estão as arestas entre eles. O framework faz o resto — sintetiza uma ferramenta handoff por aresta de saída e a injeta em cada agente. Quando um agente decide passar o controle, ele chama a ferramenta. O framework aplica a topologia.

Três coisas tornam isso diferente de simplesmente fazer com que os agentes se chamem:

Uma transcrição compartilhada — o agente receptor vê o histórico completo da conversa. Sem começar do zero.
Aplicação de topologia — um agente só pode fazer handoff para destinos declarados. Bugs de roteamento são detectados no momento de criação, não em produção.
Terminação natural — quando o agente ativo termina seu turno sem chamar uma ferramenta de handoff, o fluxo de trabalho cede ao usuário. Sem polling, sem condições de saída explícitas.

Um Exemplo Mínimo

Em .NET, construir um fluxo de trabalho handoff fica assim:

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

AIAgent triage = chatClient.AsAIAgent(
 instructions: "Route to the right specialist.",
 name: "Triage");

AIAgent billing = chatClient.AsAIAgent(
 instructions: "Handle billing questions.",
 name: "Billing");

AIAgent tech = chatClient.AsAIAgent(
 instructions: "Handle technical support.",
 name: "Tech");

var workflow = HandoffWorkflow.Create()
 .Add(triage, targets: [billing, tech])
 .Add(billing, targets: [triage])
 .Add(tech, targets: [triage, billing]);

Triagem pode enviar para qualquer especialista. Ambos os especialistas podem enviar de volta para triagem. O grafo é compatível com acíclico, mas suporta arestas de retorno quando você as precisa (“preciso de mais informações” → de volta à pesquisa).

Quando Usar Handoff (e Quando Não)

Handoff é uma boa escolha quando:

A propriedade pode mudar no meio da conversa — um agente pode perceber que é o especialista errado
Arestas de retorno importam — você pode precisar revisitar um passo anterior sem reiniciar
As decisões de roteamento são difusas — a decisão de fazer handoff é contextual e melhor tomada pelo modelo do que por predicados tipados

Não é a escolha certa quando:

Seu pipeline é fixo e sequencial — use o fluxo de trabalho Sequential para isso
Cada passo é independente — agentes compartilhando uma transcrição onde apenas um deles precisava dela é apenas ruído
Você precisa de garantias rígidas de processamento — o não-determinismo do roteamento orientado por modelo não é o que você quer

Arestas de Retorno e Human-in-the-Loop

Uma das formas mais interessantes que o Handoff permite são as arestas de retorno genuínas. Um agente pode decidir “não tenho informações suficientes” e rotear de volta para um passo de pesquisa, não com um loop codificado, mas porque o modelo decide que é a decisão certa.

As interações human-in-the-loop também se compõem naturalmente. Quando um especialista precisa de entrada do usuário, o fluxo de trabalho cede de volta ao usuário via o loop de turno padrão, coleta a resposta e retoma com contexto completo. O agente nunca perdeu a conversa.

Conclusão

Handoff é um desses padrões que parece simples, mas permite muito uma vez que você o internaliza: roteamento descentralizado, contexto compartilhado, topologia aplicada, terminação natural. É o próximo passo certo quando seus agentes começam a dizer “na verdade, alguém mais deveria lidar com isso.”

Leia o passo a passo completo no post original: A Tour of the Handoff Orchestration Pattern

Construindo UIs Multi-Agente em Tempo Real Que Não Parecem uma Caixa Preta

Emiliano Montesdeoca — Fri, 10 Apr 2026 00:00:00 +0000

Este post foi traduzido automaticamente. Para a versão original, clique aqui.

A questão com sistemas multi-agente é a seguinte: eles ficam incríveis nas demos. Três agentes passando trabalho entre si, resolvendo problemas, tomando decisões. Aí você tenta colocar na frente de usuários reais e… silêncio. Um indicador girando. Nenhuma ideia de qual agente está fazendo o quê ou por que o sistema pausou. Isso não é um produto — é um problema de confiança.

O time do Microsoft Agent Framework acabou de publicar um tutorial fantástico sobre como combinar fluxos MAF com AG-UI, um protocolo aberto para transmitir eventos de execução de agentes para um frontend via Server-Sent Events. E sinceramente? Essa é a ponte que estava faltando.

Por que isso importa para desenvolvedores .NET

Se você está construindo apps com IA, provavelmente já bateu nesse muro. Sua orquestração backend funciona perfeitamente — agentes passam tarefas entre si, ferramentas disparam, decisões são tomadas. Mas o frontend não faz ideia do que está acontecendo nos bastidores. AG-UI resolve isso definindo um protocolo padrão para transmitir eventos de agentes (pense em RUN_STARTED, STEP_STARTED, TOOL_CALL_*, TEXT_MESSAGE_*) diretamente para sua camada de UI via SSE.

A demo que construíram é um fluxo de suporte ao cliente com três agentes: um agente de triagem que roteia solicitações, um agente de reembolso que cuida de questões financeiras, e um agente de pedidos que gerencia substituições. Cada agente tem suas próprias ferramentas, e a topologia de handoff é definida explicitamente — nada de “descubra a partir do prompt”.

A topologia de handoff é a verdadeira estrela

O que me chamou a atenção é como o HandoffBuilder permite declarar um grafo dirigido de roteamento entre agentes:

builder = HandoffBuilder(
 name="ag_ui_handoff_workflow_demo",
 participants=[triage, refund, order],
 termination_condition=termination_condition,
)

(
 builder
 .add_handoff(triage, [refund], description="Refunds, damaged-item claims...")
 .add_handoff(triage, [order], description="Replacement, exchange...")
 .add_handoff(refund, [order], description="Replacement logistics needed after refund.")
 .add_handoff(order, [triage], description="After replacement/shipping tasks complete.")
)

Cada add_handoff cria uma aresta dirigida com uma descrição em linguagem natural. O framework gera ferramentas de handoff para cada agente baseado nessa topologia. Então as decisões de roteamento são fundamentadas na sua estrutura de orquestração, não apenas no que o LLM resolve fazer. Isso é enorme para confiabilidade em produção.

Human-in-the-loop que realmente funciona

A demo mostra dois padrões de interrupção que qualquer app de agentes do mundo real precisa:

Interrupções de aprovação de ferramentas — quando um agente chama uma ferramenta marcada com approval_mode="always_require", o fluxo pausa e emite um evento. O frontend renderiza um modal de aprovação com o nome da ferramenta e seus argumentos. Sem loops de retry queimando tokens — apenas um fluxo limpo de pausa-aprovação-retomada.

Interrupções de solicitação de informação — quando um agente precisa de mais contexto do usuário (como um ID de pedido), ele pausa e pergunta. O frontend mostra a pergunta, o usuário responde, e a execução retoma exatamente de onde parou.

Ambos os padrões são transmitidos como eventos AG-UI padrão, então seu frontend não precisa de lógica personalizada por agente — simplesmente renderiza qualquer evento que chegue pela conexão SSE.

Conectar tudo é surpreendentemente simples

A integração entre MAF e AG-UI é uma única chamada de função:

from agent_framework.ag_ui import (
 AgentFrameworkWorkflow,
 add_agent_framework_fastapi_endpoint,
)

app = FastAPI()

demo_workflow = AgentFrameworkWorkflow(
 workflow_factory=lambda _thread_id: create_handoff_workflow(),
 name="ag_ui_handoff_workflow_demo",
)

add_agent_framework_fastapi_endpoint(
 app=app, agent=demo_workflow, path="/handoff_demo",
)

O workflow_factory cria um fluxo novo por thread, então cada conversa tem estado isolado. O endpoint cuida de toda a tubulação SSE automaticamente. Se você já usa FastAPI (ou pode adicioná-lo como uma camada leve), isso tem praticamente zero fricção.

Minha opinião

Para nós desenvolvedores .NET, a pergunta imediata é: “Posso fazer isso em C#?” O Agent Framework está disponível para .NET e Python, e o protocolo AG-UI é agnóstico de linguagem (é apenas SSE). Então embora essa demo específica use Python e FastAPI, o padrão se traduz diretamente. Você poderia montar uma API mínima ASP.NET Core com endpoints SSE seguindo o mesmo schema de eventos AG-UI.

A conclusão mais importante é que UIs multi-agente estão se tornando uma preocupação de primeira classe, não algo deixado para depois. Se você está construindo qualquer coisa onde agentes interagem com humanos — suporte ao cliente, fluxos de aprovação, processamento de documentos — essa combinação de orquestração MAF e transparência AG-UI é o padrão a seguir.

Concluindo

AG-UI + Microsoft Agent Framework te dá o melhor dos dois mundos: orquestração multi-agente robusta no backend e visibilidade em tempo real no frontend. Sem mais interações de agentes como caixas pretas.

Confira o tutorial completo e o repositório do protocolo AG-UI para se aprofundar.

Microsoft Agent Framework Chega à 1.0 — Eis O Que Realmente Importa para Desenvolvedores .NET

Emiliano Montesdeoca — Fri, 03 Apr 2026 00:00:00 +0000

Este post foi traduzido automaticamente. Para a versão original, clique aqui.

Se você tem acompanhado a jornada do Agent Framework desde os primeiros dias do Semantic Kernel e AutoGen, este é significativo. O Microsoft Agent Framework acabou de chegar à versão 1.0 — pronto para produção, APIs estáveis, compromisso de suporte de longo prazo. Está disponível tanto para .NET quanto para Python, e está genuinamente pronto para cargas de trabalho reais.

Vou cortar o ruído do anúncio e focar no que importa se você está construindo apps com IA usando .NET.

A versão curta

Agent Framework 1.0 unifica o que costumava ser Semantic Kernel e AutoGen em um único SDK open source. Uma abstração de agente. Um motor de orquestração. Múltiplos provedores de IA. Se você estava alternando entre Semantic Kernel para padrões enterprise e AutoGen para workflows multi-agente de nível pesquisa, pode parar. Este é o único SDK agora.

Começar é quase injustamente simples

Aqui está um agente funcional em .NET:

// dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;
using Azure.Identity;

var agent = new AIProjectClient(endpoint: "https://your-project.services.ai.azure.com")
 .GetResponsesClient("gpt-5.3")
 .AsAIAgent(
 name: "HaikuBot",
 instructions: "You are an upbeat assistant that writes beautifully."
 );

Console.WriteLine(await agent.RunAsync("Write a haiku about shipping 1.0."));

É isso. Um punhado de linhas e você tem um agente de IA rodando contra o Azure Foundry. O equivalente em Python é igualmente conciso. Adicione ferramentas de funções, conversas multi-turno e streaming conforme avança — a superfície da API escala sem ficar estranha.

Orquestração multi-agente — isso é pra valer

Agentes individuais são bons para demos, mas cenários de produção geralmente precisam de coordenação. Agent Framework 1.0 vem com padrões de orquestração testados em batalha diretamente da Microsoft Research e AutoGen:

Sequencial — agentes processam em ordem (escritor → revisor → editor)
Concorrente — distribui para múltiplos agentes em paralelo, converge resultados
Handoff — um agente delega para outro baseado na intenção
Chat em grupo — múltiplos agentes discutem e convergem para uma solução
Magentic-One — o padrão multi-agente de nível pesquisa do MSR

Todos suportam streaming, checkpointing, aprovações com humano no loop, e pausa/retomada. A parte de checkpointing é crucial — workflows de longa duração sobrevivem a reinícios de processo. Para nós desenvolvedores .NET que construímos workflows duráveis com Azure Functions, isso é familiar.

As funcionalidades que mais importam

Aqui está minha lista do que vale a pena saber:

Hooks de middleware. Sabe como o ASP.NET Core tem pipelines de middleware? Mesmo conceito, mas para execução de agentes. Intercepte cada estágio — adicione segurança de conteúdo, logging, políticas de compliance — sem tocar nos prompts do agente. É assim que você torna agentes prontos para enterprise.

Memória plugável. Histórico conversacional, estado persistente chave-valor, recuperação baseada em vetores. Escolha seu backend: Foundry Agent Service, Mem0, Redis, Neo4j, ou crie o seu próprio. Memória é o que transforma uma chamada LLM sem estado em um agente que realmente lembra do contexto.

Agentes YAML declarativos. Defina as instruções do seu agente, ferramentas, memória e topologia de orquestração em arquivos YAML versionados. Carregue e execute com uma única chamada de API. Isso é um divisor de águas para equipes que querem iterar no comportamento do agente sem reimplantar código.

Suporte A2A e MCP. MCP (Model Context Protocol) permite que agentes descubram e invoquem ferramentas externas dinamicamente. A2A (protocolo Agent-to-Agent) habilita colaboração entre runtimes — seus agentes .NET podem se coordenar com agentes rodando em outros frameworks. O suporte ao A2A 1.0 está chegando em breve.

As funcionalidades em preview que valem acompanhar

Algumas funcionalidades foram lançadas como preview na 1.0 — funcionais mas as APIs podem evoluir:

DevUI — um depurador local baseado em navegador para visualizar a execução do agente, fluxos de mensagens e chamadas de ferramentas em tempo real. Pense no Application Insights, mas para o raciocínio do agente.
GitHub Copilot SDK e Claude Code SDK — use o Copilot ou Claude como harness de agente diretamente do seu código de orquestração. Componha um agente capaz de programar ao lado dos seus outros agentes no mesmo workflow.
Agent Harness — um runtime local customizável que dá aos agentes acesso a shell, sistema de arquivos e loops de mensagens. Pense em agentes de código e padrões de automação.
Skills — pacotes reutilizáveis de capacidades de domínio que dão aos agentes capacidades estruturadas prontas para uso.

Migrando do Semantic Kernel ou AutoGen

Se você tem código existente de Semantic Kernel ou AutoGen, existem assistentes de migração dedicados que analisam seu código e geram planos de migração passo a passo. O guia de migração do Semantic Kernel e o guia de migração do AutoGen te guiam por tudo.

Se você estava nos pacotes RC, atualizar para 1.0 é apenas uma mudança de versão.

Finalizando

Agent Framework 1.0 é o marco de produção que as equipes enterprise estavam esperando. APIs estáveis, suporte multi-provedor, padrões de orquestração que realmente funcionam em escala, e caminhos de migração tanto do Semantic Kernel quanto do AutoGen.

O framework é totalmente open source no GitHub, e você pode começar hoje com dotnet add package Microsoft.Agents.AI. Confira o guia de início rápido e os exemplos para colocar a mão na massa.

Se você estava esperando o sinal de “seguro para usar em produção” — é este.