Drawing AI systems
AI systems are mostly ordinary systems with a few new building blocks: models, agents, tools, retrieval. So they live in the same architecture diagrams as your services and databases. You don't need a separate diagram type, and an AI feature can sit right next to the rest of your platform.
The building blocks
| Kind | What it is | Typical label |
|---|---|---|
llm | A language model endpoint | "Claude", "Chat model" |
model | Any other ML model (classifier, hosted embedding model, fine-tune) | "Intent classifier" |
agent | An LLM-driven loop that plans and calls tools | "Support agent" |
orchestrator | Coordinates several agents or steps | "Router / supervisor" |
tool | A function or API an agent can call | "Search orders" |
mcp | An MCP server exposing tools and resources | "GitHub MCP" |
prompt | A prompt template or system prompt | "System prompt v3" |
memory | Conversation or long-term memory | "Session memory" |
vectordb | A vector database or index | "pgvector" |
embedder | The embedding step | "Embed chunks" |
retriever | Retrieval: vector, keyword or hybrid | "Hybrid retriever" |
reranker | Re-ranking of retrieved passages | "Cross-encoder rerank" |
corpus | Source documents, the knowledge base | "Help-centre articles" |
chunker | Document splitting and ingestion | "Chunk 512 tokens" |
guardrail | Input/output safety, policy or PII filter | "PII redaction" |
eval | An evaluation suite or judge | "Groundedness eval" |
tracer | Observability: traces, token and cost metrics | "LLM traces" |
cache | Semantic or response cache (already available) | "Semantic cache" |
Arrows mean what they mean everywhere else: -> a call, ~> asynchronous or streamed, <-> two-way (an agent and its tool loop), -- an association. Use zone and group for boundaries such as "Agent harness", "Ingestion pipeline" or "Online / offline path".
Each kind has its own original glyph. Vendor references like use=anthropic/claude, use=openai/gpt, use=aws/bedrock, use=azure/openai or use=gcp/vertex draw the generic model glyph and keep the vendor name only as a hint; Inkline never bundles vendor logos.
Retrieval-augmented generation (RAG)
The offline path turns documents into vectors; the online path retrieves them for each question.
diagram architecture "RAG — basic"
direction right
group offline "Ingestion (offline)" {
corpus docs "Help-centre articles"
chunker split "Chunk 512 tokens"
embedder embed "Embed chunks"
}
vectordb index "Vector index"
group online "Answering (online)" {
client user "Chat UI"
retriever retrieve "Retriever"
llm model "Chat model"
}
docs -> split -> embed -> index
user -> retrieve : question
retrieve -> index : top-k
retrieve -> model : context + question
model ~> user : streamed answerAn agent harness
An agent is a loop: the model decides, calls a tool, reads the result and decides again. The harness around it is where most of the engineering lives.
diagram architecture "Agent harness"
direction right
person user "User"
zone harness "Agent harness" {
agent loop "Support agent"
prompt system "System prompt"
memory session "Session memory"
guardrail policy "Policy + PII filter"
tracer traces "Traces + token cost"
}
llm model "Chat model"
tool orders "Search orders"
mcp github "GitHub MCP"
eval checks "Task success eval"
user -> policy : message
policy -> loop
loop -- system
loop <-> session
loop <-> model : tool_use / tool_result
loop <-> orders
loop <-> github
loop ~> traces
traces ~> checks : nightlyTips
- Draw the data path (what the user's request touches) left to right, and put offline jobs (ingestion, evals) in their own
groupso they don't tangle with it. - Label tool calls with what flows (
tool_use / tool_result,top-k,context) rather than with the transport. - For the order of messages in one request, use a sequence diagram next to the architecture: user → agent → model → tool → model → user.
- Start from a template:
ink init --list-templatesshows RAG (basic and advanced), agent harness, multi-agent, LLM gateway, eval pipeline and two sequence diagrams (agent tool call, RAG request). The same templates are in the web gallery under AI systems.