Documentando um sistema de agentes de IA com o modelo C4

Os projetos de agentes mudam de forma rápido: surge um gateway de ferramentas, a memória vai para o seu próprio armazenamento, entra um segundo provedor de modelos. O diagrama da wiki costuma deixar de corresponder ao sistema em poucas semanas, e muitas vezes nunca respondeu à primeira pergunta de quem chega à equipe: quais são as partes e quem fala com quem?

Quatro níveis, e raramente você precisa de todos

O modelo C4, criado por Simon Brown, descreve o software em quatro níveis de zoom: sistema de software, contêiner, componente e código. O site do C4 é explícito: você não precisa usar todos os níveis, e os diagramas de contexto do sistema e de contêineres bastam para a maioria das equipes.

Use as abas acima para se mover entre os níveis. Elas mostram a mesma plataforma de agentes de exemplo, cada uma com um passo a mais de zoom.

• C1, contexto do sistema: o seu sistema como uma única caixa, com as pessoas e outros sistemas ao redor. Ainda sem tecnologia.
• C2, contêineres: os aplicativos e armazenamentos de dados que rodam separadamente, com a tecnologia de cada um e como se comunicam.
• C3, componentes: as partes dentro de um contêiner. Desenhe só para o contêiner que precisa. Aqui é o serviço de agentes.
• C4, código: classes e interfaces. Em geral é melhor gerar a partir do código-fonte do que desenhar à mão.

O que é um contêiner em um sistema de agentes

Um contêiner é algo que precisa estar rodando para o sistema funcionar: um aplicativo web, um serviço de agentes, um gateway de ferramentas, um banco de dados. O provedor de modelos e os sistemas do negócio não são nossos, então são desenhados como sistemas externos fora da fronteira.

Regras que mantêm o desenho legível

• Um nível por diagrama, e o nível no título.
• Rotule cada seta com o que acontece e, onde importar, o protocolo: HTTPS, SQL, MCP.
• Nomeie a tecnologia ou o papel dentro de cada contêiner, para ninguém precisar adivinhar.
• Desenhe uma fronteira em volta do sistema em escopo, para o que é externo ficar óbvio.
• Diga o que ficou de fora. Um diagrama de nível 2 que omite a implantação deveria dizê-lo.

Mantenha junto do código

Guarde o código-fonte do diagrama no repositório e revise-o no mesmo pull request da mudança que ele descreve. Um diagrama editado junto com o código continua honesto. Um que vive só em uma apresentação, não.