Documentar un sistema de agentes de IA con el modelo C4

Los proyectos de agentes cambian de forma rápido: aparece una pasarela de herramientas, la memoria pasa a su propio almacén, se suma un segundo proveedor de modelos. El diagrama de la wiki suele dejar de coincidir con el sistema en cuestión de semanas, y a menudo nunca respondió la primera pregunta que hace alguien nuevo en el equipo: ¿cuáles son las partes y quién habla con quién?

Cuatro niveles, y rara vez necesitas todos

El modelo C4, creado por Simon Brown, describe el software en cuatro niveles de zoom: sistema de software, contenedor, componente y código. El sitio de C4 es explícito en que no tienes que usar todos los niveles, y en que los diagramas de contexto del sistema y de contenedores bastan para la mayoría de los equipos.

Usa las pestañas de arriba para moverte entre los niveles. Muestran la misma plataforma de agentes de ejemplo, cada una con un paso más de zoom.

• C1, contexto del sistema: tu sistema como una sola caja, con las personas y otros sistemas a su alrededor. Todavía sin tecnología.
• C2, contenedores: las aplicaciones y almacenes de datos que corren por separado, con la tecnología de cada uno y cómo se comunican.
• C3, componentes: las partes dentro de un contenedor. Dibújalo solo para el contenedor que lo necesite. Aquí es el servicio de agentes.
• C4, código: clases e interfaces. Normalmente conviene generarlo desde el código fuente en vez de dibujarlo a mano.

Qué es un contenedor en un sistema de agentes

Un contenedor es algo que tiene que estar funcionando para que el sistema opere: una aplicación web, un servicio de agentes, una pasarela de herramientas, una base de datos. El proveedor de modelos y los sistemas del negocio no son nuestros, así que se dibujan como sistemas externos fuera del límite.

Reglas que mantienen legible el dibujo

• Un nivel por diagrama, y el nivel en el título.
• Rotula cada flecha con lo que ocurre y, donde importe, el protocolo: HTTPS, SQL, MCP.
• Nombra la tecnología o el rol dentro de cada contenedor, para que nadie tenga que adivinar.
• Dibuja un límite alrededor del sistema en alcance, para que lo externo sea obvio.
• Di qué dejaste fuera. Un diagrama de nivel 2 que omite el despliegue debería decirlo.

Mantenlo junto al código

Guarda el código fuente del diagrama en el repositorio y revísalo en el mismo pull request que el cambio que describe. Un diagrama que se edita junto con el código se mantiene honesto. Uno que vive solo en una presentación, no.