# Microsoft Agent Framework: Guia Definitivo — Enterprise Multi-Provider

> Guia completo do Microsoft Agent Framework 1.0: a fusão do Semantic Kernel com AutoGen em um SDK unificado para .NET e Python. Tutorial passo a passo,...

Source: https://agentify.ia.br/blog/microsoft-agent-framework/

## TL;DR

O Microsoft Agent Framework 1.0 (GA em abril de 2026) é a convergência oficial do Semantic Kernel e AutoGen em um único SDK open-source para.NET e Python. Suporta múltiplos providers (Azure OpenAI, OpenAI, Claude/Anthropic, GitHub Copilot, Ollama), oferece quatro padrões de orquestração built-in (sequential, concurrent, handoff e group chat), integra-se nativamente com o Agent Governance Toolkit para enforcement de políticas determinístico, e se conecta ao Agent 365 como control plane enterprise. Se você está planejando um sistema multi-agente em ambiente corporativo, este é o framework que a Microsoft quer que você adote — e o AutoGen já entrou em maintenance mode.

---

## Overview: A Convergência que Mudou o Jogo

### De Dois Frameworks a Um SDK Unificado

Se você acompanhou o ecossistema de agentes IA da Microsoft nos últimos três anos, provavelmente sentiu uma certa confusão. De um lado, o **Semantic Kernel** — o SDK enterprise-ready com conectores para sistemas corporativos, telemetria integrada e content moderation. Do outro, o **AutoGen** — nascido no Microsoft Research, experimental, mas revolucionário nos padrões de orquestração multi-agente que inspiraram toda a comunidade.

A pergunta “devo usar SK ou AutoGen?” virou uma espécie de meme entre devs.NET e Python. Cada um tinha seus pontos fortes, mas a sobreposição era real e a divergência, incômoda.

Em outubro de 2025, a Microsoft deu o primeiro sinal claro: anunciou o Microsoft Agent Framework como um projeto que “unifica as fundações enterprise-ready do Semantic Kernel com as orquestrações inovadoras do AutoGen em um único SDK open-source.” O Release Candidate veio em dezembro de 2025, com a mensagem direta: “Agora é a hora de migrar seus projetos de Semantic Kernel e AutoGen para o Agent Framework.”

Em **3 de abril de 2026**, o General Availability 1.0 foi oficialmente lançado. AutoGen entrou em maintenance mode (apenas patches de segurança e bugs críticos). Semantic Kernel v1.77+ continua recebendo atualizações mínimas, mas toda feature nova vai para o Agent Framework.

A mensagem é inequívoca: para projetos greenfield, o Microsoft Agent Framework é o caminho.

### Agent 365: O Control Plane Enterprise

Paralelamente ao framework de desenvolvimento, a Microsoft lançou o **Agent 365** — descrito oficialmente como “o control plane para agentes IA.” Se o Agent Framework é onde você *constrói* agentes, o Agent 365 é onde a empresa *gerencia, monitora e governa* esses agentes em produção.

O Agent 365 oferece:

- **Observabilidade unificada** — telemetria, dashboards e alertas para toda a frota de agentes

- **Gestão centralizada** — rastreamento de cada agente em uso, construído ou trazido para a organização

- **Governança** — políticas de segurança aplicadas uniformemente

- **Interoperabilidade** — funciona com agentes criados em plataformas Microsoft, open-source ou third-party

A visão é clara: agentes como “funcionários digitais” que passam pelo mesmo ciclo de gestão que colaboradores humanos — deployment, permissões, monitoramento e compliance.

---

## Tutorial: Seu Primeiro Agente com Microsoft Agent Framework

Vamos colocar a mão na massa. O framework suporta.NET e Python com APIs praticamente idênticas. Vou mostrar ambos, começando pelo Python (mais acessível) e depois o equivalente em.NET.

### Pré-requisitos

- **Python 3.9+** ou **.NET 8+**

- Uma API key de qualquer provider suportado (Azure OpenAI, OpenAI, Anthropic, etc.)

- VS Code com a extensão do Agent Framework (opcional, mas recomendado pelo DevUI integrado)

### Python: Agente Básico

```
# Instale o SDK
pip install microsoft-agent-framework
```

