Phase 14 - Lesson 14

AutoGen v0.4: Modelo de Atores e Framework de Agentes

O AutoGen v0.4 (Microsoft Research, Jan 2025) redesenhou a orquestração de agentes em torno do modelo de atores. Troca assíncrona de mensagens, agentes orientados a eventos, isolamento de falhas, concorrência natural. O framework agora está em modo de manutenção enquanto o Microsoft Agent Framework (public preview Out 2025) se torna o sucessor.

Tipo: Aprender + Construir Linguagens: Python (stdlib) Pré-requisitos: Phase 14 · 01 (Agent Loop), Phase 14 · 12 (Workflow Patterns) Tempo: ~75 minutos

Objetivos de Aprendizado

• Descrever o modelo de atores: agentes como atores, mensagens como a única IPC, isolamento de falhas por ator.
• Nomear as três camadas de API do AutoGen v0.4 — Core, AgentChat, Extensions — e para que serve cada uma.
• Explicar por que desacoplar a entrega de mensagens de seu processamento fornece isolamento de falhas e concorrência natural.
• Implementar um runtime de atores com a stdlib em Python e portar um fluxo de revisão de código de dois agentes para ele.

O Problema

A maioria dos frameworks de agentes é síncrona: um agente produz, outro agente consome, em uma pilha de chamadas. Falhas travam a pilha. A concorrência é adaptada de forma forçada. A distribuição requer reescrita de código.

A resposta do AutoGen v0.4: o modelo de atores. Cada agente é um ator com uma caixa de entrada privada. Mensagens são a única forma de interação. O runtime desacopla a entrega do processamento. As falhas são isoladas a um único ator. A concorrência é nativa. A distribuição é apenas um transporte diferente.

O Conceito

Atores

Um ator possui:

• Um estado privado (nunca acessado diretamente de fora).
• Uma caixa de entrada (fila de mensagens).
• Um handler: receive(message) -> effects onde os efeitos podem ser "responder", "enviar para outro ator", "criar novo ator", "atualizar estado", "parar a si mesmo".

Dois atores não compartilham memória. Eles só podem enviar mensagens.

Três camadas de API no AutoGen v0.4

1. Core. Framework de atores de baixo nível. AgentRuntime, Agent, Message, Topic. Troca assíncrona de mensagens, orientado a eventos.
2. AgentChat. API de alto nível orientada a tarefas (substituta para o ConversableAgent da v0.2). AssistantAgent, UserProxyAgent, RoundRobinGroupChat, SelectorGroupChat.
3. Extensions. Integrações — OpenAI, Anthropic, Azure, ferramentas, memória.

Por que o desacoplamento importa

No modelo v0.2, chamar agent_a.chat(agent_b) bloqueia o agent_a de forma síncrona até que o agent_b retorne. No v0.4, send(agent_b, msg) coloca a mensagem na caixa de entrada do agent_b e retorna. O runtime faz a entrega mais tarde. Três consequências:

• Isolamento de falhas. O travamento do Agente B não derruba o Agente A — o runtime captura a falha no handler de B e decide o que fazer (registrar log, tentar novamente, dead-letter).
• Concorrência natural. Muitas mensagens em trânsito ao mesmo tempo; os atores processam suas caixas de entrada de forma concorrente.
• Pronto para distribuição. A abstração de caixa de entrada + transporte é a mesma, seja o ator executado no mesmo processo ou em outro host.

Topologias

• RoundRobinGroupChat. Os agentes se revezam em uma rotação fixa.
• SelectorGroupChat. Um agente seletor escolhe quem fala a seguir com base no contexto da conversa.
• Magentic-One. Equipe de múltiplos agentes de referência para navegação na web, execução de código e manipulação de arquivos. Construído sobre o AgentChat.

Observabilidade

O suporte ao OpenTelemetry é integrado. Cada mensagem emite um span; as chamadas de ferramentas carregam atributos gen_ai.* de acordo com as convenções semânticas de GenAI do OTel de 2026 (Lição 23).

Status: modo de manutenção

Início de 2026: AutoGen v0.7.x é estável para pesquisa e prototipagem. A Microsoft mudou o desenvolvimento ativo para o Microsoft Agent Framework (public preview em 1 de outubro de 2025; 1.0 GA planejado para o fim do Q1 de 2026). Os padrões do AutoGen são portados facilmente — o modelo de atores é a ideia duradoura.

Construa

code/main.py implementa um runtime de atores com a stdlib:

• Message — payload tipado com sender, recipient, topic, body.
• Actor — classe abstrata com receive(message, runtime).
• Runtime — loop de eventos com uma fila compartilhada, entrega e isolamento de falhas.
• Uma demonstração com dois atores: ReviewerAgent revisa o código, ChecklistAgent executa um checklist; eles trocam mensagens até chegarem a um consenso.

Execute:

python3 code/main.py

O rastreamento mostra a entrega de mensagens, uma falha simulada em um ator que não derruba o outro e a convergência em um veredito compartilhado.

Use

• AutoGen v0.4/v0.7 (manutenção) — estável para pesquisa, prototipagem e padrões multiagente.
• Microsoft Agent Framework (public preview) — o caminho a seguir; as mesmas ideias de modelo de atores em uma API renovada.
• Topologia swarm do LangGraph (Lição 13) — padrão semelhante via transferências de ferramentas compartilhadas.
• Runtime de atores customizado — quando você precisa de um transporte específico (NATS, RabbitMQ, gRPC).

Entregue

outputs/skill-actor-runtime.md gera um runtime de atores minimalista e um modelo de equipe (RoundRobin ou Selector) para uma determinada tarefa multiagente.

Exercícios

1. Adicione uma fila de mensagens mortas (dead-letter queue): quando um handler lançar uma exceção, estacione a mensagem com falha para inspeção humana. Com que frequência a DLQ é acionada no seu brinquedo?
2. Implemente SelectorGroupChat: um ator seletor escolhe quem processa a próxima mensagem com base no estado da conversa.
3. Adicione transporte distribuído: substitua a fila interna do processo por um servidor JSON sobre HTTP para que os atores possam ser executados em processos separados.
4. Conecte um span OTel por mensagem (ou um substituto fictício). Emita gen_ai.agent.name, gen_ai.operation.name conforme a Lição 23.
5. Leia o post de arquitetura do AutoGen v0.4. Porte seu brinquedo para a API real do autogen_core. O que você ignorou que importa em produção?

Termos-Chave

Leitura Adicional

• AutoGen v0.4, Microsoft Research — o post sobre o redimensionamento
• Visão geral do LangGraph — alternativa baseada em grafos
• Convenções semânticas de GenAI do OpenTelemetry — spans que o AutoGen emite por padrão