Inkline
Menu
Docs / Start here

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

KindWhat it isTypical label
llmA language model endpoint"Claude", "Chat model"
modelAny other ML model (classifier, hosted embedding model, fine-tune)"Intent classifier"
agentAn LLM-driven loop that plans and calls tools"Support agent"
orchestratorCoordinates several agents or steps"Router / supervisor"
toolA function or API an agent can call"Search orders"
mcpAn MCP server exposing tools and resources"GitHub MCP"
promptA prompt template or system prompt"System prompt v3"
memoryConversation or long-term memory"Session memory"
vectordbA vector database or index"pgvector"
embedderThe embedding step"Embed chunks"
retrieverRetrieval: vector, keyword or hybrid"Hybrid retriever"
rerankerRe-ranking of retrieved passages"Cross-encoder rerank"
corpusSource documents, the knowledge base"Help-centre articles"
chunkerDocument splitting and ingestion"Chunk 512 tokens"
guardrailInput/output safety, policy or PII filter"PII redaction"
evalAn evaluation suite or judge"Groundedness eval"
tracerObservability: traces, token and cost metrics"LLM traces"
cacheSemantic 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 answer
RAG — basic 7 items and 7 connections. Ingestion (offline) Answering (online) question top-k context + question streamed answer Help-centre articles Chunk 512 tokens Embed chunks Vector index Chat UI Retriever Chat model
RAG — basic, drawn from the text above

An 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 : nightly
Agent harness 10 items and 9 connections. Agent harness message tool_use / tool_result nightly User Support agent System prompt Session memory Policy + PII filter Traces + token cost Chat model Search orders GitHub MCP Task success eval
Agent harness, drawn from the text above

Tips

  • Draw the data path (what the user's request touches) left to right, and put offline jobs (ingestion, evals) in their own group so 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-templates shows 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.