```
import asyncio
from microsoft.agents import AIAgent, AgentKernel
from microsoft.agents.connectors import OpenAIChatClient

# Configure o kernel com o provider desejado
kernel = AgentKernel()
kernel.add_chat_client(OpenAIChatClient(
 model="gpt-4o",
 api_key="sua-api-key-aqui"
))

# Crie o agente com instruções
agent = AIAgent(
 kernel=kernel,
 name="AssistenteFinanceiro",
 instructions="""Você é um assistente financeiro especializado.
 Responda de forma clara e use dados quando disponíveis.
 Sempre cite suas fontes."""
)

# Execute
async def main():
 response = await agent.run("Quais são as melhores práticas para hedge cambial em PMEs?")
 print(response.content)

asyncio.run(main())
```

### .NET: Agente Básico

```
dotnet add package Microsoft.Agents.AI --prerelease
dotnet add package Microsoft.Agents.AI.OpenAI
```

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

// Configure o provider
var chatClient = new OpenAIChatClient(
 model: "gpt-4o",
 apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")
);

// Crie o agente
var agent = new AIAgentBuilder()
 .WithChatClient(chatClient)
 .WithName("AssistenteFinanceiro")
 .WithInstructions("""
 Você é um assistente financeiro especializado.
 Responda de forma clara e use dados quando disponíveis.
 """)
 .Build();

// Execute
var response = await agent.RunAsync("Analise o risco cambial de uma operação de importação de USD 500k.");
Console.WriteLine(response.Content);
```

### Adicionando Tools (Plugins)

O diferencial de um agente sobre um chatbot é a capacidade de *agir*. Vamos adicionar uma tool:

```
from microsoft.agents import tool

@tool(description="Busca a cotação atual de uma moeda")
async def get_exchange_rate(base_currency: str, target_currency: str) -> str:
 # Sua lógica de API aqui
 rate = await fetch_from_api(base_currency, target_currency)
 return f"1 {base_currency} = {rate} {target_currency}"

# Adicione a tool ao agente
agent = AIAgent(
 kernel=kernel,
 name="AssistenteFinanceiro",
 instructions="Você é um assistente financeiro. Use a ferramenta de câmbio quando necessário.",
 tools=[get_exchange_rate]
)
```

### Orquestrando Múltiplos Agentes

Aqui é onde o framework realmente brilha — os **orchestrators built-in** herdados do AutoGen:

```
from microsoft.agents.workflows import (
 SequentialOrchestration,
 HandoffOrchestration,
 ConcurrentOrchestration,
 GroupChatOrchestration
)

# Crie agentes especializados
pesquisador = AIAgent(kernel=kernel, name="Pesquisador",
 instructions="Pesquise dados relevantes sobre o tema solicitado.")

analista = AIAgent(kernel=kernel, name="Analista",
 instructions="Analise os dados coletados e identifique padrões e insights.")

redator = AIAgent(kernel=kernel, name="Redator",
 instructions="Redija um relatório executivo baseado na análise fornecida.")

# Orquestração Sequential: cada agente processa em sequência
pipeline = SequentialOrchestration(
 agents=[pesquisador, analista, redator]
)

result = await pipeline.run("Relatório sobre impacto da IA generativa no setor financeiro BR")
```

### Orquestração Concurrent (Paralela)

```
# Três agentes trabalham simultaneamente
concurrent = ConcurrentOrchestration(
 agents=[agente_mercado_br, agente_mercado_us, agente_mercado_eu]
)

# Todos executam em paralelo e os resultados são agregados
results = await concurrent.run("Análise de sentimento do mercado hoje")
```

### Orquestração Handoff

```
# Agentes transferem controle baseado no contexto
handoff = HandoffOrchestration(
 agents=[triagem, suporte_tecnico, suporte_financeiro, escalacao],
 entry_agent=triagem
)

