Tu orquestador necesita el agente de otro equipo
Tu equipo de agentes organiza la jornada de puertas abiertas del instituto. Necesita aulas libres, y otro departamento ya tiene un agente que conoce el horario.
Tu código no puede importar el suyo, y no ves lo que hay dentro. Te hace falta una forma acordada de preguntarle qué sabe hacer y de pasarle un trabajo.
Al final de esta lección
Nota
Puedo leer una Agent Card y decidir si le envío una tarea a ese agente.
Palabras clave
| Palabra | Qué significa | Ejemplo |
|---|---|---|
| A2A | un protocolo abierto para que un agente pase una tarea a otro | |
| Agent Card | un archivo JSON en el que un agente se describe | |
| Habilidad | un trabajo que la tarjeta dice que el agente sabe hacer | |
| Tarea | un trabajo enviado a un agente, con un estado | |
| Artefacto | lo que devuelve una tarea terminada | |
| JSON-RPC | una forma de llamar a un método enviando JSON | "method": "message/send" |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
A2A es un idioma común entre agentes
Google anunció el protocolo Agent2Agent en 2025 y después lo cedió a la Linux Foundation. Es abierto, así que cualquier equipo puede seguirlo.
Va sobre HTTP normal. Un agente cliente envía una tarea en JSON-RPC 2.0, y el agente remoto puede devolver actualizaciones como eventos enviados por el servidor. Ninguno de los dos ve el código, las instrucciones ni las herramientas del otro.
Una Agent Card dice qué ofrece un agente
Un agente A2A publica una tarjeta en una dirección fija de su servidor, /.well-known/agent-card.json. La tarjeta da su nombre y versión, la dirección para las tareas y sus habilidades, cada una con etiquetas.
También dice cómo debe demostrar quién es quien llama. El cliente lee la tarjeta antes de enviar nada.
Escribe el agente de horarios falso, parte 1
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const http = require(\"http\");' 'const CARD = {' ' protocolVersion: \"0.3.0\",' ' name: \"Agente de horarios\",' ' description: \"Responde preguntas sobre el horario de un instituto.\",' ' 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: \"aulas-libres\", name: \"Aulas libres\", description: \"Lista las aulas libres a una hora.\", tags: [\"aulas\", \"horario\"] },' ' { id: \"choques\", name: \"Choques\", description: \"Encuentra dos clases en la misma aula.\", tags: [\"horario\"] },' ' ],' '};' > agent.js"Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Escribe el agente de horarios falso, parte 2
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const ANSWER = \"Libres el lunes a las 14:00: B12 y 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: \"respuesta\", parts: [{ kind: \"text\", text: text }] }];' ' return t;' '}' 'function said(call) { return call.params.message.parts[0].text; }' 'function send(call) {' ' if (said(call).includes(\"choque\")) return task(\"task-9\", \"failed\", \"\");' ' return task(\"task-7\", \"completed\", ANSWER);' '}' >> agent.js"Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Escribe el agente de horarios falso, parte 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"Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Escribe el agente de horarios falso, parte 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"Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Escribe el agente de horarios falso, parte 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"Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Escribe el lector de tarjetas
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(\"Nombre: \" + card.name + \", versión \" + card.version);' ' console.log(\"Enviar tareas a: \" + card.url);' ' console.log(\"Emite actualizaciones: \" + card.capabilities.streaming);' ' card.skills.forEach(function (s) {' ' console.log(\"Habilidad \" + s.id + \": \" + s.description + \" Etiquetas: \" + s.tags.join(\", \"));' ' });' ' const schemes = Object.values(card.securitySchemes).map(function (s) { return s.scheme; });' ' console.log(\"Pide a quien llama: \" + schemes.join(\", \"));' ' server.close();' '}' 'main();' > card.js"Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Descarga y lee la Agent Card
docker exec -w /home/node/project agent node card.jsSe muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Una tarea pasa por estados
El cliente envía un mensaje con message/send. El agente responde con una tarea: un id, un estado y, cuando acaba, artefactos.
Una tarea empieza en submitted, pasa a working y puede pararse en input-required para pedir más datos. Termina en completed, failed, canceled o rejected. Con message/stream, cada cambio llega como un evento, y el último va marcado como final.
Escribe el emisor de tareas, parte 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 : \"artefacto \" + e.artifact.parts[0].text;' ' return \"Evento \" + e.kind + \": \" + what + (e.final ? \" (final)\" : \"\");' '}' > task.js"Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Escribe el emisor de tareas, parte 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\", \"¿Qué aulas están libres el lunes a las 14:00?\", \"class-key\")).json();' ' console.log(\"Tarea \" + sent.result.id + \": \" + sent.result.status.state);' ' console.log(\"Artefacto: \" + sent.result.artifacts[0].parts[0].text);' ' const text = await (await call(\"message/stream\", \"Lo mismo, en directo.\", \"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/cantar\", \"Hola\", \"class-key\")).json();' ' console.log(\"Método desconocido: error \" + odd.error.code);' ' console.log(\"Sin clave: HTTP \" + (await call(\"message/send\", \"Hola\", \"\")).status);' ' server.close();' '}' 'main();' >> task.js"Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Envía una tarea y sigue otra en directo
docker exec -w /home/node/project agent node task.jsSe muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Lo que imprime el Run
| Línea | Qué pasó |
|---|---|
| Tarea task-7: completed | message/send esperó hasta el final |
| Artefacto: Libres el lunes a las 14:00: B12 y C3. | La respuesta que devolvió la tarea |
| Evento status-update: submitted, luego working | El flujo informa de cada estado |
| Evento artifact-update: artefacto Libres el lunes… | La respuesta llega dentro del flujo |
| Evento status-update: completed (final) | No llegará nada más |
| Método desconocido: error -32601 | El código de JSON-RPC para un método que no existe |
| Sin clave: HTTP 401 | El agente rechazó una llamada sin token |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
A2A y MCP hacen trabajos distintos
| MCP | A2A | |
|---|---|---|
| Conecta | Un agente con herramientas y datos | Un agente con otro agente |
| El otro lado | Hace lo que se le pide, paso a paso | Planifica su propio trabajo y puede tardar |
| Tú ves | Cada llamada a una herramienta y su resultado | Solo la tarea, sus estados y artefactos |
| Juntos | El agente remoto puede usar MCP por dentro | Tu agente delega el trabajo entero |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Una tarjeta es una promesa, no una prueba
Cualquiera puede publicar una tarjeta que anuncie cualquier habilidad. Por eso conviene una lista de hosts de confianza, y no llamar nunca a uno que no esté en ella.
Después, prueba la habilidad anunciada con una tarea cuya respuesta conozcas. El esquema de seguridad de la tarjeta dice qué enviar. Aun así, el agente remoto debe comprobar en cada tarea si quien llama puede pedirla.
Escribe la comprobación de confianza, parte 1
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const { start } = require(\"./agent\");' 'const ALLOWED = [\"localhost:4100\"];' 'const OTHER = { name: \"Agente servicial\", url: \"https://agents.example.net/a2a\", skills: [{ id: \"todo\" }] };' '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"Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Escribe la comprobación de confianza, parte 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 + \" en \" + hostOf(c.url) + \": \" + (known ? \"en la lista permitida\" : \"fuera de la lista, nunca se llama\"));' ' });' ' console.log(\"La tarjeta anuncia: \" + ours.skills.map(function (s) { return s.id; }).join(\", \"));' ' console.log(\"Prueba aulas-libres: \" + await test(ours, \"¿Qué aulas están libres el lunes a las 14:00?\"));' ' console.log(\"Prueba choques: \" + await test(ours, \"Busca un choque en el aula B12.\"));' ' server.close();' '}' 'main();' >> trust.js"Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Prueba las habilidades que anuncia una tarjeta
docker exec -w /home/node/project agent node trust.jsSe muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.
Un error frecuente
Advertencia
Mucha gente toma una Agent Card como prueba de lo que sabe hacer un agente. Una tarjeta es el agente describiéndose a sí mismo. Aquí anuncia choques, y sin embargo una tarea sobre un choque vuelve como failed. Fíate de una habilidad solo cuando pase una prueba conocida, y solo desde un host que hayas elegido.