Your orchestrator needs an agent somebody else built
Your team of agents plans a college open day. It needs free rooms, and another department already runs an agent that knows the timetable.
Your code cannot import theirs, and you cannot see inside it. You need an agreed way to ask it what it can do and to hand it a job.
By the end of this lesson
Note
I can read an Agent Card and decide whether to send that agent a task.
Key words
| Word | What it means | Example |
|---|---|---|
| A2A | an open protocol for one agent to hand a task to another | |
| Agent Card | a JSON file in which an agent describes itself | |
| Skill | one job a card says the agent can do | |
| Task | one job sent to an agent, with a state | |
| Artifact | what a finished task hands back | |
| JSON-RPC | a way to call a method by sending JSON | "method": "message/send" |
The cells students fill in are left blank in this preview.
A2A is a shared language between agents
Google announced the Agent2Agent protocol in 2025 and gave it to the Linux Foundation. It is open, so any team can build to it.
It uses plain HTTP. A client agent sends a task as JSON-RPC 2.0, and the remote agent can stream updates back as server-sent events. Neither side sees the other's code, prompts or tools.
An Agent Card says what an agent offers
An A2A agent publishes a card at a fixed address on its server, /.well-known/agent-card.json. The card names the agent and its version. It gives the address for tasks and lists its skills, each with tags.
It also says how a caller must prove who it is. A client reads the card before it sends anything.
Write the fake timetable agent, part 1
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const http = require(\"http\");' 'const CARD = {' ' protocolVersion: \"0.3.0\",' ' name: \"Timetable agent\",' ' description: \"Answers questions about a college timetable.\",' ' url: \"http://localhost:4100/a2a\",' ' version: \"1.0.0\",' ' capabilities: { streaming: true },' ' defaultInputModes: [\"text/plain\"],' ' defaultOutputModes: [\"text/plain\"],' ' securitySchemes: { classKey: { type: \"http\", scheme: \"bearer\" } },' ' security: [{ classKey: [] }],' ' skills: [' ' { id: \"free-rooms\", name: \"Free rooms\", description: \"Lists the rooms free at a time.\", tags: [\"rooms\", \"timetable\"] },' ' { id: \"clashes\", name: \"Clashes\", description: \"Finds two classes in one room.\", tags: [\"timetable\"] },' ' ],' '};' > agent.js"Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Write the fake timetable agent, part 2
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const ANSWER = \"Free at 14:00 on Monday: B12 and C3.\";' 'function task(id, state, text) {' ' const t = { kind: \"task\", id: id, contextId: \"ctx-1\", status: { state: state } };' ' if (text) t.artifacts = [{ artifactId: \"a-1\", name: \"answer\", parts: [{ kind: \"text\", text: text }] }];' ' return t;' '}' 'function said(call) { return call.params.message.parts[0].text; }' 'function send(call) {' ' if (said(call).includes(\"clash\")) return task(\"task-9\", \"failed\", \"\");' ' return task(\"task-7\", \"completed\", ANSWER);' '}' >> agent.js"Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Write the fake timetable agent, part 3
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'function stream(call, res) {' ' res.setHeader(\"content-type\", \"text/event-stream\");' ' const events = [' ' { kind: \"status-update\", taskId: \"task-8\", status: { state: \"submitted\" }, final: false },' ' { kind: \"status-update\", taskId: \"task-8\", status: { state: \"working\" }, final: false },' ' { kind: \"artifact-update\", taskId: \"task-8\", artifact: { artifactId: \"a-1\", parts: [{ kind: \"text\", text: ANSWER }] } },' ' { kind: \"status-update\", taskId: \"task-8\", status: { state: \"completed\" }, final: true },' ' ];' ' events.forEach(function (e) {' ' res.write(\"data: \" + JSON.stringify({ jsonrpc: \"2.0\", id: call.id, result: e }) + \"\n\n\");' ' });' ' res.end();' '}' >> agent.js"Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Write the fake timetable agent, part 4
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'function rpc(res, body) {' ' const call = JSON.parse(body);' ' if (call.method === \"message/stream\") return stream(call, res);' ' res.setHeader(\"content-type\", \"application/json\");' ' const out = { jsonrpc: \"2.0\", id: call.id };' ' if (call.method === \"message/send\") out.result = send(call);' ' else out.error = { code: -32601, message: \"Method not found\" };' ' res.end(JSON.stringify(out));' '}' >> agent.js"Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Write the fake timetable agent, part 5
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'function start(port) {' ' const server = http.createServer(function (req, res) {' ' if (req.method === \"GET\" && req.url === \"/.well-known/agent-card.json\") {' ' res.setHeader(\"content-type\", \"application/json\");' ' return res.end(JSON.stringify(CARD));' ' }' ' if ((req.headers.authorization === \"Bearer class-key\") === false) {' ' res.statusCode = 401;' ' return res.end();' ' }' ' let body = \"\";' ' req.on(\"data\", function (c) { body += c; });' ' req.on(\"end\", function () { rpc(res, body); });' ' });' ' return new Promise(function (ok) { server.listen(port, function () { ok(server); }); });' '}' 'module.exports = { start };' >> agent.js"Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Write the card reader
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const { start } = require(\"./agent\");' 'async function main() {' ' const server = await start(4100);' ' const res = await fetch(\"http://localhost:4100/.well-known/agent-card.json\");' ' const card = await res.json();' ' console.log(\"Name: \" + card.name + \", version \" + card.version);' ' console.log(\"Send tasks to: \" + card.url);' ' console.log(\"Streams updates: \" + card.capabilities.streaming);' ' card.skills.forEach(function (s) {' ' console.log(\"Skill \" + s.id + \": \" + s.description + \" Tags: \" + s.tags.join(\", \"));' ' });' ' const schemes = Object.values(card.securitySchemes).map(function (s) { return s.scheme; });' ' console.log(\"Asks callers for: \" + schemes.join(\", \"));' ' server.close();' '}' 'main();' > card.js"Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Fetch and read the Agent Card
docker exec -w /home/node/project agent node card.jsShown here, not run. Press Start lab to type it into your own lab’s terminal.
A task moves through states
A client sends a message with message/send. The agent answers with a task: an id, a state and, once finished, artifacts.
A task starts as submitted, becomes working, and can stop at input-required to ask for more. It ends completed, failed, canceled or rejected. With message/stream, each change arrives as an event, and the last one is marked final.
Write the task sender, part 1
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const { start } = require(\"./agent\");' 'function call(method, text, key) {' ' const headers = { \"content-type\": \"application/json\" };' ' if (key) headers.authorization = \"Bearer \" + key;' ' const message = { role: \"user\", messageId: \"m-1\", parts: [{ kind: \"text\", text: text }] };' ' const body = { jsonrpc: \"2.0\", id: 1, method: method, params: { message: message } };' ' return fetch(\"http://localhost:4100/a2a\", { method: \"POST\", headers: headers, body: JSON.stringify(body) });' '}' 'function line(e) {' ' const what = e.status ? e.status.state : \"artifact \" + e.artifact.parts[0].text;' ' return \"Event \" + e.kind + \": \" + what + (e.final ? \" (final)\" : \"\");' '}' > task.js"Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Write the task sender, part 2
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'async function main() {' ' const server = await start(4100);' ' const sent = await (await call(\"message/send\", \"Which rooms are free at 14:00 on Monday?\", \"class-key\")).json();' ' console.log(\"Task \" + sent.result.id + \" is \" + sent.result.status.state);' ' console.log(\"Artifact: \" + sent.result.artifacts[0].parts[0].text);' ' const text = await (await call(\"message/stream\", \"The same, as a stream.\", \"class-key\")).text();' ' text.split(\"\n\n\").filter(Boolean).forEach(function (chunk) {' ' console.log(line(JSON.parse(chunk.slice(6)).result));' ' });' ' const odd = await (await call(\"tasks/sing\", \"Hello\", \"class-key\")).json();' ' console.log(\"Unknown method: error \" + odd.error.code);' ' console.log(\"No key: HTTP \" + (await call(\"message/send\", \"Hello\", \"\")).status);' ' server.close();' '}' 'main();' >> task.js"Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Send a task, then stream one
docker exec -w /home/node/project agent node task.jsShown here, not run. Press Start lab to type it into your own lab’s terminal.
What the Run prints
| Line | What happened |
|---|---|
| Task task-7 is completed | message/send waited for the end |
| Artifact: Free at 14:00 on Monday: B12 and C3. | The answer the task handed back |
| Event status-update: submitted, then working | The stream reports each state |
| Event artifact-update: artifact Free at 14:00 ... | The answer arrives inside the stream |
| Event status-update: completed (final) | Nothing more will come |
| Unknown method: error -32601 | JSON-RPC's code for a method that does not exist |
| No key: HTTP 401 | The agent refused a caller with no token |
The cells students fill in are left blank in this preview.
A2A and MCP do different jobs
| MCP | A2A | |
|---|---|---|
| Connects | One agent to tools and data | One agent to another agent |
| The other side | Does what it is told, step by step | Plans its own work and may take a while |
| You see | Each tool call and its result | Only the task, its states and artifacts |
| Used together | The remote agent may use MCP inside | Your agent delegates the whole job |
The cells students fill in are left blank in this preview.
A card is a claim, not a proof
Anybody can publish a card that claims any skill. So keep a list of hosts you trust, and never call one that is not on it.
Then test a claimed skill with a task whose answer you know. The card's security scheme says what to send. The remote agent must still check, on every task, whether this caller may ask.
Write the trust check, part 1
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const { start } = require(\"./agent\");' 'const ALLOWED = [\"localhost:4100\"];' 'const OTHER = { name: \"Helpful agent\", url: \"https://agents.example.net/a2a\", skills: [{ id: \"anything\" }] };' 'function hostOf(url) { return url.split(\"/\")[2]; }' 'async function test(card, text) {' ' const message = { role: \"user\", messageId: \"m-2\", parts: [{ kind: \"text\", text: text }] };' ' const body = { jsonrpc: \"2.0\", id: 2, method: \"message/send\", params: { message: message } };' ' const headers = { \"content-type\": \"application/json\", authorization: \"Bearer class-key\" };' ' const res = await fetch(card.url, { method: \"POST\", headers: headers, body: JSON.stringify(body) });' ' return (await res.json()).result.status.state;' '}' > trust.js"Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Write the trust check, part 2
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'async function main() {' ' const server = await start(4100);' ' const ours = await (await fetch(\"http://localhost:4100/.well-known/agent-card.json\")).json();' ' [ours, OTHER].forEach(function (c) {' ' const known = ALLOWED.includes(hostOf(c.url));' ' console.log(c.name + \" at \" + hostOf(c.url) + \": \" + (known ? \"on the allow-list\" : \"not on the allow-list, never called\"));' ' });' ' console.log(\"Card claims: \" + ours.skills.map(function (s) { return s.id; }).join(\", \"));' ' console.log(\"Test free-rooms: \" + await test(ours, \"Which rooms are free at 14:00 on Monday?\"));' ' console.log(\"Test clashes: \" + await test(ours, \"Find a clash in room B12.\"));' ' server.close();' '}' 'main();' >> trust.js"Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Test the skills a card claims
docker exec -w /home/node/project agent node trust.jsShown here, not run. Press Start lab to type it into your own lab’s terminal.
A common mistake
Warning
Many people treat an Agent Card as proof of what an agent can do. A card is the agent describing itself. Here it claims clashes, yet a clash task comes back failed. Trust a skill only after a known test passes, and only from a host you chose.