# O agente de triagem decide para quem transferir
response = await handoff.run("Preciso contestar uma cobrança duplicada no meu cartão")
```

---

## Deep Dive: Providers, Orchestrators e Governança

### Multi-Provider: A Liberdade de Escolha

Um dos aspectos mais pragmáticos do Microsoft Agent Framework é o suporte nativo a múltiplos providers de LLM. Diferente de outros frameworks que nascem acoplados a um vendor específico, aqui você pode misturar providers *dentro do mesmo workflow*:

 Provider
 Status
 Uso Típico

 Azure OpenAI
 GA, integração nativa
 Workloads enterprise com compliance Azure

 OpenAI
 GA
 Acesso a modelos mais recentes

 Anthropic (Claude)
 GA
 Agentes que precisam de context windows grandes, raciocínio

 GitHub Copilot Models
 GA
 Integração com workflows de desenvolvimento

 Microsoft Foundry
 GA
 Deploy gerenciado na infraestrutura Azure

 Ollama
 GA
 Modelos locais, prototipagem, air-gapped

O devblog da Microsoft confirma explicitamente: “Compose Claude agents with other agents in sequential, concurrent, handoff, and group chat workflows using built-in orchestrators.” Ou seja, você pode ter um agente Claude fazendo análise profunda enquanto um GPT-4o faz chamadas de API e um modelo local via Ollama processa dados sensíveis on-premises.

Isso é real multi-provider, não apenas multi-model dentro do mesmo vendor.

### Os Quatro Orchestrators

Os padrões de orquestração são o coração do framework — e vêm diretamente da pesquisa do AutoGen, agora produtizados:

**1. Sequential** — Pipeline linear onde cada agente processa e passa adiante. Ideal para workflows determinísticos: pesquisa → análise → escrita → revisão.

**2. Concurrent** — Agentes executam em paralelo, resultados são agregados. Perfeito para fan-out/fan-in: múltiplas fontes de dados consultadas simultaneamente.

**3. Handoff** — Transfer de controle dinâmico baseado em contexto. O agente decide quando não é o mais adequado e transfere para outro. Padrão natural para atendimento ao cliente com escalação.

**4. Group Chat** — Conversa colaborativa multi-agente coordenada por um manager que determina quem fala e quando. Ideal para refinamento iterativo, brainstorming multi-perspectiva e code review entre agentes especializados.

Cada orchestrator suporta:

- **Checkpointing** — salva estado para retomada em caso de falha

- **Human-in-the-loop** — pausa para aprovação humana em pontos definidos

- **Type-safe routing** — tipagem forte nas interfaces entre agentes

- **Telemetria OpenTelemetry** — observabilidade de ponta a ponta

### Agent Governance Toolkit (AGT)

Se os orchestrators são o coração, o **Agent Governance Toolkit** é o sistema imunológico do ecossistema. O AGT é open-source (MIT license) e fornece:

- **Policy enforcement determinístico** — ações bloqueadas pela política são *estruturalmente impossíveis*, não apenas probabilisticamente improváveis

- **Zero-trust identity** — cada agente tem identidade verificável

- **Execution sandboxing** — code interpreter roda em containers isolados (Azure Container Apps Sandboxes)

- **SRE para agentes autônomos** — tratamento de agentes como serviços que precisam de observabilidade e incident response

O AGT trabalha com políticas declarativas em YAML:

```
# policy.yaml - Exemplo de política de governança
version: "1.0"
rules:
- name: block-external-data-exfil
 description: "Bloqueia envio de dados para endpoints externos"
 match:
 tool: "http_request"
 action: "POST"
 destination: "!*.empresa.com.br"
 decision: deny

- name: require-approval-financial
 description: "Transações financeiras requerem aprovação humana"
 match:
 tool: "payment_gateway"
 amount_above:
 decision: require_approval

- name: sandbox-code-execution
 description: "Execução de código sempre em sandbox"
 match:
 tool: "code_interpreter"
 decision: allow
 sandbox: azure_container_apps
