Neste tutorial, demonstramos como construir um sistema de IA colaborativo usando o framework ChatDev e exploramos sua estrutura de comunicação entre agentes baseada em funções, o ChatChain. O ChatDev usa agentes de IA com funções atribuídas para simular uma empresa de software virtual. Cada agente inteligente colabora com outros por meio de comunicação estruturada, seguindo um fluxo de trabalho sequencial baseado em fases do ciclo de vida de desenvolvimento de software.
Para alimentar esses agentes, integramos o estúdio de IA da interface de programação de aplicativos (API) do IBM® watsonx.ai como um back-end de modelo. Aproveitando uma integração do watsonx.ai com o Hugging Face, configuramos o framework para usar o Llama-4-Maverick para gerar uma solução de software simples. Este exemplo serve como base para explorar o ChatChain e outros mecanismos internos de comunicação de agentes que orientam o comportamento e a tomada de decisão de agentes em todo o fluxo de trabalho.
Até o final deste tutorial, você terá experiência prática na configuração e execução do ChatDev, além de uma compreensão mais clara de como os protocolos de comunicação de agentes possibilitam a colaboração eficaz e confiável multiagentes.
IA colaborativa: sistemas de inteligência artificial projetados para trabalhar junto com humanos ou agentes de IA, muitas vezes usando deep learning ou outras técnicas avançadas para permitir a cooperação, a tomada de decisão e a resolução conjunta de problemas para alcançar objetivos comuns.
Colaboração multiagentes: múltiplos agentes autônomos que compartilham informações e se coordenam para realizar um objetivo compartilhado. Esses agentes podem ter diferentes níveis de conhecimento, recursos e perspectivas, e sua colaboração geralmente envolve negociação, planejamento e ação coordenada.
Agentes de dramatização: agentes de IA que simulam funções ou personas específicas para interagir e colaborar de maneira orientada por objetivos. Esses papéis podem refletir profissões ou personagens do mundo real, permitindo interações mais conscientes do contexto e orientadas para um propósito.
Protocolos de comunicação de agentes: padrões ou frameworks que definem como os agentes de IA interagem entre si por meio da troca de mensagens de dados estruturadas. Esses protocolos regem o formato, a semântica e as regras de comunicação para agentes coordenados em sistemas multiagentes.
O ChatDev é uma implementação baseada em funções de IA colaborativa, em que agentes individuais assumem funções especializadas para trabalhar em direção a um objetivo compartilhado. Esse design reflete princípios de inteligência coletiva — colaboração essencialmente eficaz — e posiciona o ChatDev como um recurso valioso para estudar e avançar nesse campo.
O ChatDev é um framework multiagentes de código aberto desenvolvida pela OpenBMB, uma iniciativa orientada por pesquisa focada no avanço de ferramentas de IA e inteligência geral artificial (IA). O framework usa o processo de desenvolvimento de software como um domínio prático para estudar agentes de IA colaborativos. Cada agente é impulsionado por um grande modelo de linguagem (LLM) e é solicitado a assumir funções específicas, como CEO, CTO, designer, testador e programador.1
A partir de uma entrada de usuário curta e descritiva, esses agentes colaboram para projetar, implementar e testar de forma iterativa um projeto de software completo. Cada agente é implementado como uma classe Python que se comunica sequencialmente usando prompts estruturados de linguagem natural. Esses prompts seguem modelos predefinidos que incluem a função do agente, instruções específicas da tarefa e contexto relevante de interações anteriores. Essa estratégia de modelos ajuda a garantir a continuidade e a coerência, incorporando a identidade da função e a memória compartilhada no próprio prompt.
A equipe de agentes especializados do ChatDev trabalha em conjunto para gerar uma solução de software simples a partir de uma entrada de usuário de uma linha descrevendo sua ideia.
Entrada do usuário: "Crie um aplicativo de lista de tarefas" → CEO delega ao CTO → CTO atribui ao desenvolvedor → Desenvolvedor escreve o código → Testador valida
Como o ChatDev funciona
As interações dos agentes são orquestradas pelo ChatChain, a lógica de coordenação personalizada dentro do framework do ChatDev. A comunicação entre os agentes ocorre por meio de uma caixa de diálogo multivoltas, ou sistema de passagem de mensagens, onde os agentes trocam sequencialmente mensagens JSON estruturadas. Essas mensagens representam produções e atualizações de contexto e atuam como um buffer de memória compartilhada, permitindo que os agentes utilizem as saídas uns dos outros em fases de desenvolvimento.
Essa arquitetura permite comunicação consistente e colaboração com base no contexto, combinando linguagens naturais e de programação para concluir o projeto de ponta a ponta. O processo depende da comunicação coordenada de vários agentes, com mecanismos internos atuando como protocolos para orquestrar a comunicação eficaz dos agentes de IA para concluir cada fase.
Os usuários podem monitorar e avaliar o fluxo de trabalho agêntico por meio da ferramenta Visualizer do ChatDev, uma interface da web baseada em Flask compatível com a análise pós-execução e o monitoramento em tempo real. O Visualizer oferece vários modos, como um Log Viewer para inspecionar interações de agentes em tempo real, um Replay Viewer para visualizar logs de conversas multiagente salvos e um ChatChain Viewer para examinar o fluxo de coordenação de tarefas. Essa interface interativa permite aos usuários depurar, experimentar e estudar a colaboração multiagentes por meio de um ambiente estruturado por meio de um navegador local.
Observação sobre a compatibilidade de modelos e a variabilidade de saídas
Este tutorial usa uma versão personalizada do ChatDev adaptada especificamente para a API do IBM watsonx.ai. Embora o ChatDev principal seja compatível com vários provedores de modelos, essa versão foi modificada usando uma abordagem pragmática de "vibeprogramação", tornando-a funcional, mas não exaustivamente testada em todos os cenários.
As principais adaptações incluem:
Envolvimento da API do IBM watsonx.ai para estar em conformidade com a interface de LLM esperada do ChatDev.
Ajuste de modelos de prompts para trabalhar com os requisitos de tokens e formatação da API do IBM watsonx.ai
Modificação da lógica de seleção de modelos para compatibilidade com o IBM watsonx.ai como opção de back-end de modelos.
Essa implementação demonstra como o ChatDev pode ser estendido para compatibilidade com provedores de LLMs alternativos. Outros provedores de modelos (por exemplo, OpenAI, Ollama) não foram testados com essa versão personalizada do ChatDev e precisariam de ajustes em nível de código.
Como em muitos fluxos de trabalho de IA generativa, a saída pode variar entre as execuções. Embora os agentes geralmente produzam código e documentação coerentes e bem estruturados, as aplicações resultantes podem exigir refinamento manual para se tornarem totalmente funcionais. Fatores como design de prompts, complexidade da tarefa e a variabilidade inerente das respostas do LLM contribuem para essa imprevisibilidade.
Este tutorial serve como uma introdução prática aos sistemas multiagentes colaborativos, com foco em como os agentes se comunicam e coordenam no ChatDev. Ele não se destina a ser uma solução pronta para produção, mas sim uma base para aprendizado, experimentação e exploração da colaboração de agentes orientada por LLMs. Somos gratos aos pesquisadores por trás do ChatDev por cederem seu código aberto, tornando esse tipo de exploração possível.
Etapa 1. Configure seu ambiente
Embora o ChatDev seja projetado para ser multiplataforma, os usuários podem encontrar problemas específicos da plataforma durante a configuração ou execução. Por exemplo, o PowerShell no Windows pode exigir ajustes em comandos de shell destinados a sistemas baseados em Unix. Variações no sistema operacional, versões do Python e arquiteturas de CPU também podem afetar o desempenho ou o comportamento. Para ajudar a garantir uma configuração e usabilidade tranquilas, os usuários devem consultar a documentação oficial do ChatDev e os guias de instalação para obter instruções específicas para o ambiente e solução de problemas.
Com isso em mente, vamos começar configurando o ambiente para executar a aplicação. Você pode seguir estas etapas no arquivo Markdown dentro da pasta do projeto no GitHub ou seguindo estas etapas.
- Certifique-se de que você tenha o Python 3.11 instalado em seu sistema.
> Você pode verificar sua versão do Python usando ocomando python3 –-version . - Clone o repositório do GitHub.
> Para obter etapas detalhadas sobre como clonar um repositório, consulte a documentação do GitHub. - Verifique se a estrutura do projeto é semelhante à seguinte:
├── camel/
│ ├── model_backend.py # Unified interface for interacting with multiple AI models
│ ├── typing.py # Defines various type classes including supported AI models
│ ├── configs.py # Defines the model parameters based on model interface
│ ├── utils.py # Various utility functions including model token limit configuration
│ └── ...
├── Visualizer/
│ └──app.py # Runs a Flask application in a local web browser to view logs and ChatChain
├── WareHouse # Where the generated software is saved
├── run.py # Application entry point
└── chatdev_watsonx.md # A markdown version of this tutorial
Etapa 2. Obtenha as credenciais da API do watsonx
- Faça login no watsonx.ai usando sua conta do IBM Cloud.
- Crie um projeto do watsonx.ai. >Anote o ID do projeto em projeto > Gerenciar > Geral > ID do projeto.
Você precisará desse ID para este tutorial. - Crie uma instância do serviço watsonx.ai Runtime (escolha o plano Lite, que é uma instância gratuita).
- Gere uma chave de API do watsonx .
- Associe o serviço watsonx.ai Runtime ao projeto que você criou no watsonx.ai.
Etapa 3. Crie um ambiente virtual
No diretório do projeto do tutorial, crie um ambiente virtual usando o Python 3.11:
source venv/bin/activate
Etapa 4. Instale o requirements.txt
Isso instala as dependências do projeto.
Etapa 5. Defina variáveis de ambiente para integração do LLM
A variável é definida para a sessão de terminal atual (fechar o terminal irá redefini-las).
Embora este tutorial use o IBM watsonx.ai como back-end do modelo, o framework subjacente do ChatDev foi originalmente projetado para ser compatível com vários provedores de LLMs, incluindo um padrão, o OpenAI. Algumas partes da base de código (por exemplo, lógica de seleção de modelo ou interfaces compartilhadas) ainda fazem referência ao
export WATSONX_URL="https://us-south.ml.cloud.ibm.com"
export WATSONX_APIKEY="your_watsonx_api_key"
export WATSONX_PROJECT_ID="your_watsonx_project_id"
Etapa 6. (opcional) Execute o aplicativo Visualizer para a interface do ChatDev
Ou então, você pode executar o Visualizer do ChatDev, uma GUI baseada em Flask que permite inspecionar os logs do agente em tempo real, explorar o fluxo de trabalho do ChatChain ou repetir caixas de diálogo de agentes salvas. Essa ferramenta é útil para depurar, monitorar ou estudar interações de agentes, mas não é necessária para executar o fluxo de trabalho multiagentes principal do ChatDev.
Para iniciar o Visualizer, primeiro instale o Flask:
Em seguida, execute o aplicativo:
Após a execução, abra um navegador e acesse:
Etapa 7. (opcional) Configuração do LLM
Observação: este tutorial usa uma versão do ChatDev pré-configurada para usar a API IBM watsonx.ai como back-end do modelo. Nenhuma configuração adicional ou alteração na configuração do modelo é necessária para que o tutorial funcione corretamente. Embora personalizável, a modificação das configurações do LLM pode resultar em saídas incompletas, incorretas e variadas.
O ChatDev é desenvolvido sobre o framework CAMEL, que gerencia funções, tarefas e interações de agentes com modelos de linguagem. A implementação original usa a API OpenAI como um back-end de modelo para interagir com modelos do ChatGPT, como o GPT-4, e usa o GPT-3.5-turbo por padrão. O projeto de código aberto também foi projetado para ser compatível com vários modelos de provedores de LLMs por meio de uma interface de modelo unificada.
Pule esta etapa se você planeja usar a configuração padrão do IBM watsonx.ai. Para experimentação, o tipo de modelo, os parâmetros e os limites de tokens podem ser ajustados para funcionar com a API do IBM watsonx.ai.
- Tipo de modelo
Para experimentar diferentes tipos de modelos, atualize a entrada
class ModelType(Enum):
WATSONX = "meta-llama/llama-4-maverick-17b-128e-instruct-fp8" # Model identifier used by the Watsonx APIThe model parameters can be configured within camel/configs.py under the WatsonxConfig data class.
- Parâmetros do modelo
Os parâmetros do modelo podem ser configurados dentro de
@dataclass(frozen=True)
class WatsonxConfig:
"""Defines the parameters for generating completions using watsonx.ai models."""
temperature: float = 0.3
top_k: int = 100
top_p: float = 0.0
- Limite de tokens
O limite de tokens para o modelo pode ser configurado no
def get_model_token_limit(model: ModelType) -> int:
if model == ModelType.WATSONX:
return 128000 # Token limit for Watsonx.ai models
Etapa 8. Execute o script para gerar um aplicativo
Essa etapa executa o fluxo de trabalho principal do ChatDev. Quando você executar esse script, os agentes simularão um processo colaborativo de desenvolvimento de software com base em sua entrada. O código gerado, a documentação e os artefatos relacionados serão salvos no diretório WareHouse do projeto. Você pode inspecionar logs ou repetir conversas usando o Visualizer.
O script aceita os seguintes argumentos:
–-task : a descrição da solução de software desejada
–-name : o nome do aplicativo ou projeto
–-model : o modelo de IA a ser usado (deve ser definido comoWATSONX para este tutorial)
Exemplo de script:
Observação: embora a arquitetura do ChatDev seja extensível, esta versão do tutorial só funciona de forma confiável com
O produto de software final é salvo na pasta
Uma saída típica pode se parecer com isto:
└── bookstore-site_DefaultOrganization_20250506162935/
├── templates/ # Web page templates
│ └── about.html
│ └── index.html
│ └── products.html
├── manual.md # The project’s README with instructions to run the software
├── main.py #The main application file for the website
├── requirements.txt # Project dependencies
├── ChatChainConfig.json # System design for collaborative agent workflows
├── RoleConfig.json # System prompts for agent roles
├── PhaseConfig.json # System prompts for phases
└── bookstore-site_DefaultOrganization_20250506162935.log # Log of the agent dialogue
A saída pode variar entre as execuções devido à natureza probabilística das ferramentas de IA generativa.
Este diretório contém um projeto de software completo gerado por agentes de IA. Junto com o código e a documentação da aplicação, você encontrará arquivos de configuração definindo:
Funções do agente (RoleConfig.json)
Fases de desenvolvimento (PhaseConfig.json)
Fluxo de trabalho do agente (ChatChainConfig.json)
Um log de diálogo que pode ser representado no Visualizer do ChatDev
Para executar o aplicativo, siga as instruções no
A interoperabilidade dos agentes refere-se à capacidade de agentes autônomos de entender, se comunicar e colaborar de forma eficaz usando um protocolo ou padrão compartilhado. Esse recurso é essencial para escalar os sistemas de IA agêntica em tarefas, integrando grandes conjuntos de dados e resolvendo problemas complexos de forma cooperativa.
Sistemas multiagentes frequentemente usam protocolos de comunicação de agentes (ACPs), que fornecem padrões para comunicação de agente para agente, mas usando mecanismos de comunicação interna como linguagens de comunicação de agentes (ACLs), como KQML ou FIPA-ACL. Estas definem "atos comunicativos" padrão (por exemplo, informar, solicitar, consultar) para permitir o diálogo estruturado e a coordenação em ambientes dinâmicos.
O ChatDev, no entanto, adota uma abordagem diferente. Ele alcança a interoperabilidade de agentes por meio do ChatChain, um mecanismo de comunicação que estrutura o fluxo de trabalho de coordenação de agentes. O ChatChain gerencia um fluxo síncrono de informações entre agentes em todos os estágios do processo de desenvolvimento de software. Embora não seja baseado em ACLs formais, o ChatChain facilita uma troca semelhante a um protocolo usando convenções otimizadas para LLMs.
A comunicação com o agente do ChatDev depende de:
Modelagem de prompts: no início de cada fase, os agentes participantes recebem um prompt estruturado com sua função, tarefa atual e histórico de conversas relevante. O ChatDev usa um prompt de iniciação para incorporar essas informações diretamente no prompt, ajudando a manter a coerência e o alinhamento de metas entre as interações.
Formatos de mensagens estruturadas: os agentes se comunicam por meio de mensagens JSON estruturadas que codificam saídas e atualizações de contexto. Isso permite troca de dados consistente e rastreabilidade em todo o fluxo de trabalho.
Condicionamento de funções: cada agente é inicializado com um prompt que reforça sua função atribuída, incluindo responsabilidades, metas e expectativas comportamentais — uma estratégia fundamental na desalucinação comunicativa.
Juntos, esses mecanismos formam um framework de comunicação leve e escalável que permite ao ChatDev gerar software de forma colaborativa a partir de um único prompt de usuário. Isso ilustra como a colaboração estruturada baseada em LLMs pode estimular fluxos de trabalho tradicionais multiagentes.
ChatChain
O ChatChain é o principal mecanismo de comunicação do ChatDev, orquestrando a sequência de interações dos agentes em todo o fluxo de trabalho de desenvolvimento de software. Ela estrutura a colaboração em um processo iterativo e semelhante a uma cadeia, composto por fases distintas, cada uma com objetivos e padrões de comunicação específicos.
Durante cada fase, o ChatChain inicia um diálogo de agente duplo entre dois agentes específicos de função (por exemplo, CEO e CTO, Programador e Revisor). Normalmente, um atua como instrutor, o outro como assistente. Esses intercâmbios estruturados multivoltas simplificam a tomada de decisão colaborativa, preservando a clareza em funções e responsabilidades claramente definidas. Prompts de cada fase incorporam instruções de tarefas, identidade da função e contexto relevante para guiar a interação.
O fluxo de trabalho geral do ChatDev segue um modelo em cascata modificado, uma metodologia tradicional de engenharia de software que divide as tarefas em três fases sequenciais: design, programação e testes. As fases de programação e testes são divididas ainda em subtarefas para refletir um processo de desenvolvimento iterativo.
Por padrão, o ChatChain divide o fluxo de trabalho nas seguintes etapas ordenadas e automatizadas:
Análise de demanda: defina a estrutura e os principais componentes da aplicação.
Seleção de idioma: decide qual linguagem de programação usar para criar e executar o software.
Programação: os agentes escrevem o código para criar a aplicação.
CodeCompleteAll: completa o código incluindo funções ou classes ausentes.
CodeReview: avalia e modifica o código para funcionalidade.
Teste: executa o software e modifica o código com base no relatório de teste.
EnvironmentDoc: documenta o ambiente.
Manual: documente e escreva um manual para a aplicação.
Cada fase é definida por um objeto de configuração que especifica atributos que definem seu comportamento e propriedades. Por exemplo, o atributo
Prompts de iniciação
Para orientar a comunicação adequada entre os agentes, o ChatDev usa prompts de iniciação como uma estratégia de inicialização dos agentes antes de cada rodada de subtarefas. Os prompts de iniciação são uma técnica de engenharia de prompts que pode ser usada para incorporar funções, metas e responsabilidades para uma comunicação eficaz dos agentes.
Vamos ver um exemplo de como os inception prompting orientam dois agentes para iniciar, manter e concluir uma subtarefa.
Exemplo de prompts de iniciação no ChatDev
Antes de cada subtarefa, cada agente recebe prompts como parâmetros que definem instruções, características, responsabilidades e objetivos específicos da função. Dois exemplos incluem
Aqui estão os prompts de função do sistema baseados nas funções do agente para o instrutor e o agente assistente na fase LanguageChoose:
{
"Chief Executive Officer": [
"{chatdev_prompt}",
"You are Chief Executive Officer. Now, we are both working at ChatDev and we
share a common interest in collaborating to successfully complete a task
assigned by a new customer.",
"Your main responsibilities include being an active decision-maker on users'
demands and other key policy issues, leader, manager, and executor. Your
decision-making role involves high-level decisions about policy and strategy;
and your communicator role can involve speaking to the organization's
management and employees.",
"Here is a new customer's task: {task}.",
"To complete the task, I will give you one or more instructions, and you
must help me to write a specific solution that appropriately solves the
requested instruction based on your expertise and my needs."
],
"Chief Technology Officer": [
"{chatdev_prompt}",
"You are Chief Technology Officer. we are both working at ChatDev. We share
a common interest in collaborating to successfully complete a task assigned
by a new customer.",
"You are very familiar to information technology. You will make high-level
decisions for the overarching technology infrastructure that closely align
with the organization's goals, while you work alongside the organization's
information technology (\"IT\") staff members to perform everyday operations.",
"Here is a new customer's task: {task}.",
"To complete the task, You must write a response that appropriately solves
the requested instruction based on your expertise and customer's needs."
],
Esses dois prompts inicializam o comportamento desejado do agente, descrevendo sua função, especialidade e responsabilidades. A estratégia de prompts também orienta o comportamento e as respostas das respectivas funções durante as interações, dando instruções personalizadas sobre como concluir a tarefa atribuída.
A comunicação dos agentes é efetivamente guiada por prompts cuidadosos para ajudar a garantir que ambas as funções tenham expectativas claras e possam colaborar de forma eficaz.
Desalucinação comunicativa
Para lidar com possíveis alucinações de codificação (geração de código incompleta ou incorreta), o ChatDev utiliza um padrão de comunicação chamado desalucinação comunicativa. Esse padrão é essencial para estruturar a conversa durante o processo de avaliação de código.
O processo de avaliação de código envolve duas fases:
Exemplo de desalucinação comunicativa no ChatDev
Neste exemplo, o agente de avaliação de código detecta um erro na produção do agente programador e o comunica, juntamente com uma sugestão para corrigir o problema no código-fonte. Em seguida, o agente programador corrige sua saída original com base nesse feedback.
Aqui está parte da saída do agente de avaliação de código durante uma iteração da
...
## Step 7: Highest Priority Comment
A high-priority comment is that the templates directory needs to be created, and
the HTML files should be placed inside it for the application to find and render
them correctly. Without this setup, running `app.py` will result in a
`TemplateNotFound` error because Flask looks for templates in a `templates`
folder by default.
## Step 8: Instructions for Fixing
To fix this, create a new directory named `templates` in the same directory
where `app.py`
O agente Programador responde com o código corrigido no próximo
Here is the list of your developed codes: main.py, index.html, about.html, products.html.
### main.py
```python
...
### templates/index.html
```html
<!--
Homepage template for Turn the Page bookstore website.
Provides navigation links to other pages.
-->
...
</html>
### templates/about.html
```html
<!-- About page template for Turn the Page bookstore website.
Provides information about the bookstore and navigation links. -->
…
</html>
O avaliador de código e o programador continuam refinando o código por até 10 iterações ou até que um consenso seja alcançado após duas fases de modificação consecutivas e idênticas.
O padrão de desalucinação de comunicação ajuda a garantir que o código final seja preciso, completo e alinhado com os requisitos pretendidos por meio de refinamento iterativo, ao mesmo tempo em que facilita a conclusão efetiva de subtarefas.
Neste tutorial, exploramos como o ChatDev permite a IA colaborativa simulando uma empresa de software virtual composta por agentes de IA baseados em funções. Usando a API IBM watsonx.ai como back-end do modelo, o ChatDev orienta os agentes durante todo o ciclo de vida de desenvolvimento de software usando comunicação estruturada em linguagens naturais e de programação.
Embora o ChatDev não use um protocolo formal de comunicação com o agente, ele alcança a interoperabilidade do agente a partir das habilidades naturais do LLM com técnicas de comunicação com o agente, como ChatChain, prompts de iniciação e desalucinação comunicativa. Isso destaca a importância de orquestrar uma comunicação eficaz entre os agentes para uma colaboração bem-sucedida e melhorar a qualidade da produção.
Com ferramentas de visualização integradas para monitorar e repetir as interações dos agentes, o ChatDev oferece uma plataforma avançada para estudar fluxos de trabalho de vários agentes e a dinâmica do trabalho em equipe impulsionado por LLMs. Ele demonstra o potencial do mundo real da IA colaborativa na criação de software e além.
Recursos
Use a IA a serviço de sua empresa com a experiência e o portfólio de soluções líder do setor da IBM à sua disposição.
Reinvente os fluxos de trabalho e operações críticos adicionando IA para maximizar experiências, tomadas de decisão em tempo real e valor de negócios.