Running Workshop 1 — a complete delivery walkthrough

A move-by-move walkthrough of what Workshop 1 looks like when delivered to a group of engineers over two hours. Read this first to understand the shape. Then open the Workshop 1 build guide for the actual code.

The shape — 2 hours, 5 moves

Move	Time	What happens
Opening	10 min	Frame the session · 3 pre-checks · the 5-move time map
1 · Setup	20 min	Make a folder · install the SDK · explain the 5 SDK names while the install runs
2 · The skeleton	25 min	Paste 4 blocks · configuration · tool groups · system prompt · task prompt · the runner
3 · 🌟 Hit GO	15 min	Run the single agent · narrate the live log · let the room watch their own terminals
4 · Multi-agent	25 min	Add three subagents · convert the parent to orchestrate · run the multi-agent flow
5 · Close	10 min	Connect what they built to where they go next · open the floor

Plus a 5-minute breather between Move 3 and Move 4. Total: ~110 minutes with buffer.

Opening · 10 min

The connecting frame:

“This session is two hours. By the end, you have a working AI agent on your laptop. About two hundred lines of TypeScript. We will mostly paste code together. You do not need to be a TypeScript expert.”

Permission to ask:

“If you get stuck, raise your hand. Do not silently struggle. There are two of us in the room — one driving, one supporting. We are here so every laptop runs by the end.”

The 5-move map — walk it on a whiteboard or slide. Engineers need a map of the next two hours before the journey starts.

The three pre-checks — type each one on the projected terminal:

node --version          # need 20.x or higher
which claude            # confirm the CLI you'll use is available
ls workshop-folder/     # confirm the shared workshop folder is accessible

Wait 60 seconds. Hands go up for whatever is missing. Floor support fixes individually while everyone else proceeds.

“Good. Let’s begin.”

Move 1 · Setup + the SDK import · 20 min

Type on the projected terminal — keep it visible the whole move:

mkdir claude-agent-sdk-training
cd claude-agent-sdk-training

Walk the room through pasting package.json and tsconfig.json from the build guide. Two small configuration files. They don’t do work — they tell the computer what libraries to fetch and what TypeScript rules to follow.

The one library that matters:

@anthropic-ai/claude-agent-sdk

Run the install:

pnpm install

While the install runs (3–5 minutes on a fresh laptop), walk to the front and explain what the SDK gives you. Five names:

Name	What it does
`query`	Starts one Claude Agent SDK run
`Options`	Configures model · cwd · tools · permissions · prompts · subagents
`SDKMessage`	Live events streamed from the run
`SDKResultMessage`	The final result
`AgentDefinition`	Defines a subagent the parent can call

Five names. You will see all five in two minutes.

Checkpoint — hands up if pnpm install finished. Floor support helps anyone stuck. Continue once 80%+ are done.

Now paste the imports. Top of src/index.ts — exactly the five names from the table above.

Pause. Check the room. Ask: “Any questions before we move on?” (Use the local language for this check-in — a bilingual room will not volunteer questions in their second language.) Wait 5 seconds. Then move on.

Move 2 · The single-agent skeleton · 25 min

“Now we put four pieces in place. Configuration. Tool groups. The agent’s identity. The agent’s task. Then a runner that drives it.”

Paste step 3 — RunConfig. The settings block. Working directory, model (Opus), how many incidents (5), how recent (last 6 months). Environment variables so the room can change them without editing code.

Paste step 4 — tool groups. Two named lists:

SAFE_RESEARCH_TOOLS — WebSearch, WebFetch, Read, Glob, Grep
WRITING_TOOLS — Write, Edit

The agent will get both. When we add subagents, the subagents only get the research tools. They cannot write files. Only the parent writes. This is how we control what each agent can do — the simplest form of governance.

Paste step 5 — the system prompt. The agent’s identity. The stable role.

“You are an Incident Collector Agent. Collect only AI-related incidents. Never invent sources. If evidence is weak, reject the case.”

This stays the same across every run. The task changes — but the identity stays.