```

O enforcement acontece em sub-milissegundo e cobre todos os 10 riscos do OWASP Agentic AI Top 10, publicado em dezembro de 2025. A integração com o Agent Framework é nativa — o AGT funciona como middleware no pipeline de execução do agente.

Como @RituWithAI resumiu no X: “Microsoft Agent Governance Toolkit — Actions the AGT kernel denies are structurally impossible.” Não é um guardrail probabilístico; é um firewall determinístico.

### Integração Azure: Do Laptop à Produção

O caminho do desenvolvimento local para produção é explicitamente mapeado pela Microsoft no que chamam de “Complete Developer Journey”:

- **Local** → Desenvolva com DevUI (debug visual, trace de cada step)

- **Test** → AG-UI para demo rápida com stakeholders

- **Deploy** → Azure Foundry Agent Service para hosting gerenciado

- **Monitor** → OpenTelemetry nativo com dashboards Azure Monitor

- **Govern** → AGT + Agent 365 para compliance e auditoria

- **Distribute** → Publique em Microsoft 365 Copilot, Teams, ou surfaces custom

O Foundry Agent Service cuida de scaling, identity, networking e lifecycle. Você escreve o agente; a infraestrutura gerencia o resto.

---

## Spider Chart: Microsoft Agent Framework vs Alternativas

Avaliação comparativa em 8 eixos (escala 1-10):

```
 Microsoft Agent Framework

 Enterprise Ready ★★★★★★★★★☆ (9/10)
 |
 Multi-Provider ★★★★★★★★★☆ (9/10)
 \ | /
 \ | /
 Governança ★★★★★★★★★★ (10/10)
 \ | /
 \ | /
 Orquestração ★★★★★★★★★☆ (9/10)
 \ | /
 \ | /
 \|/
 DX / Learning ★★★★★★★☆☆☆ (7/10)
 /|\
 / | \
 / | \
 Comunidade ★★★★★★★☆☆☆ (7/10)
 / | \
 / | \
 Flexibilidade ★★★★★★★★☆☆ (8/10)
 / | \
 Docs ★★★★★★★★★☆ (9/10)
