Khalid ShamsPrincipal Solutions Architect

Learn AI The SHAMS AI Atlas Follow one request

See what each part does, and how the whole system works.

Flagship lesson. A customer's order arrived damaged. Resolve the request without exceeding the system's authority. Teaching simulation · synthetic data

A requester brings a damaged lamp to a workshop. A software operator works at a cobalt context tray while an owner and a reviewer oversee the boundary.Outline operator: software metaphor · ⏸ Review boundary

Inside the workshop

One request. People, evidence and a boundary.

The requester brings the problem. The owner sets the goal. The outline operator is a software metaphor, and the reviewer decides whether a proposed action may cross the gate.

The illustration sets the scene. Run the lesson below to inspect each proposal, permission check and result.

Start the interactive lesson ↓
Follow one request through a governed AI systemAn example architecture drawn as a workshop. People stand outside the application runtime. Inside, an agent operator works at a bench with a goal card, a bounded context tray, a model engine and a tool dock, next to a procedure binder, a notes cabinet and a policy library. Tool calls cross the runtime wall through authorization gates to connected services. A human approver sits outside the boundary. A policy specialist station, a budget gauge, a hand-off tray and an event trail complete the scene. A text version of every step follows the drawing. APPLICATION RUNTIME · EXAMPLE ARCHITECTURECONNECTED SERVICESPEOPLE Accountable ownerSupport operations leadOwns the goaland the policyOwnerpolicy + successcriteria (signed) RequesterCustomer, order A-1042TASK BRIEFLamp arrived cracked.Order A-1042.Photos sent Tuesday.Client appauthenticatedcustomer sessionPOST /support PROCEDURE BINDERDamaged item v3Skill packageSKILL.md + scriptsloaded on match NOTES CABINET29 Sep · photos ×2Memory storeper-customer notesscoped readsfreshness check POLICY LIBRARYowned · versioned · filteredRetrieval servicepolicy indexpermission filterprovenance on hits GOALResolve A-1042within refund policy3 success criteriaRun goalsuccess criteriaverified fromrecords orderDISPATCH BOARDDelegation callwork order schema MODELreplaceable · pinnedLLM APImessages incontent + stop_reason outmodel id pinned AGENT LOOPsoftware metaphorAgent looporchestrator code CONTEXT · THIS CALL ONLYInstructionsRequestProcedureSaved notePolicy §4.2OrderRefundReplyContext assemblyprompt builder: instructions, request,loaded skill, notes, passages, results TOOLS$Toolsschemas MCPMCP clients CHECKpre-call hook orders:readauthz refunds:issueauthz messages:sendauthz ORDERSOrdersMCP serverMCP server · orderstools/list, tools/callown authorization REFUNDSRefundsMCP serverMCP server · refundstools/list, tools/callown authorization MESSAGINGMessagingMCP serverMCP server · messagingtools/list, tools/callown authorization PROPOSED OPERATIONissue_refund 84.00awaitingHuman approvalDuty supervisorApproval workflowhuman task queuedecision recorded POLICY SPECIALIST · OWN CONTEXTsoftware metaphorWORK ORDERRESULTretrieve_policygrantedissue_refundnot granted (configured)Subagent · policyown context windowtools: retrieve_policy onlyidentity: as configured(not a sandbox by default) BUDGET0/10Run limitssteps, time, spend HAND-OFFHandoff queueretry policycompensation EVENT TRAIL · SYNTHETICEvent logrun id, typed events, decisions (no model reasoning) requestowns the goalpassage + provenanceorder recordrefused at the gateresultapprovalwork orderresult + evidencehand-off

Ready

Press "Follow the request" to start.

One customer request, followed through an example AI system: who owns it, what goes on the desk, what the model proposes, what is checked before anything happens, and how the run ends.

Also in the atlas: How a model is made Content version 2026.10.3 · reviewed against primary sources on 2 October 2026

Follow the thread

Question. Evidence. Proposal. Boundary. Receipt.

Five reading chapters help you find your place. The chapter controls above follow the actual lesson, including its stops and denied actions.

A cobalt reading thread connects five workshop vignettes: question, evidence, proposal, boundary and receipt.Outline operators: software metaphor · Reading order, not runtime flow
The cobalt thread is navigation between chapters, not a connection between running services.
A human reviewer holds a proposal beside an outline software operator, an evidence tray and a closed gate.Outline operator: software metaphor · ⏸ Proposal awaiting review
⏸ A proposal waits for review. Approval permits an attempt; the returned result and verification tell you what happened.

Inspect the approval step →

Text version

The same lesson, in words.

