Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

Agents that talk to agents: the A2A protocol

After this lesson: I can read an Agent Card and decide whether to send that agent a task.

70 min lesson13 commandsAI coding agent lab: use opencode to explain and fix code, and check its work

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

WordWhat it meansExample
A2Aan open protocol for one agent to hand a task to another
Agent Carda JSON file in which an agent describes itself
Skillone job a card says the agent can do
Taskone job sent to an agent, with a state
Artifactwhat a finished task hands back
JSON-RPCa 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

Command
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

Command
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

Command
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

Command
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

Command
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

Command
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

Command
docker exec -w /home/node/project agent node card.js

Shown 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

Command
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

Command
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

Command
docker exec -w /home/node/project agent node task.js

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

What the Run prints

LineWhat happened
Task task-7 is completedmessage/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 workingThe 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 -32601JSON-RPC's code for a method that does not exist
No key: HTTP 401The agent refused a caller with no token

The cells students fill in are left blank in this preview.

A2A and MCP do different jobs

MCPA2A
ConnectsOne agent to tools and dataOne agent to another agent
The other sideDoes what it is told, step by stepPlans its own work and may take a while
You seeEach tool call and its resultOnly the task, its states and artifacts
Used togetherThe remote agent may use MCP insideYour 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

Command
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

Command
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

Command
docker exec -w /home/node/project agent node trust.js

Shown 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.

About this lab and its source: AI coding agent lab: use opencode to explain and fix code, and check its work

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.