Paste step 6 — the task prompt. The job. Collect five incidents. Here is the exact schema. Write two output files.

Important — the prompt explicitly says: do not pad. If you cannot find five real incidents, write fewer. Be honest about evidence quality.

“This is how we tell the agent — it is OK to under-deliver. It is not OK to invent.”

Paste step 7 — the runner loop. The longest block. About a hundred lines. Engineers paste it without trying to understand every line right now.

What they need to know: this is the function that drives the agent and prints every move it makes. Every search. Every page it reads. Every file it writes. Live in the terminal.

Typecheck before running:

pnpm typecheck

Silence on the terminal = success. A red error = a typo somewhere. Floor support helps.

Move 3 · 🌟 Hit GO · 15 min

Paste step 8 — runSingleAgent. Then step 9 — the entrypoint.

Now the command:

pnpm start

First 20–30 seconds — nothing happens. Tell the room: do not worry, do not kill the program. The agent is connecting and choosing its first search query.

Then the log starts streaming. Narrate it live:

[single-incident-collector] START agent run
[single-incident-collector] SYS session initialized
[single-incident-collector] A I'll search for recent AI incidents...
[single-incident-collector] T WebSearch query=LLM coding agent incident 2026
[single-incident-collector] T WebSearch query=AI agent security incident 2026
[single-incident-collector] R WebSearch: 12 results found
[single-incident-collector] A Let me verify the most concrete-sounding incidents...
[single-incident-collector] T WebFetch url=https://...
[single-incident-collector] R WebFetch error: 403 Forbidden
[single-incident-collector] T WebSearch query=Replit AI agent deleted production database
[single-incident-collector] A Replit case is from July 2025 — outside the 6-month window.
                              Let me verify the more recent candidates.
[single-incident-collector] T WebFetch url=https://www.anthropic.com/news/disrupting-AI-espionage
[single-incident-collector] R WebFetch: 209,339 bytes
[single-incident-collector] T Write file_path=.../incidents.jsonl
[single-incident-collector] T Write file_path=.../01-incident-registry.md
[single-incident-collector] DONE success turns=19 cost=$0.9956

Log code	Meaning
`START`	The agent process is alive
`SYS`	The model connection is open
`A`	The agent is reasoning to itself
`T`	A tool was called — search, fetch, write
`R`	A tool result came back
`DONE`	The run completed

The A line where the agent rejects an out-of-window incident is the key moment. When the room sees that — the agent following its own rules under real-world ambiguity — the workshop has landed. Do not announce it. Let the room notice on their own.

After ~5 minutes, the run completes. Check the outputs:

ls outputs/single/workshop-outputs/
# 01-incident-registry.md

Open the markdown. Read out the first incident title. Click the URL. The dates are real. The sources are real. The room can verify the agent’s work in 60 seconds.

5-minute break. Engineers stretch. Floor support handles individual questions.

Move 4 · Convert to multi-agent · 25 min

“Same agent. We add three subagents.”

One agent doing everything is one worker. Three subagents = specialists.

A general discovery subagent
A coding-agent-specific discovery subagent
A verifier subagent

Each subagent has its own job, its own prompt, its own tools. The discovery subagents cannot write files. Only the parent agent writes the final files.

Paste step 10 — subagent definitions. Three named entries, each with a description, a prompt, a tools list, a model (Sonnet — cheaper than the Opus parent).

Paste step 11 — the multi-agent prompt. The orchestration is in the prompt:

Use the discovery subagent for broad discovery
Use the coding-agent discovery subagent for agentic-AI incidents
Merge candidate lists yourself (the parent)
Use the verifier subagent to validate sources
Write the final files yourself

The parent decides the sequence. The subagents do their bit and return notes.

Paste step 12 — runMultiAgent + the entrypoint update. One new option: agents. That tells the SDK about the subagents. They become available through the Agent tool.

Now run:

pnpm start -- --multi

The log changes shape. New scoped labels appear:

[multi-agent-incident-collector] START agent run
[multi-agent-incident-collector] T Agent -> incident-database-discovery
[multi/incident-database-discovery] A I'll search for AI incidents in the recency window...
[multi/incident-database-discovery] T WebSearch ...
[multi-agent-incident-collector] T Agent -> coding-agent-incident-discovery
[multi/coding-agent-incident-discovery] T WebSearch ...
[multi-agent-incident-collector] T Agent -> incident-verifier
[multi/incident-verifier] A Verifying sources for each candidate...
[multi-agent-incident-collector] T Write file_path=.../incidents.jsonl
[multi-agent-incident-collector] T Write file_path=.../01-incident-registry.md
[multi-agent-incident-collector] T Write file_path=.../collection-method.md
[multi-agent-incident-collector] DONE success turns=27 cost=$1.4823

Three scoped labels on one screen — parent, two discovery subagents, one verifier. Working together. On the engineer’s own laptop.

Open the multi-agent outputs:

ls outputs/multi/workshop-outputs/
# 01-incident-registry.md
# collection-method.md

The new file — collection-method.md — is the parent’s notes on which subagent found what. The work is now auditable. You can see who did what.

Move 5 · Close · 10 min

“Look back at what you just did. Two hundred lines of TypeScript. Two runs. One single agent. One team of four — one parent and three subagents.”

The cost of two runs — about three dollars. The time — about ten minutes of compute.

This is the agent primitive. The same primitive that watches mailboxes, monitors alarms, processes inbound requests, drafts reports — any workflow where an agent reads, decides, and writes. The domain changes; the primitive stays.

Open the floor. Take questions. The room may want to discuss:

How does the agent decide what to search? (the model + the prompt + reasoning)
What happens if the agent runs in a loop? (maxTurns cap, the safety bound)
How do we deploy this in production? (the parent is one piece; orchestration around it is the production system)
What about cost at scale? (subagents on Sonnet are ~20% the cost of Opus; budget controls in the orchestration layer)
Can we use a different LLM? (yes — the SDK is provider-agnostic when paired with a router; for Anthropic’s SDK specifically, swap the model name)

Common surprises and what to do

What happens	What to do
Long silence after `pnpm start`	Wait 30 seconds. The agent is connecting + choosing its first query. Then the log starts.
`403 Forbidden` on a WebFetch	Expected. Many sources block automated requests. The agent will try a different source.
Agent says “only 3 verified incidents, not 5”	Accept it. The prompt told the agent not to invent. This is correct behaviour.
`429 Too Many Requests`	Wait 60 seconds and rerun. If using a shared key, switch to a different provider routing.
Agent finishes but `outputs/` is empty	Check `permissionMode` is `"acceptEdits"`. If `"ask"`, the agent paused for permission.
Typecheck shows errors after pasting	Likely a wrong-order paste or a missing brace. Re-paste the section that fails.
Cost much higher than $1	`INCIDENT_COUNT` may be set high, or the model is Opus running long. Drop count, switch to Sonnet via env.

Why this format works

Three reasons this two-hour workshop tends to land well:

Paste-driven, not type-from-scratch. Engineers don’t need to learn TypeScript. They paste 9 sections in sequence; the presenter narrates what each section does. Cognitive load goes to understanding the agent, not to writing code.
The first ~30 seconds of pnpm start look like nothing. This is the moment to NOT fill the silence. When the log starts, the room is ready to watch.
The agent rejects a result on its own. Without prompting, without scripted theatre — the agent obeys its instructions. That is the moment where the room understands what they just built.

What this primitive scales to

The single agent → multi-agent pattern is the kernel. Beyond it:

A company of many subagents — multiple parent agents, each with its own subagent team, sharing a library and a memory layer.
Long-running agents — heartbeats, scheduled wakeups, persistent state across runs.
Channel-driven agents — WhatsApp, email, Slack, Teams — the agent receives, processes, and replies on the channel its user prefers.
Cross-agent memory — what one agent learns yesterday, another agent reads on its way in today.

These are not in Workshop 1. They live in the Workshop 2 build guide and Workshop 3 hooks guide, and in the broader LifeOS · Living AI Office platform.