Agent Workflow

Ask an agent to explain an architecture diagram it did not draw

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

The usual agent story runs one way: you describe a system, it draws. The reverse direction is quieter and more useful on a joining week. Point a connected agent at a diagram somebody else made, and it can answer questions about the system in the vocabulary the team actually uses, because that vocabulary is written on the nodes.

Try it free
6 min readFor new joiners and anyone inheriting a system they did not build

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

134/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Finding the right diagram first

The list tool returns the diagrams the key can reach, most recently updated first, each with its name, id, node count and last-updated date. That metadata is more useful than it looks on a joining week: a 40-node diagram updated last week and a 9-node diagram from eighteen months ago are different kinds of artifact, and the node count tells you which one is the overview.

Ambiguity here is the first failure mode. Three diagrams named after the same platform, and the agent reads the wrong one, then answers with confidence about a system that was decommissioned. Naming the id explicitly costs one line and removes the class of error entirely.

One other state is worth recognising rather than guessing at. A diagram created moments ago may still be drawing, and the read says so explicitly, reporting how many nodes have been placed and how many seconds have elapsed instead of returning an empty canvas that reads as a failure. The instruction attached to it is to wait about thirty seconds and read again, never to create a second diagram.

Reading a diagram as structure, not as a picture

The read tool returns the full structure of a diagram: every node with its type and its columns, every connection, and the groups. That text is what the model reasons over. The rendered image is for you, and passing include_image as false gives a structure-only read that costs a fraction of the context, which matters when the diagram is large or the session is already long.

Structure is a better substrate for questions than an image, because the relationships are explicit. What connects to the orders table is a lookup over edges rather than an inference from arrow geometry. Zone membership is a field rather than a judgment about which box sits inside which. Table columns are a list, so a lineage question about a single column is answerable rather than approximate.

This is also why a diagram made in a drawing tool answers fewer questions. A picture where the meaning lives in position and colour carries far less for a reader who is not looking at it, whether that reader is a model or a person reading a description of it aloud in a call.

Questions that get good answers

What feeds this table, and what reads from it. Which zone owns this service. What sits between the ingestion API and the warehouse. Which components have no inbound edges, which usually means either an entry point or something forgotten. What would break downstream if this job stopped, answered by walking the edges rather than by intuition.

Column-level questions work when the diagram carries columns, which is where a lineage diagram earns its keep: which source column ends up in this reporting field is a real answer rather than a guess about table-level flow.

Questions about quality do not work. Is this a good architecture, should we split this service, is this the right database: the canvas contains no information about load, cost, team ownership or history, so an answer would be the model reasoning from generic priors and dressing it in your node names, which is worse than no answer because it sounds specific.

What the canvas cannot tell it

No runtime truth. No traffic volumes, no latency, no error rates, no idea which of two paths actually serves requests today. A diagram is a declaration of structure, and structure is silent about behaviour.

Labels are claims. A node named payments-service is named that because somebody typed it, and it may have been renamed in the code eight months ago. A repository-linked diagram at least carries a commit and a sync time you can check, and that is the strongest reason to prefer one over a hand-drawn picture when the agent is going to answer questions from it. On a Terraform-backed diagram the link is tighter still: node ids are derived from the resource address, so a node traces back to a declaration in a named module and a named file rather than to whoever typed the label.

Absence proves nothing. A component missing from the canvas may not exist, or may simply never have been drawn, and the agent has no way to tell those apart from the diagram alone. When the answer matters, the right move is to have the agent confirm against the repository: name the file or module behind the node, then answer.

Pair the picture with the source

A diagram generated from a branch comes with a commit, which turns "the agent says" into something checkable. See repo to diagram.

FAQ

Can an AI agent read an architecture diagram and explain it?

Yes, when the diagram is structured data rather than an image. A connected agent reads every node with its type and columns, every connection and the groups, and answers questions such as what feeds a table, which zone owns a service, and what sits between two components.

Does the agent need the picture, or just the structure?

Just the structure for reasoning. Requesting the read without the image gives the nodes, edges and groups as text at a fraction of the context cost, which matters on large diagrams and long sessions. The rendered image is for the person in the conversation.

What kinds of questions should not be asked of a diagram?

Anything about quality or operations. The canvas holds no traffic, latency, cost, ownership or history, so questions like whether the architecture is good or whether a service should be split produce generic reasoning dressed in your node names, which reads as specific and is not.

How do you make sure the agent reads the right diagram?

Name the diagram id rather than the name. Listing diagrams returns names, ids, node counts and last-updated dates, and several diagrams often share a platform name, so an unqualified reference is how an agent ends up describing a decommissioned system with confidence.

Can the agent tell whether the diagram is missing a component?

Not from the diagram alone: an absent component looks the same whether it does not exist or was never drawn. Asking the agent to name the file or module behind each node, against a repository, is what turns absence into a checkable claim.