Overview

• Time estimate: 60 minutes (this exercise includes more material than most people finish in an hour — see the note below)
• Difficulty: Intermediate. Comfortable with a terminal; no coding required.
• Format: Individual, hands-on, self-paced. Someone will be circulating to help with technical blockers (a gateway not starting, a port conflict, etc.) — but the challenges themselves are yours to work through and explain.

You should already have Hermes installed and confirmed working (Day 7 pre-work). If you haven't done that yet, do it now before continuing — flag it to whoever's facilitating rather than trying to debug an install mid-exercise.

• Main — the entry point. You talk to Main. It doesn't answer topic questions itself.
• Proxy — a broker. It's a directory that maps a topic to the agent that handles it. It doesn't answer topic questions either.
• Three researcher agents — one each for workouts, injuries, and nutrition. Each is an expert in exactly one topic.

The rule that makes this a real test of the protocol: nobody knows anybody except through the Proxy. Main doesn't know the researchers exist. Researchers don't know Main or each other exist. Everything routes through the broker.

setup.sh — builds the five agents (run once)

This script does four things, in order. First, it creates one Hermes profile per agent — a profile is an isolated identity with its own settings and memory:

--clone copies your default profile's model and login so you're not re-entering an API key five times. The existence check is what makes it safe to run setup.sh more than once — it won't clobber a profile that's already there. The same pattern repeats for a2a-main and the three researcher profiles.

Second, it copies each agent's identity file into place:

SOUL.md is plain Markdown — the file you'll edit yourself in the Proxy-upgrade step later. Whatever it says the agent is, the agent behaves as. There's no code here; the "programming" is a written identity.

Third, it turns on an inbound server for the Proxy and each researcher, each on its own port:

This is why the ports differ per agent — 9901 for the Proxy, 9911/9912/9913 for the researchers. Two agents can't share a port on one machine, so each gets its own.

Fourth and last, it gives Main the opposite of a server — the ability to call out:

Main never listens on a port in this setup — it only makes outbound calls.

start-all.sh — brings everyone online and registers the researchers

Where setup.sh builds the agents, start-all.sh actually starts them as running background processes and wires up the registry. It begins by making sure the Proxy's registry file exists and starts empty:

That registry.json file is the entire broker — it's just a JSON file on disk mapping topics to researchers. You'll look at this file directly in a later challenge.

Then it starts each server in the background:

The trailing & is what makes it a background process instead of blocking the terminal, so the script can move on to starting the next agent instead of waiting forever. Hermes itself keeps track of which gateway process belongs to which profile — that's what makes it possible to stop a specific agent later by profile name alone (see stop-all.sh below). The same lines repeat for each researcher, with a different port and description each time — this is also where each researcher's Agent Card description comes from, if you want to curl one later and see it reflected back.

After a fixed wait for everything to boot, it registers each researcher with the Proxy — the moment they actually become discoverable:

This line is the entire "join the network" step for a researcher: topic, its own endpoint URL, a name, a description, and some alias keywords. It works by calling examples/register.sh, which is worth reading on its own (next section) since it's the rawest look at the protocol in the whole kit.

examples/register.sh — the actual wire format

This is the one script worth reading in full, because it's not a convenience wrapper — it is the protocol, with nothing hidden. It builds one line of text:

— and then sends it as a JSON-RPC SendMessage call over plain HTTP:

Strip away the JSON-RPC envelope (jsonrpc, id, method) and what's actually being communicated is just parts: [{ text: "REGISTER topic=nutrition name=nutrition_researcher card=http://127.0.0.1:9913 ..." }] — a plain text instruction inside a standard message shape. The Proxy's whole job (defined in its SOUL.md) is reading that text and deciding what to do with it. examples/resolve.sh and examples/list.sh are the same envelope with a different one-line message (RESOLVE <topic> and LIST) — once you've read register.sh, you've effectively read all three.

stop-all.sh and stop-agent.sh — stopping agents by profile

Stopping an agent doesn't involve tracking its process yourself — Hermes already knows which running process belongs to which profile, so you just ask it to stop that profile's gateway:

