Describing Agentic AI Systems with C4: Lessons from Industry Projects
This work addresses the problem of inadequate documentation for long-lived agentic AI systems in industry, offering a tailored approach that is incremental in building on existing C4 practices.
The paper tackles the challenge of documenting agentic AI systems in industrial settings by proposing a style-oriented modeling vocabulary and hierarchical description technique aligned with C4, resulting in transparent and maintainable architecture documentation that supports sustained evolution.
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.