Describing Agentic AI Systems with C4: Lessons from Industry Projects

TL;DR

This paper introduces a style-oriented documentation approach for agentic AI systems, emphasizing collaboration, artifacts, and external tools, based on industrial experience and tailored modeling techniques.

Contribution

It presents a new documentation systematics for agentic AI, including a modeling vocabulary, views, and hierarchical description aligned with C4, derived from industry projects.

Findings

Improved transparency and maintainability of agentic AI architecture documentation.

The approach supports long-term evolution of industrial systems.

Lessons learned demonstrate practical effectiveness.

Abstract

Different domains foster different architectural styles -- and thus different documentation practices (e.g., state-based models for behavioral control vs. ER-style models for information structures). Agentic AI systems exhibit another characteristic style: specialized agents collaborate by exchanging artifacts, invoking external tools, and coordinating via recurring interaction patterns and quality gates. As these systems evolve into long-lived industrial solutions, documentation must capture these style-defining concerns rather than relying on ad-hoc code sketches or pipeline drawings. This paper reports industrial experience from joint projects and derives a documentation systematics tailored to this style. Concretely, we provide (i) a style-oriented modeling vocabulary and a small set of views for agents, artifacts, tools, and their coordination patterns, (ii) a hierarchical description technique aligned with C4 to structure these views across abstraction levels, and (iii) industrial examples with lessons learned that demonstrate how the approach yields transparent, maintainable architecture documentation supporting sustained evolution.