stop-all.sh does this for the Proxy and the three built-in researchers. stop-agent.sh <topic> (which you'll use in one of the challenges) does the same thing for a single named agent — it first turns the topic into a profile name (proxy → a2a-proxy, anything else → a2a-res-<topic>), then stops just that one:

Neither script touches the registry. Stopping a researcher this way doesn't tell the Proxy anything happened — the Proxy will still have that researcher's card on file, unaware it's now unreachable. That gap is exactly what one of the upcoming challenges is designed to expose.

clean-all.sh — full teardown

This one builds on what you just saw, plus one more piece: it also has to account for any researcher you add later with add-researcher.sh, since those aren't part of the original five. It runs in three parts:

1. Stop the built-in agents, the same way stop-all.sh does.
2. Find any extra researcher profiles — anything named a2a-res-* that isn't one of the three built-ins — and stop and delete each one:

This is why clean-all.sh is the right tool for a full reset if you've been experimenting with add-researcher.sh — stop-all.sh alone won't touch anything you added, since it only knows about the original five.

3. Delete the five built-in profiles outright (hermes profile delete -y a2a-proxy, etc.) and remove the logs/ folder.

Worth knowing about for later if you want to wipe the network — including anything you added — and rebuild from scratch with ./setup.sh && ./start-all.sh.

setup.sh creates the five agent profiles and installs each one's identity. start-all.sh starts all five, waits for each to come online, then registers the three researchers with the Proxy.

If something doesn't start: check the relevant file in logs/. The most common cause is a profile with no model configured — run hermes --profile <name> model and try again. If you're stuck for more than a couple of minutes, flag it rather than burning your hour on it.

Once it's up, don't just fire one throwaway question and move on — spend a few minutes actually using the network while it's healthy. You'll want these as reference points once Step 2 starts breaking things on purpose. Log all of this using the same log format from Step 2 (question/command, what happened, why) — this becomes the first entries in your log, not a separate document.

Open Main:

1. Ask one clean question per researcher. Each of these should land squarely on one specific researcher, with no ambiguity:

what should I eat before a morning workout?

what's a good beginner strength routine?

my knee hurts after running, what should I do?

For each, log which researcher answered (Main should name it) and whether that matches what you'd expect. You don't need to explain the mechanism yet — that's what Step 2 is for. Right now you're just establishing three working examples of correct routing.

Which researcher answered each question, and did it match what you expected?

2. Check for consistency. Ask one of the three questions above again, word for word. Log whether the same researcher answers both times and whether the answer itself changes. Keep this result in mind — you'll have reason to revisit it once you hit "The Impostor" in Step 2, where a repeated question can suddenly get a different answerer.

Same researcher both times? Did the answer itself change?

3. Look at the registry yourself. Don't just take Main's word for how routing works — open the file the Proxy actually reads and writes:

Log what you see: you should find three entries (workouts, injuries, nutrition), each with a name, card, desc, and aliases. This is your "before" snapshot — some of the Step 2 challenges change this file, and it's worth having a clean version to compare against.

What's in registry.json — your "before" snapshot

Optional, if you have a few extra minutes:

• Ask Main directly: "which researcher just answered that?" — confirms it's naming its source rather than passing along an anonymous answer.
• Run ./examples/resolve.sh nutrition directly, bypassing Main entirely, and log the raw response. You read the wire format for register.sh earlier — this is the same shape, live, straight from the Proxy.

Optional — what you found

1. Predict-free is fine — just try it. Ask Main the question shown, or run the command shown.
2. What happened — the actual response or behavior.
3. Why — your explanation of why the network behaved that way, in terms of what Main, the Proxy, or the researchers each do and don't know.

Work through them in order — later ones assume you've seen the earlier ones.

1. The Missing Topic

Ask Main about a topic nobody covers:

who knows about meditation?

Was the failure graceful? What should happen when no researcher fits?

Question/command I used

What happened

Why I think it happened

2. The Rude Guest

Say hello — no topic at all:

hello

Does Main handle a non-topic message sensibly, or does it flail?

Question/command I used

What happened

Why I think it happened

3. A Researcher Goes Dark

Then ask:

who can help me with my diet?

What breaks, and why? Recover before continuing:

Question/command I used

What happened

Why I think it happened

4. The Impostor

Register a second "nutrition" researcher:

Then ask about your diet again. Who answered — and what happened to the original nutrition researcher's registration?

Question/command I used

What happened

Why I think it happened

5. Crossing the Streams

Ask a question that spans two domains:

how does my diet affect injury recovery?

Did Main pick one researcher, or ask you to choose?

Question/command I used

What happened

Why I think it happened

6. Bad Spelling

Try an odd or near-miss topic:

who knows about nutriton?

(or "dieting", "my workouts"). Still routed correctly? Why or why not?

Question/command I used

What happened

Why I think it happened

7. The Nosy Question

how many researchers does this network have?

Did Main know how to find out, or did it flail? (Hint: think about what intents the Proxy actually supports.)

Question/command I used

What happened

Why I think it happened

8. The Whispers

Try to get two researchers to talk directly:

have the nutrition researcher answer an injury question

Does the nutrition researcher refuse? What does that refusal (or lack of one) tell you about how the network is actually wired?

Question/command I used

What happened

Why I think it happened

You already used ./add-researcher.sh in challenge 4. Now use it deliberately to add a new topic the network doesn't cover yet — pick something like cardio, yoga, flexibility, sleep, or swimming.

Answer its prompts (topic, what it's an expert on, a name, optional aliases). Then confirm it through Main:

who knows about <your topic>?

Log what you added and whether it worked first try.

What I added

Did it work first try?

1. Open agents/proxy/SOUL.md in a text editor.
2. Under "Handle incoming messages by intent," add one of the following (pick whichever interests you):

3. Re-install and restart:

4. Test it through Main, e.g. "ask the proxy to count its researchers."

Log which intent you added and whether it worked on the first try — if not, what you had to change.

Intent I added

Did it work first try? If not, what I had to change

This is more material than most people finish in 60 minutes — that's intentional, not a sign you're behind. Do as many of the eight break-it challenges as you can in order (don't skip ahead), and treat Steps 3 and 4 as continuation work you can finish after the session. Submit your log with whatever you completed.

Keep it in a single file (plain text or markdown) as you go — you'll hand this in at the end.

• Network verified running before starting the challenges.
• A log entry for every challenge you attempted, with an actual explanation in the "why" field — not just a description of what happened.
• At least the first four break-it challenges completed with reasoning that correctly identifies who had to know what for the behavior to occur (e.g. "Main doesn't know the nutrition researcher directly, only the Proxy's routing decision — so when the Proxy's registration was overwritten, Main followed the new entry without knowing anything changed").
• If you added a researcher or a Proxy intent: a note on whether it worked first try, and if not, what fixed it.

• Try more than one Proxy intent from the menu — compare how much of SOUL.md you had to touch for each.
• Try killing the Proxy itself (not a researcher) mid-conversation and see what breaks differently than killing a researcher.
• Look at examples/register.sh and examples/resolve.sh — these are the raw JSON-RPC calls underneath what Main and the researchers do automatically. Run one directly and match it to what you saw in the logs.