The Question I Couldn't Answer
I was reviewing a C4 architecture diagram with my team recently when someone asked a question I couldn't cleanly answer.
"Where do the AI agents go?"
Not conceptually. Literally — which box, which level, which relationship arrow in the diagram?
C4 is the framework I reach for when I need to communicate architecture clearly. Context, Container, Component, Code. Four levels of abstraction that force you to think carefully about system boundaries, responsibilities, and interfaces. It works because it's simple, scalable, and technology-agnostic.
But C4 was designed for deterministic systems. You draw a box. You label it. You define its interfaces. The box does what it says every time.
AI agents don't behave like boxes.
They plan. They decide. They initiate actions autonomously. They produce different outputs for identical inputs. They traverse system boundaries in ways that a conventional relationship arrow doesn't capture honestly.
I went looking for guidance on how to represent this in C4 and found something worth sharing — the gap is real, documented, and actively being worked on by the architecture community. A 2026 industry report explicitly acknowledged that C4 and arc42 don't prescribe agentic-specific constructs — agent roles and boundaries, tool access, interaction protocols, memory structures.
What follows is my current working model. Not a standard — there isn't one yet. A practical approach worth considering as your team navigates the same question.
Starting Point — What C4 Gets Right
Before extending anything it's worth being clear about what C4 already handles well when it comes to AI systems.
The four-level hierarchy maps cleanly onto the questions you need to answer about any AI deployment:
-
ContextWho are the users and what external systems does this touch?
-
ContainerWhat are the separately deployable units and how do they communicate?
-
ComponentWhat are the internal building blocks and their responsibilities?
-
CodeHow is the code structured?
The framework doesn't break down because the questions are wrong. It breaks down because the answers for AI systems don't fit the conventional element types — and the relationship notation assumes synchronous deterministic calls that agents frequently don't make.
The extension is about adding element types and relationship conventions that reflect how agentic systems actually behave — without abandoning the C4 principles that make it useful.
At the Context Level — Model Providers Are External Systems
Model providers — OpenAI, Anthropic, AWS Bedrock, Azure OpenAI — are external systems. They have defined interfaces, data flows, SLAs, and critically, data residency implications. If your system sends data to a model provider, that relationship belongs in your context diagram the same way any third party dependency does.
This matters beyond the diagram. A context diagram that shows your model provider forces conversations about:
-
What data leaves your system boundary and where does it go?
-
What happens to your system if the model provider has an outage?
-
Which model provider is each part of your system dependent on — and have you accepted that as a risk?
If your C4 context diagram was drawn before your organisation started using AI and hasn't been updated since, it is already incomplete. That's not an architecture problem. It's a governance problem waiting to surface.
At the Container Level — Three New Container Types
AI systems introduce three container types that pass the deployability test but don't fit the conventional labels.
At the Component Level — Inside the Agent Container
Inside an Agent Container, these are the components worth making visible — and the architectural conversation each one forces.
-
The Prompt Template LayerWho owns the prompts that define this agent's behaviour? Who can change them? What is the process for updating a prompt in production?
-
The Tool RegistryWhat can this agent actually invoke? Every tool in the registry is a capability — and a potential blast radius extension.
-
The Memory StoreWhat does this agent remember across sessions? Where is that memory stored? Who can read it, modify it, or delete it?
-
The Guardrails LayerWhat constraints exist on this agent's behaviour? If the answer is nothing formal — that belongs on the diagram too. An absent guardrails layer is an architectural decision, even if it wasn't made consciously.
The Part I Haven't Solved Yet — Relationship Notation
Traditional C4 relationship arrows represent synchronous calls. A calls B. B responds predictably.
Agentic systems break this in two ways:
-
Agents initiate actions — they don't just respond to calls.
-
Agent responses are non-deterministic — the same input produces different outputs.
Structurizr — the tooling built by C4's creator Simon Brown — has begun acknowledging AI agent workflows. They've released an MCP server for diagram validation and added support for AI agent use cases. But there is no official notation guidance yet for representing autonomous initiation or non-deterministic relationships.
My current pragmatic approach: annotate autonomous relationships explicitly — labelling them as "autonomous action" rather than "calls" — and note non-deterministic responses in the relationship description rather than leaving them implicit. It's not a clean solution. But it's honest.
Where This Leaves Us
C4 doesn't give us a standard for representing agentic AI yet. The architecture community is working on it and the gap is acknowledged at the research level.
What we can do in the meantime is be deliberate. Name the new elements. Draw the new boundaries. Ask the questions that the diagram forces — even if the notation isn't perfect yet.
An imperfect diagram that shows where your AI agents sit, what they can reach, and what governs their behaviour is significantly more valuable than a clean diagram that pretends AI isn't there.
The question "where does AI sit in your C4 diagram" is deceptively simple.
This article reflects the author's personal views and exploration. It is not affiliated with any employer.