```

 Eixo
 Score
 Justificativa

 Enterprise Ready
 9/10
 Azure-native, compliance built-in, telemetria OTel, Agent 365 control plane

 Multi-Provider
 9/10
 Azure OpenAI, OpenAI, Claude, Ollama, Foundry, GitHub Copilot

 Governança
 10/10
 AGT com enforcement determinístico, OWASP Agentic AI compliant, sandboxing

 Orquestração
 9/10
 4 padrões built-in (seq, concurrent, handoff, group chat) + custom

 DX / Learning Curve
 7/10
 Boa DX mas curva de aprendizado moderada; migração de SK/AutoGen requer esforço

 Comunidade
 7/10
 Crescendo rapidamente (herança de 75k+ stars SK+AutoGen), mas ainda consolidando

 Flexibilidade
 8/10
 Multi-linguagem, multi-provider, mas fortemente opinionado em patterns Azure

 Documentação
 9/10
 Docs excelentes, migration guides, DevUI, samples extensivos

**Score total: 68/80 (85%)**

---

## Prós e Contras

### O Que Funciona Muito Bem

- **Unificação real** — Acabou a fragmentação SK vs AutoGen. Um SDK, duas linguagens, todos os padrões

- **Multi-provider de verdade** — Misture Claude, GPT-4o e modelos locais no mesmo workflow sem gambiarras

- **Governança determinística** — O AGT não é um “please don’t do bad things” no system prompt; é enforcement estrutural

- **Caminho para produção claro** — De `pip install` ao Azure Foundry sem reescrever código

- **Backward compatibility** — Migration guides oficiais tanto de SK quanto de AutoGen; não é um “delete tudo e comece de novo”

- **Telemetria nativa** — OpenTelemetry de graça, não como afterthought

- **MCP e A2A nativos** — Interoperabilidade com o ecossistema mais amplo de agentes 2026

### Onde Dói

- **Lock-in gravitacional** — Funciona com qualquer provider, mas o caminho de menor resistência é Azure. Se você já está em AWS ou GCP, a friction é real

- **Complexidade para agentes simples** — Se você precisa de um chatbot que faz uma coisa, o boilerplate do framework pode ser overkill comparado com o OpenAI Agents SDK

- **Maturidade da comunidade** — Embora herde 75k+ stars, a comunidade *específica* do Agent Framework 1.0 ainda está se formando. StackOverflow e blogs independentes ainda são escassos comparado com LangChain

- **Breaking changes recentes** — Quem estava em SK ou AutoGen precisa migrar; quem entrou no RC teve algumas APIs mudando até o GA

- **Python como “cidadão quase igual”** — A documentação e exemplos privilegiam.NET em profundidade; Python às vezes parece um passo atrás

- **Agent 365 pricing** — O control plane enterprise não é gratuito e a precificação por agente ativo pode surpreender em escala

---

## Quando Usar (e Quando Não Usar)

### Use Microsoft Agent Framework quando:

- Você está construindo um **sistema multi-agente** onde agentes precisam coordenar, transferir contexto e colaborar

- O ambiente é **enterprise** com requisitos de compliance, auditoria e governança

- Você precisa de **multi-provider** — diferentes LLMs para diferentes tarefas no mesmo sistema

- Seu stack já inclui **.NET ou Python** e você quer um framework first-class em ambos

- Precisa de **observabilidade de ponta a ponta** com OpenTelemetry nativo

- A aplicação vai rodar no **Azure** ou precisa se integrar com Microsoft 365

- Você quer **Agent Governance Toolkit** para enforcement de políticas determinístico

### Considere alternativas quando:

- Precisa de um **agente simples** que faz uma tarefa — OpenAI Agents SDK ou Pydantic AI são mais diretos

- Seu ecossistema é **100% Python** e você quer simplicidade — LangGraph ou CrewAI podem ter menos friction

- Você está em **AWS** e quer integração nativa com Bedrock — AWS Strands Agents faz mais sentido

- Precisa de **extensibilidade radical** em TypeScript — Vercel AI SDK ou Mastra podem ser melhores

- Quer a **menor curva de aprendizado possível** — Agno ou OpenAI Agents SDK vencem nesse critério

Para uma comparação mais ampla entre frameworks, confira nosso artigo [Agent Frameworks vs Coding Agents](/blog/agent-frameworks-vs-coding-agents) e entenda [por que agentes IA morrem no piloto](/blog/por-que-agentes-ia-morrem-no-piloto).

---

## Próximos Passos

Se este guia te convenceu a explorar o Microsoft Agent Framework, aqui está o caminho recomendado:

### 1. Comece pelo Tutorial Oficial

Acesse [learn.microsoft.com/agent-framework/get-started](https://learn.microsoft.com/en-us/agent-framework/get-started/) e siga o tutorial incremental — ele adiciona um conceito por vez.

### 2. Escolha seu Provider

Para prototipar, OpenAI direto é o mais simples. Para produção enterprise, Azure OpenAI. Para contextos longos e raciocínio complexo, Claude via Anthropic connector.

### 3. Explore os Orchestrators

Implemente cada padrão com um caso de uso simples. O Sequential é o mais intuitivo; o Group Chat é o mais poderoso para problemas complexos.

### 4. Integre o AGT Desde o Dia 1

Não espere produção para pensar em governança. O AGT com políticas YAML é leve o suficiente para usar desde o desenvolvimento. Shift-left.

### 5. Monitore com OpenTelemetry

Configure exporters desde o primeiro agente. Quando o sistema crescer, você vai agradecer ter traces desde o início.

### 6. Entenda a Arquitetura de Harness

O conceito de “agent harness” (um loop em torno do modelo com tools, planning e memória) é central. O [post sobre harness e claw](https://devblogs.microsoft.com/agent-framework/meet-your-agent-harness-and-claw/) é leitura obrigatória — e dialoga diretamente com o que discutimos em [harness e loop: arquitetura de agentes](/blog/harness-e-loop-arquitetura-agentes).

### 7. Planeje a Migração

Se você tem projetos em Semantic Kernel ou AutoGen, a Microsoft oferece migration guides dedicados. O SK ainda funciona, mas novas features só vão para o Agent Framework.

---

## Conclusão

O Microsoft Agent Framework 1.0 não é apenas mais um framework de agentes — é a consolidação de três anos de pesquisa e feedback enterprise em um SDK que finalmente resolve a fragmentação do ecossistema Microsoft. A fusão Semantic Kernel + AutoGen entregou o melhor dos dois mundos: a confiabilidade enterprise de um e a inovação multi-agente do outro.

Se você está construindo agentes para contextos corporativos em 2026, este framework merece ser seu default. Não porque é da Microsoft, mas porque a combinação de multi-provider real, orchestrators produtizados, governança determinística e um caminho claro do laptop ao Azure é difícil de encontrar em um pacote único em qualquer outro lugar.

O AutoGen serviu seu propósito e o Semantic Kernel plantou as fundações. O Agent Framework colhe os frutos de ambos.

---

*Quer montar a arquitetura do seu sistema multi-agente? Agenda um papo em [ft.ia.br](https://ft.ia.br) — ajudamos empresas a ir do protótipo ao deploy enterprise com frameworks como este.*

-->