O AutoGen da Microsoft foi, durante quase dois anos, uma das referências incontornáveis quando se falava em agentes de IA que conversam entre si para resolver tarefas complexas. Mas em 2026 esse nome partiu-se em três caminhos distintos, e um deles, o AG2, tornou-se o sucessor open source mais ativo do projeto original. Este tutorial mostra, passo a passo, como instalar o AG2, construir agentes conversáveis, orquestrar um GroupChat com vários agentes e levar tudo isso para produção com Docker.
Se já experimentou o AutoGen original, vai reconhecer grande parte da sintaxe usada aqui, porque o AG2 foi desenhado precisamente para manter essa compatibilidade. Se está a começar do zero, este guia assume apenas conhecimento básico de Python e não exige experiência prévia com nenhum outro framework de agentes, seja CrewAI, LangGraph ou Model Context Protocol, embora o AG2 possa, mais tarde, ser combinado com qualquer um destes.
O Que é o AG2 e Porque o AutoGen da Microsoft Está a Desaparecer
O AutoGen nasceu na Microsoft Research como um projeto para programar sistemas de agentes de IA capazes de conversar entre si, executar código e resolver tarefas em conjunto. Chi Wang, um dos cofundadores, explicou numa publicação pública que o objetivo inicial, junto com a professora Qingyun Wu da Penn State University, era criar uma base de código aberto para a programação agêntica, pensada para resolver problemas reais de forma colaborativa. Esse projeto cresceu rápido: o repositório oficial da Microsoft chegou a mais de 61 mil estrelas no GitHub, segundo dados recolhidos pela IntelligentTools, mas o último push de código significativo nesse repositório aconteceu a 15 de abril de 2026, sinal de que entrou em modo de manutenção.
Enquanto isso, a comunidade que rodeava o projeto decidiu continuar a desenvolvê-lo fora da alçada direta da Microsoft. Nasceu assim o AG2, hospedado na organização ag2ai no GitHub, com licença Apache 2.0 e um modelo de governação aberta que junta membros de várias empresas e universidades. Wang descreveu a transição como algo que vai muito além de uma simples troca de nome: “Esta não é apenas uma remodelação, é uma reinvenção”, escreveu na altura do anúncio. Em paralelo, a própria Microsoft lançou um sucessor oficial, o Agent Framework, que combina conceitos do AutoGen com as capacidades empresariais do Semantic Kernel.
Em meados de outubro de 2026 o AG2 somava cerca de 5 mil estrelas no GitHub, com 745 forks, 23 issues abertas e 58 pull requests ativos, segundo o painel público da organização ag2ai no GitHub. O ritmo de lançamentos também não parou: a versão 1.1.2 saiu a 3 de outubro de 2026 e a versão 1.2.0 chegou apenas oito dias depois, a 11 de outubro. É este projeto, ativo e em evolução rápida, que vamos instalar e usar neste guia.
Pré-requisitos e Versões Necessárias
Antes de avançar, confirme que tem os seguintes componentes instalados e configurados. O AG2 é uma biblioteca Python, por isso a maior parte dos requisitos giram em torno do ecossistema Python e de uma chave de API para o modelo de linguagem que vai usar.
| Requisito | Versão ou detalhe | Observação |
|---|---|---|
| Python | 3.10 ou mais recente | Confirme a versão mínima exata no guia oficial de arranque rápido do AG2 antes de instalar |
| pip | 23 ou superior | Atualize com python -m pip install --upgrade pip |
| Pacote ag2 | 1.1.2 (PyPI) / v1.2.0 (GitHub) | O PyPI ficou um lançamento atrás do GitHub à data deste artigo |
| Chave de API LLM | OpenAI, Azure OpenAI, Anthropic ou modelo local | Necessária para os agentes conseguirem gerar respostas |
| Docker Desktop | Versão atual estável | Opcional, mas recomendado para executar código gerado pelo LLM em isolamento |
| Editor de código | VS Code ou equivalente | Facilita a depuração dos scripts Python |
| Sistema operativo | Windows 10/11, macOS 12+ ou Linux Ubuntu 20.04+ | AG2 corre em qualquer um destes |
Vale notar uma particularidade importante: como o AG2 é um fork do AutoGen original, ainda existe no PyPI o pacote antigo chamado pyautogen, além do próprio autogen mantido pela Microsoft. Instalar o pacote errado é, de longe, o erro mais comum entre quem começa a usar esta ferramenta, e vamos falar disso em detalhe mais à frente.
Passo 1: Preparar o Ambiente Python
Comece por criar um ambiente virtual isolado para este projeto. Isto evita conflitos entre as dependências do AG2 e outras bibliotecas que já tenha instaladas no sistema, um cuidado especialmente importante dado que vários frameworks de agentes de IA partilham nomes de pacotes semelhantes.
mkdir projeto-ag2
cd projeto-ag2
python3 -m venv venv
# Linux ou macOS
source venv/bin/activate
# Windows (PowerShell)
venv\Scripts\Activate.ps1
python -m pip install --upgrade pipDepois de ativar o ambiente virtual, o terminal deve mostrar o prefixo (venv) antes do caminho atual. Isto confirma que qualquer pacote instalado a partir daqui fica contido dentro da pasta do projeto, sem afetar outras instalações Python no mesmo computador.
Passo 2: Instalar o AG2 e as Dependências
Com o ambiente ativo, instale o pacote ag2 diretamente do PyPI. Se tiver o pacote antigo pyautogen instalado em qualquer ambiente anterior, remova-o primeiro para evitar que as duas bibliotecas entrem em conflito ao registarem o mesmo espaço de nomes.
pip uninstall pyautogen -y
pip install ag2
# Para usar o executor de código com Docker
pip install "ag2[docker]"
# Confirmar a instalação
python -c "import autogen; print(autogen.__file__)"O comando final confirma onde o pacote foi instalado. Note que, mesmo chamando-se ag2 no PyPI, o módulo Python que se importa continua a chamar-se autogen, uma decisão deliberada da equipa para manter compatibilidade com o código escrito para a versão anterior do projeto.
Passo 3: Configurar a Chave de API do Modelo de Linguagem
O AG2 não vem com nenhum modelo embutido: ele orquestra chamadas a modelos de linguagem externos, seja a API da OpenAI, Azure OpenAI, Anthropic, ou um modelo local servido via Ollama ou outro backend compatível com a API da OpenAI. A forma mais limpa de configurar isto é através de um ficheiro JSON com a lista de configurações de modelo.
{
"config_list": [
{
"model": "gpt-4o-mini",
"api_key": "SUBSTITUA_PELA_SUA_CHAVE_AQUI"
}
]
}Guarde este conteúdo num ficheiro chamado OAI_CONFIG_LIST.json na raiz do projeto. Nunca escreva a chave diretamente no código Python que vai partilhar ou versionar: adicione o ficheiro ao .gitignore e, em produção, prefira carregar a chave a partir de uma variável de ambiente.
Passo 4: Criar o Primeiro Agente Conversável
A peça fundamental do AG2 é a classe ConversableAgent. Qualquer agente, seja ele um assistente, um crítico ou um executor de código, deriva desta mesma estrutura base. Vamos criar o primeiro agente, configurado para responder como um assistente de pesquisa técnica.
import autogen
config_list = autogen.config_list_from_json("OAI_CONFIG_LIST.json")
assistente = autogen.ConversableAgent(
name="assistente_pesquisa",
system_message="Você é um assistente técnico que responde de forma objetiva e cita fontes quando possível.",
llm_config={"config_list": config_list, "temperature": 0.3},
)
resposta = assistente.generate_reply(
messages=[{"role": "user", "content": "Explica em três frases o que é um GroupChat no AG2."}]
)
print(resposta)Ao correr este script, o agente devolve uma resposta de texto gerada pelo modelo configurado. Este é o padrão mais simples possível: um único agente a responder a uma única mensagem, sem qualquer troca com outros agentes. É a partir daqui que começamos a adicionar camadas de complexidade.
Passo 5: Construir uma Conversa Entre Dois Agentes
A vantagem real do AG2 aparece quando dois ou mais agentes conversam entre si de forma autónoma. Vamos criar um segundo agente, um “utilizador proxy” que representa um humano no sistema, e deixar os dois trocarem mensagens até a tarefa estar concluída.
utilizador_proxy = autogen.ConversableAgent(
name="utilizador_proxy",
human_input_mode="NEVER",
max_consecutive_auto_reply=5,
is_termination_msg=lambda msg: "TAREFA_CONCLUIDA" in msg.get("content", ""),
code_execution_config=False,
llm_config=False,
)
utilizador_proxy.initiate_chat(
assistente,
message="Resume em cinco pontos as diferenças entre AG2 e AutoGen original. Termina com a palavra TAREFA_CONCLUIDA.",
)Repare em dois parâmetros críticos: max_consecutive_auto_reply limita quantas respostas automáticas seguidas um agente pode dar, e is_termination_msg define a condição exata que encerra a conversa. Sem estes dois limites, uma conversa entre agentes pode continuar indefinidamente, consumindo tokens da API sem necessidade.
Ao correr este script no terminal, o resultado aparece como uma troca de mensagens impressa linha a linha, cada uma identificada pelo nome do agente que a enviou. Um exemplo típico de saída é o seguinte:
utilizador_proxy (to assistente_pesquisa):
Resume em cinco pontos as diferenças entre AG2 e AutoGen original. Termina com a palavra TAREFA_CONCLUIDA.
--------------------------------------------------------------------------------
assistente_pesquisa (to utilizador_proxy):
1. O AG2 é mantido pela organização ag2ai, fora do controlo direto da Microsoft.
2. Usa licença Apache 2.0 em vez da licença MIT do repositório original.
3. Recebe lançamentos mais frequentes, com v1.1.2 e v1.2.0 publicadas na mesma semana.
4. Mantém grande parte da API original, facilitando a migração de código existente.
5. Tem uma comunidade de governação aberta, com contribuidores de várias organizações.
TAREFA_CONCLUIDA
--------------------------------------------------------------------------------Note que a conversa parou exatamente depois da palavra TAREFA_CONCLUIDA aparecer na resposta, confirmando que a condição de terminação funcionou como esperado. Se essa palavra nunca aparecer, o utilizador_proxy continuaria a responder automaticamente até atingir o limite de cinco respostas consecutivas definido antes.
Passo 6: Adicionar um Agente Executor de Código
Um dos recursos que distinguiu o AutoGen (e agora o AG2) de outros frameworks de agentes é a capacidade de um agente escrever código Python, entregá-lo a outro agente, e esse código ser executado automaticamente para validar o resultado. Para isso funcionar com segurança, configure o executor para correr dentro de um contentor Docker.
from autogen.coding import DockerCommandLineCodeExecutor
executor_docker = DockerCommandLineCodeExecutor(
image="python:3.11-slim",
timeout=60,
work_dir="espaco_trabalho",
)
executor_agente = autogen.ConversableAgent(
name="executor_codigo",
llm_config=False,
code_execution_config={"executor": executor_docker},
human_input_mode="NEVER",
)Com o Docker Desktop a correr em segundo plano, este agente cria um contentor isolado, limitado a 60 segundos de execução, sempre que recebe um bloco de código Python de outro agente. Se o Docker não estiver disponível, o AG2 também permite usar um executor local sem isolamento, mas isso só deve ser feito em ambientes de teste controlados, nunca com código gerado a partir de prompts não confiáveis.
Passo 7: Orquestrar um GroupChat com Múltiplos Agentes
Quando o problema exige mais do que dois participantes, por exemplo um investigador, um crítico e um executor de código, o AG2 oferece a classe GroupChat gerida por um GroupChatManager. O gestor decide, a cada turno, qual agente deve responder a seguir, com base no histórico da conversa e nas instruções de cada um.
investigador = autogen.ConversableAgent(
name="investigador",
system_message="Pesquisa e propõe soluções técnicas, sempre com justificação.",
llm_config={"config_list": config_list},
)
critico = autogen.ConversableAgent(
name="critico",
system_message="Revê as propostas do investigador e aponta falhas ou riscos de segurança.",
llm_config={"config_list": config_list},
)
grupo = autogen.GroupChat(
agents=[utilizador_proxy, investigador, critico, executor_agente],
messages=[],
max_round=12,
)
gestor = autogen.GroupChatManager(groupchat=grupo, llm_config={"config_list": config_list})
utilizador_proxy.initiate_chat(
gestor,
message="Propõe e valida um pequeno script Python que calcule a média de uma lista de números.",
)O parâmetro max_round funciona como uma rede de segurança adicional, limitando o número total de turnos no grupo independentemente das condições de terminação individuais de cada agente. Em projetos com quatro ou mais agentes, este limite é o que evita faturas inesperadas na conta da API.
Numa corrida real deste GroupChat, o GroupChatManager escolhe o próximo orador a cada turno e imprime essa decisão no terminal antes da resposta do agente escolhido. Um trecho representativo do resultado é este:
Next speaker: investigador
investigador (to chat_manager):
Proposta: usar a função sorted() do Python para ordenar a lista, com complexidade O(n log n).
Código: numeros_ordenados = sorted(lista_numeros)
--------------------------------------------------------------------------------
Next speaker: executor_codigo
executor_codigo (to chat_manager):
exitcode: 0 (execution succeeded)
Code output: [1, 2, 5, 8, 9]
--------------------------------------------------------------------------------
Next speaker: critico
critico (to chat_manager):
A solução está correta e eficiente. Aprovado. TAREFA_CONCLUIDAEste padrão, investigador propõe, executor valida, crítico aprova, é o esqueleto mais comum de qualquer fluxo de trabalho sério construído com AG2, e pode ser reaproveitado para tarefas muito mais complexas do que ordenar uma lista de números.
Passo 8: Ligar Ferramentas Externas com Function Calling
Além de gerar texto e código, os agentes do AG2 podem chamar funções Python reais, como consultar uma base de dados, fazer um pedido HTTP a uma API externa, ou ler um ficheiro local. Isto faz-se registando a função em dois agentes: um que a “conhece” (pode sugerir chamá-la) e outro que a executa de facto.
def consultar_preco_acao(ticker: str) -> str:
precos = {"AAPL": "271.40 USD", "MSFT": "512.10 USD"}
return precos.get(ticker.upper(), "Ticker não encontrado")
autogen.register_function(
consultar_preco_acao,
caller=assistente,
executor=utilizador_proxy,
description="Consulta o preço mais recente de uma ação pelo seu ticker.",
)A partir deste registo, sempre que o modelo decidir que precisa do preço de uma ação para responder à pergunta do utilizador, o agente assistente propõe a chamada à função e o utilizador_proxy executa-a de verdade, devolvendo o resultado real em vez de um valor inventado pelo modelo.
Este padrão de separar quem decide chamar a função (o agente com llm_config ativo) de quem a executa de facto (normalmente um agente proxy sem acesso direto ao modelo) é central para a segurança do sistema. Se precisar de registar várias funções, o mais simples é agrupá-las por domínio, por exemplo todas as funções de consulta financeira num agente e todas as funções de acesso a ficheiros noutro, em vez de concentrar tudo num único agente com acesso irrestrito a cada ferramenta disponível no projeto.
Passo 9: Guardar e Retomar o Estado das Conversas
Em aplicações reais, raramente uma conversa com agentes termina numa única execução do script. É comum querer guardar o histórico e retomá-lo mais tarde, ou reutilizá-lo como contexto para uma nova sessão. O AG2 guarda o histórico de cada agente na propriedade chat_messages, que pode ser serializada para disco.
import json
historico = assistente.chat_messages[utilizador_proxy]
with open("historico_conversa.json", "w", encoding="utf-8") as ficheiro:
json.dump(historico, ficheiro, ensure_ascii=False, indent=2)
# Para retomar numa nova sessão
with open("historico_conversa.json", "r", encoding="utf-8") as ficheiro:
historico_recuperado = json.load(ficheiro)
assistente.chat_messages[utilizador_proxy] = historico_recuperadoEsta abordagem simples com ficheiros JSON é suficiente para projetos pequenos ou de teste. Para aplicações com vários utilizadores em simultâneo, o recomendado é persistir este histórico numa base de dados, associando cada sessão a um identificador único de utilizador ou conversa. Bases de dados como PostgreSQL ou um armazenamento chave-valor como Redis funcionam bem para este caso, especialmente porque permitem consultar rapidamente o histórico de uma sessão específica sem ter de carregar todos os ficheiros JSON do disco a cada pedido recebido pela aplicação.
Passo 10: Testar, Depurar e Registar o Fluxo de Agentes
Depurar um sistema multiagente é diferente de depurar código tradicional, porque o comportamento depende das respostas do modelo de linguagem, que não são 100% determinísticas por padrão. O AG2 inclui um módulo de registo de execução que grava cada chamada ao modelo, o tempo de resposta e o custo estimado em tokens.
import autogen.runtime_logging as runtime_logging
sessao_log = runtime_logging.start(logger_type="sqlite", config={"dbname": "logs_ag2.db"})
print("ID da sessão de registo:", sessao_log)
# ... correr a conversa normalmente ...
runtime_logging.stop()Depois de parar o registo, o ficheiro logs_ag2.db fica disponível para consulta via SQL, permitindo analisar quantas chamadas cada agente fez, quanto tempo demorou cada resposta e onde a conversa eventualmente ficou presa em ciclos repetitivos. Usar cache_seed fixo no llm_config durante os testes também ajuda, porque garante que a mesma pergunta produz sempre a mesma resposta em corridas repetidas, facilitando comparar alterações ao código.
Passo 11: Preparar o Projeto Completo para Produção com Docker
Para colocar este sistema de agentes a correr num servidor, a forma mais previsível é empacotar tudo num contentor Docker próprio, separado do contentor que o executor de código usa internamente. Isto isola as dependências do projeto das dependências do ambiente de execução de código.
# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "main.py"]O ficheiro requirements.txt deve fixar a versão exata do AG2 usada em desenvolvimento, por exemplo ag2==1.1.2, para evitar que uma atualização automática do PyPI mude o comportamento dos agentes em produção sem aviso. Se o seu sistema também usa o executor de código baseado em Docker, o contentor principal da aplicação vai precisar de acesso ao socket do Docker do anfitrião (Docker-outside-of-Docker), uma configuração que exige atenção extra de segurança em ambientes partilhados.
Nunca copie a chave da API do modelo para dentro da imagem Docker durante o build. Passe-a sempre como variável de ambiente no momento de arrancar o contentor, por exemplo com docker run --env-file .env nome-da-imagem, mantendo o ficheiro .env fora do controlo de versões. Esta separação entre código e segredos é uma das diferenças mais visíveis entre um protótipo de agentes de IA feito num portátil e um sistema preparado para correr de forma fiável num servidor partilhado por várias equipas.
AG2 vs AutoGen vs Microsoft Agent Framework: Qual Escolher
Com três projetos a disputar o mesmo espaço, vale a pena comparar o estado de cada um antes de decidir qual usar num projeto novo. A tabela seguinte resume os dados recolhidos pela IntelligentTools e pela própria organização ag2ai no GitHub, referentes a outubro de 2026.
| Projeto | Estrelas GitHub | Licença | Última atividade relevante | Estado |
|---|---|---|---|---|
| AutoGen (Microsoft, original) | 61.258 | MIT | Último push a 15 de abril de 2026 | Em modo de manutenção |
| AG2 (fork comunitário) | Cerca de 5.000 | Apache 2.0 | v1.2.0 lançada a 11 de outubro de 2026 | Em desenvolvimento ativo |
| Microsoft Agent Framework | 13.945 | MIT | Versão 1.20.0 lançada a 2 de outubro de 2026 | Sucessor oficial orientado a produção |
Na prática, isto traduz-se em três cenários de uso distintos. Quem já tem código escrito para o AutoGen original e só precisa de correções de segurança pontuais pode continuar com o repositório da Microsoft, sabendo que não vai receber funcionalidades novas. Quem quer uma framework leve, orientada a código, com desenvolvimento rápido e uma comunidade aberta a contribuições, encontra no AG2 o caminho mais direto, até porque mantém grande parte da API original do AutoGen, o que torna a migração relativamente simples. Já quem precisa de integração profunda com o ecossistema Azure e capacidades empresariais como autenticação corporativa e observabilidade nativa, o Microsoft Agent Framework, que junta conceitos do AutoGen com o Semantic Kernel, é a aposta mais alinhada com esse objetivo, segundo a análise comparativa publicada pela Sim.ai.
Um fator a não ignorar é o ritmo de lançamentos. Entre 3 e 11 de outubro de 2026, o AG2 publicou duas versões novas, uma cadência que nenhum dos outros dois projetos conseguiu igualar no mesmo período. Para uma equipa que valoriza correções rápidas de bugs e novidades frequentes, esse ritmo pesa tanto na decisão como o número total de estrelas no GitHub.
Casos de Uso Reais para Equipas de Engenharia
Depois de montar o esqueleto técnico, vale a pena olhar para onde este tipo de arquitetura multiagente costuma gerar valor real numa equipa de engenharia. O caso mais direto é a revisão automática de código: um agente gera um pull request pequeno, outro agente simula o papel de revisor, apontando problemas de estilo ou falhas lógicas, e um terceiro agente corre os testes automatizados num contentor isolado antes de qualquer humano olhar para a alteração. Isto não substitui a revisão humana final, mas filtra erros óbvios antes de chegarem a essa fase.
Outro uso comum é a investigação técnica estruturada: em vez de pedir a um único modelo para resumir um tema complexo, divide-se o trabalho entre um agente que procura informação, outro que organiza essa informação em secções, e um terceiro que verifica se as afirmações feitas têm suporte nas fontes recolhidas. Esta divisão de papéis reduz a tendência de um modelo único “inventar” factos quando não tem a certeza da resposta, porque cada etapa fica mais fácil de auditar isoladamente.
Equipas de dados também têm adotado este padrão para automatizar relatórios recorrentes: um agente consulta uma base de dados através de uma função registada, outro agente interpreta os números e escreve um resumo em linguagem natural, e um terceiro agente formata o resultado final para envio por email ou publicação num painel interno. Como cada agente tem uma responsabilidade estreita e bem definida, fica mais simples substituir ou melhorar apenas uma peça do sistema sem reescrever o fluxo inteiro, uma vantagem direta da arquitetura modular que tanto o AutoGen original como o AG2 adotaram desde o início.
Segurança e Governação ao Usar Agentes Autónomos
Dar a um conjunto de agentes a capacidade de executar código, chamar funções externas e tomar decisões sem supervisão humana constante levanta questões de segurança que não podem ser ignoradas, especialmente em ambientes empresariais com dados sensíveis. A primeira linha de defesa é sempre o isolamento do executor de código: qualquer script gerado por um modelo de linguagem deve correr dentro de um contentor descartável, sem acesso a credenciais, variáveis de ambiente de produção ou à rede interna da organização, salvo exceções explicitamente autorizadas.
A segunda camada de proteção diz respeito às funções registadas em cada agente. Um erro frequente é expor a um agente conversável todas as funções disponíveis no sistema, incluindo operações destrutivas como apagar ficheiros ou enviar pagamentos. A prática recomendada é dividir as funções por nível de risco e só registar, em cada agente, o conjunto mínimo necessário para a tarefa que lhe foi atribuída, seguindo o mesmo princípio de menor privilégio usado há décadas em sistemas tradicionais.
Por fim, qualquer sistema multiagente colocado em produção deve manter um registo auditável de cada decisão tomada, incluindo que agente propôs o quê e em que momento. É exatamente para isso que serve o módulo runtime_logging apresentado no Passo 10 deste tutorial: sem esse registo, torna-se quase impossível reconstruir o que aconteceu depois de um incidente, seja ele uma resposta incorreta entregue a um cliente ou uma chamada de função inesperada. Manter esse histórico, mesmo que pareça desnecessário no início de um projeto pequeno, poupa tempo significativo no dia em que algo correr mal.
Erros Comuns ao Construir Agentes com AG2
Depois de testar o fluxo completo descrito acima, há um conjunto de erros que aparecem com frequência em projetos reais com AG2. Conhecê-los antecipadamente poupa horas de depuração.
- Instalar o pacote errado: confundir
pyautogen,autogeneag2no PyPI gera conflitos silenciosos de dependências, porque todos registam o mesmo módulo Python internamente. - Esquecer limites de turnos: não definir
max_consecutive_auto_replynemmax_roundpode fazer dois agentes trocarem mensagens indefinidamente, gastando tokens sem produzir valor. - Executar código sem isolamento: correr o executor de código fora do Docker, com entradas vindas de prompts não confiáveis, expõe a máquina anfitriã a comandos potencialmente perigosos.
- Condições de terminação ambíguas: usar frases genéricas em
is_termination_msgque podem aparecer por acaso numa resposta normal do modelo, encerrando a conversa antes do previsto. - Misturar versões do PyPI e do GitHub: como a versão publicada no PyPI (1.1.2) ficou atrás da versão mais recente no GitHub (1.2.0) em outubro de 2026, instalar diretamente do repositório sem fixar o commit pode introduzir comportamento diferente do testado.
- Ignorar o custo de tokens em grupos grandes: cada turno extra num GroupChat com vários agentes multiplica as chamadas à API do modelo, e sem monitorização esse custo cresce rapidamente.
Resolução de Problemas: Erros Frequentes e Soluções
Esta secção reúne os problemas mais reportados por quem está a começar com o AG2, junto com a forma mais rápida de os resolver.
- ModuleNotFoundError: No module named ‘autogen’: normalmente significa que o pacote
ag2não foi instalado no ambiente virtual ativo. Confirme compip show ag2e reative ovenvcorreto. - Erro 401 de autenticação da API: a chave no ficheiro
OAI_CONFIG_LIST.jsonestá inválida, expirou, ou não corresponde ao fornecedor indicado no campomodel. - Agentes em loop aparentemente infinito: verifique se
is_termination_msgestá a avaliar corretamente o conteúdo da mensagem e semax_roundestá definido no GroupChat. - “Docker not found” ao executar código: confirme que o Docker Desktop está a correr e que o utilizador atual tem permissões para aceder ao socket do Docker.
- Erro 429 (rate limit) da API do modelo: reduza o número de agentes ativos em simultâneo no GroupChat ou adicione lógica de espera exponencial entre chamadas.
- Respostas cortadas a meio: aumente o valor de
max_tokensnollm_config, já que o valor padrão pode ser insuficiente para respostas longas com código. - O GroupChatManager escolhe sempre o mesmo agente: reveja o
system_messagede cada agente, pois instruções vagas fazem o gestor repetir a mesma escolha a cada turno. - Conflito entre pyautogen e ag2 instalados ao mesmo tempo: desinstale ambos e reinstale apenas o
ag2num ambiente virtual limpo. - Histórico de conversa perdido entre execuções: confirme que o passo de serialização em JSON (ou base de dados) está mesmo a ser chamado antes do script terminar.
Dicas Avançadas e Boas Práticas
Depois de dominar o fluxo básico, estas práticas ajudam a tornar o sistema mais estável e mais barato de operar a longo prazo.
- Fixe
cache_seednum valor inteiro durante os testes automatizados, para que a mesma entrada produza sempre a mesma saída e facilite comparar alterações ao código entre versões. - Combine o AG2 com o Model Context Protocol para expor ferramentas externas de forma padronizada a vários agentes, em vez de registar funções individualmente em cada script.
- Em ambientes partilhados, prefira o executor de código baseado em Jupyter kernel ou em contentores Docker descartáveis, nunca o executor local sem isolamento.
- Para agentes que tomam decisões críticas (por exemplo, aprovar uma transação ou enviar um email), use uma
temperaturebaixa, entre 0 e 0.3, para reduzir variabilidade nas respostas. - Active o registo estruturado com
runtime_loggingdesde o primeiro dia em produção, não apenas durante os testes, porque facilita auditar decisões tomadas pelos agentes depois de um incidente. - Limite explicitamente quais agentes podem chamar quais funções, em vez de registar todas as ferramentas em todos os agentes, reduzindo a superfície de ataque em caso de prompt injection.
Projeto Completo: Assistente de Pesquisa Multiagente
Para fechar o tutorial, junte tudo o que foi construído nos passos anteriores num único projeto funcional: um assistente de pesquisa com três agentes (investigador, crítico e executor de código), limites claros de turnos, persistência de histórico e registo de execução.
import json
import autogen
import autogen.runtime_logging as runtime_logging
from autogen.coding import DockerCommandLineCodeExecutor
config_list = autogen.config_list_from_json("OAI_CONFIG_LIST.json")
llm_config = {"config_list": config_list, "temperature": 0.3, "cache_seed": 42}
executor_docker = DockerCommandLineCodeExecutor(image="python:3.11-slim", timeout=60)
investigador = autogen.ConversableAgent(
name="investigador", llm_config=llm_config,
system_message="Propõe soluções técnicas objetivas, com justificação breve.",
)
critico = autogen.ConversableAgent(
name="critico", llm_config=llm_config,
system_message="Revê propostas e aponta riscos. Responde TAREFA_CONCLUIDA quando aprovar.",
)
executor_agente = autogen.ConversableAgent(
name="executor_codigo", llm_config=False,
code_execution_config={"executor": executor_docker}, human_input_mode="NEVER",
)
utilizador_proxy = autogen.ConversableAgent(
name="utilizador_proxy", human_input_mode="NEVER", max_consecutive_auto_reply=6,
is_termination_msg=lambda m: "TAREFA_CONCLUIDA" in m.get("content", ""),
code_execution_config=False, llm_config=False,
)
grupo = autogen.GroupChat(
agents=[utilizador_proxy, investigador, critico, executor_agente],
messages=[], max_round=15,
)
gestor = autogen.GroupChatManager(groupchat=grupo, llm_config=llm_config)
runtime_logging.start(logger_type="sqlite", config={"dbname": "logs_ag2.db"})
utilizador_proxy.initiate_chat(
gestor,
message="Investiga, escreve e valida um script Python que ordene uma lista de números por ordem crescente.",
)
runtime_logging.stop()
with open("historico_conversa.json", "w", encoding="utf-8") as f:
json.dump(grupo.messages, f, ensure_ascii=False, indent=2)Ao correr este script com uma chave de API válida e o Docker Desktop ativo, deve ver no terminal uma sequência de mensagens alternadas entre o investigador, o crítico e o executor de código, terminando quando o crítico aprovar explicitamente o resultado com a palavra TAREFA_CONCLUIDA. No final, a pasta do projeto fica com um ficheiro logs_ag2.db para auditoria e um historico_conversa.json com a conversa completa, prontos para análise posterior ou para retomar uma nova sessão a partir daí.
Perguntas Frequentes
O AG2 é gratuito?
Sim, o AG2 é distribuído sob licença Apache 2.0, uma licença open source aprovada pela OSI. O que não é gratuito são as chamadas à API do modelo de linguagem escolhido, cobradas diretamente pelo fornecedor (OpenAI, Anthropic, Azure, entre outros).
O AG2 é o mesmo que o AutoGen?
Não exatamente. O AG2 é um fork comunitário que continuou o desenvolvimento do AutoGen depois de o repositório oficial da Microsoft ter entrado em modo de manutenção. Partilha grande parte da API original, mas é mantido por uma organização separada, a ag2ai.
Preciso de Docker para usar o AG2?
Não é obrigatório para criar agentes conversáveis simples, mas é altamente recomendado sempre que algum agente vai executar código Python gerado automaticamente, por motivos de segurança e isolamento.
Posso usar modelos locais em vez da API da OpenAI?
Sim, desde que o servidor local exponha uma API compatível com o formato da OpenAI, como acontece com o Ollama ou outros servidores de inferência. Basta ajustar o base_url na configuração de cada modelo.
Qual a diferença entre AG2 e o Microsoft Agent Framework?
O Agent Framework é o sucessor oficial da Microsoft, pensado para integração empresarial com Azure e com o Semantic Kernel. O AG2 é a continuação comunitária, mais leve e mais próxima da API original do AutoGen.
É seguro deixar os agentes executarem código automaticamente?
Só se o código correr dentro de um ambiente isolado, como um contentor Docker descartável, e nunca com acesso direto a credenciais ou a dados sensíveis da máquina anfitriã.
Quantos agentes consigo colocar num único GroupChat?
Não há um limite técnico rígido, mas na prática cada agente adicional aumenta o número de chamadas à API por turno e a complexidade da coordenação, por isso a maioria dos projetos reais usa entre dois e cinco agentes.
Vale a pena migrar um projeto antigo de AutoGen para AG2?
Na maioria dos casos sim, especialmente se o projeto depende de correções de segurança ou de funcionalidades novas, já que o repositório oficial da Microsoft deixou de receber atualizações regulares desde abril de 2026.
O AG2 funciona bem em produção ou é só para protótipos?
Funciona em produção desde que sejam seguidas as práticas descritas neste tutorial: fixar a versão exata do pacote, isolar a execução de código em contentores, limitar o número de turnos por conversa e manter registo auditável de cada decisão tomada pelos agentes. Sem esses cuidados, qualquer framework de agentes, não só o AG2, torna-se arriscada de operar fora de um ambiente controlado.
O que acontece se o PyPI e o GitHub do AG2 tiverem versões diferentes?
Pode acontecer, como se viu em outubro de 2026, quando o GitHub já tinha a versão 1.2.0 publicada mas o pacote no PyPI continuava na 1.1.2. Nesse cenário, instalar via pip install ag2 traz a versão mais antiga disponível publicamente, e só quem instalar diretamente do repositório Git vai obter as funcionalidades mais recentes, com o risco de usar código ainda não totalmente estabilizado.