Teaching simulation. Every record, policy, name and event is synthetic. Nothing here calls a model or a real service, and the gates in the drawing represent enforcement; they do not enforce anything.

  1. Request. A customer asks for help. The customer reports that order A-1042 arrived with a cracked lamp base. The application creates a run with a goal owned by the support operations lead.
  2. Context. The application sets the desk. Context is assembled for the first model call: standing instructions and the request. Nothing else is on the desk yet.
  3. Context. A procedure card is selected. The skill description 'damaged item' matches, so the application loads the Damaged item procedure v3. It is guidance for this task, not a worker and not a permission.
  4. Context. A relevant earlier note is loaded. Memory holds an entry from this customer's earlier session: two photos of the cracked base, uploaded 29 September. It is relevant, permitted for this customer and recent, so it goes on the desk.
  5. Model. The model proposes a lookup. The model reads the desk and proposes a tool call. It does not run the call. The response ends with stop_reason tool_use, which says why this response stopped, nothing more.
  6. Authorize. The read is checked and allowed. The application validates the arguments and checks the agent identity's scopes: orders:read is granted. Allowed.
  7. Execute. The Orders service answers. Through its MCP client the host calls tools/call on the Orders server. The record comes back and is added to the desk for the next model call.
  8. Evidence. The policy passage is retrieved. The application searches the policy library for this case. Returns policy v7 section 4.2 comes back with its provenance and goes on the desk.
  9. Model. The model proposes a refund. Order, note and policy are on the desk. The model proposes issue_refund for $84.00 and cites its evidence. It is still only a proposal.
  10. Authorize. Allowed, but approval required. The pre-call check confirms the arguments match the records: $84.00 is the order total and the money goes back to the original payment method. Then the gate: refunds:issue is granted, but the amount is over $50, so the rule routes it to a human approver before execution.
  11. Approve. A supervisor approves. The duty supervisor sees the exact operation, the order record and the policy passage, and approves. The decision is recorded and returns through the gate.
  12. Execute. The refund is issued. The approved call goes to the Refunds server with an idempotency key. The result comes back to the desk.
  13. Model. The model drafts the reply. With the refund result on the desk, the model proposes a reply to the customer.
  14. Execute. The reply is sent. Sending is allowed and the message goes out. A sent message cannot be unsent, which is why it comes after the refund succeeded.
  15. Verify. The application verifies the goal. The model's last response ended with end_turn. That is not the success signal. The application checks the criteria against records: refund issued, amount within policy, customer notified. A reply that cited a policy nobody retrieved would fail here.

How a run can end

A model's stop reason says why one response ended. It is not proof that the task succeeded. These are the run's own outcomes.

The 25 concepts in this scene

