Not recorded yet. The lesson below is complete and runnable today — the video is added later without touching this page.
recordings/B1.1.mp4Without a shared picture, 'secure the agent' has no referent and every later risk lands nowhere in particular.
One component map and five topologies, named once and reused by every lesson that follows.
Build the component graph and the five topologies, then trace one request through each and see where the trust boundary sits.
"Secure the agent" is not an instruction. It becomes one the moment you can point at a component and a boundary — and every risk in this chapter, every control in the next two, and every detection in Function E names something on the picture you are about to draw.
What it covers. Build the component graph and the five topologies, then trace one request through each and see where the trust boundary sits.
Why a security engineer needs it. Without a shared picture, 'secure the agent' has no referent and every later risk lands nowhere in particular. The control it builds is: one component map and five topologies, named once and reused by every lesson that follows.
This is a mapping lesson: every later risk and control in this function names a component from the picture it draws.
Every later lesson names a component from this map. Without it a risk lands nowhere in particular and cannot be argued about.
Draw CyberTravels as components and trust boundaries, and compute the crossings from the levels rather than listing them by hand.
The number of trust-boundary crossings — computed, so it moves when the architecture moves rather than when someone remembers to edit.
Measure this
| what to measure | denominator or target |
|---|---|
| trust-boundary crossings | count, computed from the levels so it moves when the architecture does |
+-----------+
request ---------->| ingress |
+-----+-----+
v
+----------------+ +-------------+
| orchestrator |------->| messaging |---> peers
+--------+-------+ +-------------+
v
+-------------------+ +-------------+
| agent runtime |<---->| model |
| plan . act . obs | | (predicts) |
+----+---------+----+ +-------------+
| |
+----------v-+ +---v---------------+
| tools /MCP | | knowledge /memory |
+------+-----+ +-------------------+
v
+---------+
| egress |
+---------+
identity + policy wrap every arrow · observability records every arrow
trust 0 (an outsider can write here): mcp, knowledge, and the corpusThese components exist under different product names in every agent platform, and the risks attach to the component rather than to the brand.
Ingress. Where a request enters: a chat surface, an API call, a webhook, a scheduled trigger, another system. It carries the requester's identity and whatever text they supplied.
Orchestrator. Decides which agent handles what, and in what pattern. In a single-agent system this is a few lines; in a multi-agent one it holds the whole design.
Agent runtime. The loop — plan, call a tool, observe the result, decide again, stop. This is the component that turns text into consequence.
Model. Predicts tokens. Holds no credential, opens no socket, changes nothing. Most of what people fear "the model doing" is done by the runtime.
Tools and MCP servers. The only components that change anything. An MCP server is a third party's process whose tool descriptions land in your context.
Knowledge and memory. Retrieval pulls documents in at query time; memory persists state across turns and sessions. Both inject text the user did not write.
Messaging. The agent-to-agent channel in a multi-agent pattern.
Identity and policy. Who is calling, on whose behalf, and whether this call is permitted. These wrap every other component.
Egress. Where data is allowed to go — the last boundary before it leaves.
Observability. What can be reconstructed afterwards.
Three of them carry content an outsider can author: MCP, knowledge and the corpus behind it. Those are the input surface for the next fifteen lessons.
One loop, one set of tools. Almost everything in production today.
user --> ingress --> agent runtime --> tools --> egress
| ^
v |
model (predicts; changes nothing)
identity + policy wrap every arrow · observability records every arrowThe edge that matters is agent runtime -> tools. That is where text becomes consequence, and it exists in every pattern below.
One planner fans work out to specialised workers and joins the results. The pattern most multi-agent platforms mean when they say "multi-agent".
+--> worker A --> tools
user --> orchestrator ----+--> worker B --> tools
+--> worker C --> tools
|
join / summariseNew surface: the orchestrator decides who runs, so anything that can influence its routing decides which permissions get used.
A pipeline of agents, each taking the previous one's output as its input.
user --> agent 1 --> agent 2 --> agent 3 --> result
recon analyse report
each hop inherits the previous hop's claims; nobody re-checks themNew surface: an unverified claim at hop 1 is a fact by hop 3. This is the shape that makes cascading hallucination (B1.12) a systems problem rather than a model problem.
Agents with no central planner, coordinating through state they all write to.
+--> agent A --+
user +--> agent B --+--> shared memory <--+
+--> agent C --+ ^ |
| |
every agent reads what any agent wroteNew surface: memory is a write-once, read-forever channel between agents. One poisoned entry is read back as trusted context indefinitely (B1.4), and there is no orchestrator to notice.
Deterministic control flow, with one or two steps handed to an agent. The pattern with the best safety properties, and the one people skip.
[fetch] --> [validate] --> (( agent step )) --> [approve] --> [commit]
deterministic non-deterministic deterministic
the blast radius of the agent is bounded by the two steps either sideNew surface: almost none, which is the point. If the work fits this shape, the other four patterns are a cost you do not have to pay.
Retrieval and human approval are not patterns of their own — they attach to any of the five above, and each brings one surface with it.
retrieval agent --> retriever --> corpus
^ |
+----- documents -------+
anyone who can write to the corpus writes to the context
human approval agent --> proposed action --> [ human ] --> tools
^
requests arrive faster than a person can read themRetrieval is how outside text reaches the context window without anyone typing it (B1.3). Approval is a real control for rare irreversible actions and a rubber stamp for everything else (B1.15).
+---------------+ +-------+
untrusted text | agent runtime | ----> | tools | consequence
---------------> | | +-------+
+---------------+
^ ^
knowledge messaging
memory MCPWhatever the topology, something reaches the agent runtime and the agent runtime reaches tools. Every risk in the rest of this chapter is a route into the left side of that picture. Every control in chapters 2 and 3 is an attempt to stand somewhere on the arrow.
The map is not a picture of CyberTravels — it is the procedure for drawing one of any agentic system, which is why every later lesson can name a box.
And it computes something, which is the part that makes a map arguable rather than decorative: the boundary crossings are derived from the trust levels, not listed. Change a level and the count changes. A diagram nobody can be wrong about is a diagram nobody has to agree with.
Five crossings, and two of them are the whole of Function B's injection material: ingress → orchestrator carries traveller text and knowledge → agent runtime carries retrieved documents, both from trust 0 into components that hold authority. B1.2 is the first of those edges and B1.3 is the second.
Then the line most maps never print: egress is absent. CyberTravels has no gateway, so "route it through the gateway" is not a control it can apply yet. Saying so on the map is what stops a later meeting designing controls for a component nobody has — and it is why B3.7 exists as a separate lesson rather than an assumption.
This map is not only a diagram in this commons. It is committed as code, at cybertravels/ — one directory per component on this map:
ingress/chat.py traveller text arrives (docstring: trust 0)
orchestrator/router.py dispatches to an agent
agents/ the four runtimes
tools/ the only things that change (docstring: trust 3)
mcp/vendor_server.py a third party's tool descriptions
knowledge/retriever.py documents nobody on staff wrote (docstring: trust 0)
messaging/bus.py agent to agentThe three components that carry outsider-authored content say their trust level in the first line of the file, because those are the three the next fifteen lessons are about.
There is no egress/, for the reason above. The absence is the point, and it is visible in the tree rather than only in a sentence.
Nine lessons later in Function C scan this tree rather than a fixture — C2.3 runs Semgrep over it, C2.4 verifies findings against it, C2.5 walks its call graph — and cybertravels/LABELS.md is the key: eight defects and four correct functions, written by hand before any scanner ran. Clone it and read it now if you like; you will meet it again.
The skill — skills/architecture/agentic-architecture-map/SKILL.md
name: agentic-architecture-map
description: >-
Draw a vendor-neutral map of an agentic system — ingress, orchestrator, agent
runtime, model, tools and MCP, memory and knowledge, messaging, egress — and
mark the edges where trust changes. Use before naming any risk, because a risk
with no component is an argument.
allowed-tools: Read, Grep, GlobEvery disagreement about agentic security is really a disagreement about which system is being discussed. The map fixes that: nine components and the edges between them, drawn the same way every time, so a risk can be pinned to a box and a control can be pinned to an edge.
First. Before threat modelling, before writing a risk register, and before any conversation that contains the phrase "secure the agent".
1 — Place the nine components. Ingress, orchestrator, agent runtime, model, tools, MCP servers, memory and knowledge, agent-to-agent messaging, egress. Draw every one even if a system has only a stub of it — an absent box is a decision, not a gap in the diagram.
2 — Draw the edges as data flow, not as call direction. Where text goes is what matters; who initiated the call is an implementation detail that hides whether untrusted content reaches the model.
3 — Mark the trust level of each component. Which ones receive content from outside the boundary, and which ones hold authority. The edge from a lower trust level to a higher one is a boundary crossing, and there are always more of them than expected.
4 — Annotate each edge with what crosses it. User text, retrieved documents, tool results, peer messages, credentials. This is what turns the picture into something a threat model can walk.
5 — Name the components that do not exist yet. A system with no gateway and no messaging is a smaller map, and saying that explicitly stops a later conversation about controls for components nobody has.
Input — the fixture committed at the top of scripts/agentic_architecture_map.py. Edit it and re-run: the buckets, counts and verdicts below are derived from it, not hard-coded.
9 components, 8 present at CyberTravels
component trust authority present
agent runtime 2 yes yes
egress 3 yes NO
ingress 0 - yes
knowledge 0 - yes
mcp servers 1 yes yes
messaging 2 - yesThe run continues past this. test_skills.py executes the script on every build, with no model configured — so what CI proves is that it runs and refuses legibly, not that it prints these lines. The output above is a recorded run against a real model, and nothing re-diffs it: a model's answer is not reproducible, and this repository does not claim otherwise anywhere it can be checked.
{
"components": [{"name": "str", "present": true, "trust": 0, "holds_authority": false}],
"edges": [{"from": "str", "to": "str", "carries": ["str"], "boundary_crossing": false}],
"crossings": 0,
"absent": ["str"]
}Three ways to do this lesson. Pick one. They run the same procedure against the same code — what changes is who drives it, and how much you see.
The agent reads the lesson, explains the idea, fetches the code, runs the check and answers your questions as you go. This is the one to take if you are here to learn.
Install it, once. From the folder you cloned. --all does every agent it finds on your machine:
python3 scripts/install_skills.py --all --lessons B1.1Then restart your agent and open it in that folder. On Windows, if python3 says Python was not found, use python instead.
Then pick b1-1-the-reference-architecture-for-agentic:
| agent | install just for this agent | start it |
|---|---|---|
| Claude Code | python3 scripts/install_skills.py --tool claude --lessons B1.1 | type /b1-1-the-reference-architecture-for-agentic |
| GitHub Copilot (VS Code) | python3 scripts/install_skills.py --tool copilot --lessons B1.1 | type /b1-1-the-reference-architecture-for-agentic in Chat |
| Cursor | python3 scripts/install_skills.py --tool cursor --lessons B1.1 | type / in Agent chat and search for it |
| Codex | python3 scripts/install_skills.py --tool agents --lessons B1.1 | type $b1-1-the-reference-architecture-for-agentic, or run /skills |
No agent, no conversation. The same lesson executes and prints the same readback. Take this one if you have no assistant, if you are reviewing rather than learning, or if you want the result without the teaching around it.
python3 scripts/lesson.py B1.1Neither of the above, and no model needed. The first command writes CyberTravels exactly as it stood at the end of this lesson; the second prints the diff — the lines this lesson added or changed, and nothing from any later one.
python3 scripts/checkpoint.py --at B1.1 --out work/cybertravels
python3 scripts/checkpoint.py --at B1.1 --diffOn Windows, type python wherever these say python3 — and use \ instead of / in the paths. Everything else is identical. A0.0 step 2 explains why.
Ways 1 and 2 need a model; way 3 does not. A signed-in Claude Code CLI needs no API key, and any OpenAI-compatible endpoint works too. With neither, the audit exits 2 and says so rather than inventing an answer. A0.0 sets this up.
Ways 1 and 2 both end with the same readback: What I did, What changed, The number and Read this next. A step that was skipped or refused is reported as exactly that, never as a pass.
If you did the last lesson’s challenge, expect this to stop. Most challenges ask you to edit the code, and ways 1 and 2 will not overwrite your edits: you get stopped, not a failure, with two options — --out for a fresh folder that keeps your work, or --force to discard it and start this lesson clean.
You can draw one agentic system you run as thirteen named components, say which of the five patterns it is, and name the three components in it whose content an outsider can author. That list is the input surface for the fifteen risk lessons that follow.
Draw your own system on one page, then mark the agent_runtime -> tools edge on it. Everything in chapters 2 and 3 is an argument about what is allowed to stand on that arrow, and you will get more out of them having drawn it first.
Skill source: skills/architecture/agentic-architecture-map