Accountable owner People and products
The named person who owns the outcome and the refund policy. Someone signs for what the system is for and what wrong costs. The goal pinned on the agent's desk comes from them, not from the model. Where the analogy stops: Ownership is an organisational fact; the line in the drawing is a reminder, not a mechanism.
Requester People and products
The person who asks for something. Here, a customer whose lamp arrived cracked. The request starts the run. It is input, not authority: what the customer asks for and what the system may do are separate questions. Where the analogy stops: Drawn as a person because this one is a person. Solid figures in the scene are real people; outline figures are software.
Skills Context
A procedure card pulled from a binder when that kind of task comes up. A skill is a package of instructions, scripts and resources. A short description is visible; the full content loads when the task matches. It is know-how, not a worker. Where the analogy stops: A card is passive paper; a skill can include scripts that run with whatever permissions the runtime gives them.
Memory Data
A notebook kept between sessions, reopened to the page that matters now. Memory persists facts, preferences, summaries or task state outside the context window. It helps only when the application selects a relevant, permitted, fresh entry and puts it on the desk. Where the analogy stops: A notebook entry stays as written; stored memories can be wrong, stale or summarised badly.
Retrieval (RAG) Context
Relevant pages pulled from reference shelves and brought to the desk. Retrieval selects passages from governed sources for this request and adds them to the context, with where they came from. It is a pattern, not a product: search, filters and permissions matter as much as any vector index. Where the analogy stops: A shelf suggests a fixed book; indexes go stale and retrieval can pick the wrong page.
Goal verification Control
Checking the work against the goal before calling it done. The run succeeds when the application verifies the success criteria (refund recorded, amount within policy, customer told), not when the model says it has finished. Where the analogy stops: A tick looks final; verification is only as good as the criteria.
Coordinator Agents and orchestration
A dispatch board that issues bounded work orders and combines what comes back. An agent that delegates part of the work to specialists, giving each a specific task and selected material, then merges their structured results. Where the analogy stops: A dispatcher manages people; a coordinator is the same loop with delegation calls.
Model (LLM) Models
The engine that reads what is on the desk and writes a response. An autoregressive language model produces output one token at a time (tokens are word pieces). It can propose a tool call, but it does not execute anything itself. Where the analogy stops: An engine suggests mechanism; a model is learned statistics, and the same input can produce different output.
Agent Agents and orchestration
Software that works toward a goal in steps: it looks, decides, uses a tool, checks, and goes again. A bounded control loop. The application calls the model with the current context; the model either answers or proposes a tool call; the application runs permitted calls and feeds results back until the goal is verified or a limit, denial, cancellation or handoff ends the run. Where the analogy stops: The operator is a drawing of software behaviour. It does not understand, intend or want anything.
Context Context
The desk: only what is placed on it for this call is available. Context is the set of tokens sent with one model call: instructions, the request, loaded procedures, selected notes, retrieved passages and tool results. It is finite and assembled fresh for each call. Where the analogy stops: A desk keeps things between visits; context does not. Each call gets what the application sends.
Tool Tools and protocols
A specific instrument: a defined input goes in, a result comes back. The model proposes a call with arguments; the application validates, authorizes and executes it, then returns the result to the context. Where the analogy stops: An instrument does one thing; a tool is software that can fail, time out or change.
MCP Tools and protocols
Compatible connectors between the workstation and the service stations. A protocol with three roles: the host application, one MCP client per connection, and MCP servers that expose tools, resources and prompts. It standardises how context and calls are exchanged. Where the analogy stops: A plug fits or it doesn't. A protocol connection can be live while a specific call is still refused.
Guardrails and hooks Control
Checks in code that run before or after a tool call, outside the model. A pre-call check can compare the proposed arguments with the records (amount no more than the order total, money back to the original payment method) and block the call. Some hooks only log and some ask another model; only a check in code that can block the call is a rule. Where the analogy stops: A locked gate stops everyone. A check stops only what it was written to test; anything it does not test passes straight through.
Authorization check Control
An identity checked at a gate before an action goes through. Code outside the model decides whether this caller may perform this operation with these arguments: allow, deny, or require approval. In Claude Code, for example, a PreToolUse hook can return allow, deny or ask; other hooks only observe. Where the analogy stops: This is a teaching simulation. A gate in a drawing, or a toggle in a web page, enforces nothing.
Connected service Tools and protocols
The station that actually does the work: looks up the order, issues the refund, sends the message. Business systems behind the protocol. They keep their own records and should enforce their own permissions too. Where the analogy stops: Stations look independent; real services share failure modes and dependencies.
Human approval People and products
A person reviews a proposed action before it happens. The application pauses a specific operation and asks an accountable person. A second model reviewing the action is not the same thing. Where the analogy stops: The drawing shows one person; real approval needs identity, an audit record and a timeout path.
Specialist Agents and orchestration
A separate station that receives one work order, uses its own few tools and returns a compact result with evidence. A specialist runs with its own context: only the work order and what it fetches. Its tool set is whatever is configured; in Claude Code, subagents inherit the main tools unless restricted. Where the analogy stops: The station looks like a separate room. Unless you configure isolation, it is not one.
Limits and budget Control
A gauge of steps and spend with a hard stop. A run stops when its step, time or cost budget is used up. That is a legitimate bounded exit, but it is not success. Where the analogy stops: The gauge counts steps in this lesson; real budgets count tokens, time and money.
Recovery Control
What happens when something goes wrong: stop, undo where possible, or make it right another way. Prevention (deny before execution), cancellation (stop pending work), rollback (undo a reversible change) and compensation (a new action that offsets one that cannot be undone) are different tools. Where the analogy stops: Nothing in the drawing undoes a sent message.
Event trail Control
A trail of stamped events you can follow back. Recorded events: model calls with stop reasons, proposed and executed tool calls, authorization decisions, approvals, errors and the final outcome. Where the analogy stops: The trail shows what was recorded, not why the model produced what it did.
Tokens Models
The small pieces of text a model reads and writes: words, parts of words, characters or bytes. Text is encoded into tokens before the model processes it, and a response is produced token by token. For Claude a token is about 3.5 English characters on average, varying by language. Context windows are measured in tokens. Where the analogy stops: Building bricks have fixed shapes. Tokenizers differ between models, so the same text can be a different number of tokens.
System prompt Context
The standing brief at the top of every call: role, rules, tools and format. Instructions the application sends with every model call, separate from the user's message. It sets role, constraints and output format and shapes behaviour strongly, but it is still text the model reads. Nothing in it enforces itself. Where the analogy stops: A new colleague remembers a briefing and a manager can hold them to it. A system prompt is sent again on every call and holds nobody to anything; the checks and gates do that.
Prompting Context
How a request is written: what is needed, why, and what good looks like. The request, with any examples and constraints, is the part of the context people write. A clear, specific ask with the reason behind it and a few relevant examples steers format and quality more reliably than clever wording. Where the analogy stops: A colleague you brief can ask a follow-up question. A model answers whatever it was sent and fills gaps with likely text unless the design asks it to stop and ask.
Hallucination Models
A fluent, confident statement that nothing the model was given supports. Models produce likely text, and when evidence is missing likely text can still read as fact. Quoting sources, permission to say 'I don't know', restricting answers to provided documents and checking claims against records reduce it. They do not eliminate it. Where the analogy stops: A student who guesses usually knows it. A model has no separate signal that a sentence is unsupported unless the design creates one.
Prompt injection Control
Text inside content the system reads that tries to give the model instructions. Records, documents and tool results are data, but a model cannot always tell data from instructions. Labelling untrusted content and its source, screening tool outputs, narrow permissions and checks on consequential actions reduce the risk. None of them removes it. Where the analogy stops: A forged note fools one person once. Injected text can sit in a record and be read on every run until someone removes it.

Sources

The workshop metaphor, the scenario and its numbers are teaching devices written for this site. They are not quoted from the sources.