Módulo 3: Contratos entre workflows
7. Contratos para MCP y herramientas de agente
Descripción
Al terminar esta lección vas a poder exponer un sub-workflow como una herramienta que un AI Agent o un cliente MCP externo puede usar, y escribir su contrato de forma que el modelo la use en el momento correcto y con los datos correctos. Vas a entender que para este tipo de llamador el contrato ya no se ve como campos en un nodo Execute Sub-workflow, sino como un nombre, una descripción en lenguaje natural y un esquema de entrada, y que un contrato claro es literalmente lo que hace que el agente elija bien tu herramienta en vez de otra. Y vas a ver que todo lo que construiste en el módulo —validar en la frontera, versionar con cuidado, declarar la forma de salida— sigue aplicando, solo que ahora quien llama es un modelo.
Esto importa porque el llamador de tus contratos está cambiando. Hasta esta lección, quien llamaba a check-credit era siempre otro workflow: order-triage con su nodo Execute Sub-workflow, llenando campos concretos. Pero cada vez más, el que consume un workflow es un AI Agent —el propio agente de order-triage— o, con las capacidades de MCP de n8n, un cliente externo como Claude Desktop, Cursor o ChatGPT que construye y dispara workflows dentro de tu instancia. Ese llamador no llena campos: lee una descripción y decide. Si la descripción es vaga, el modelo adivina —y adivinar en un sistema que consulta crédito o emite reembolsos sale caro—.
Conexión con el módulo: todo el módulo construyó el contrato entre dos workflows. Esta lección lo traslada a un llamador nuevo —un modelo— y muestra que el contrato es el mismo, expresado de otra forma. Se apoya directamente en la guía de chatbots y agentes del ecosistema, que enseña el contrato de una tool (Name, Description, parámetros con $fromAI()) y el límite de confianza (la revisión humana para acciones sensibles): lo que aquí ves es ese mismo concepto, aplicado a un sub-workflow completo expuesto como una sola herramienta, y amarrado con la validación (lección 5) y el versionado (lección 6) que ya practicaste. La lección 8 cierra el módulo construyendo el sub-workflow validado; esta lección le da la cara que el sub-workflow muestra cuando quien lo llama es un agente.
Un comensal que solo tiene el menú
Volvamos por última vez al restaurante, porque la analogía todavía tiene algo que enseñar. Hasta ahora, el comensal que pedía de tu menú era otro workflow: sabía exactamente qué platos existían porque el nodo Execute Sub-workflow se los mostraba como campos listos para llenar. Era un comensal que ya conocía la carta.
El comensal nuevo es distinto. Es alguien que llegó al restaurante por primera vez, no puede llamar al mesero para preguntar nada, y tiene que decidir qué pedir leyendo únicamente el menú. Si el menú dice "Plato del día", ese comensal no tiene idea de qué le van a traer, y va a pedir con miedo o va a pedir otra cosa. Si el menú dice "Arrachera a las brasas, término a elegir, con guarnición de nopales", el comensal sabe exactamente qué está pidiendo y cuándo pedirlo. Para este comensal, el texto del menú es todo lo que tiene. No hay conversación posible; solo hay lo que está escrito.
Un AI Agent frente a tus herramientas es exactamente ese comensal. No lee los nodos internos de check-credit, no puede preguntarte qué esperabas, no ve el Sticky Note del contrato. Lo único que tiene para decidir si usa tu herramienta, cuándo la usa y con qué datos la llama es texto: el nombre de la herramienta, su descripción, y la descripción de cada parámetro. Ese texto es el contrato completo, y como el comensal que solo tiene el menú, si el texto es vago, el modelo adivina. La guía de chatbots lo dice sin rodeos y vale la pena repetirlo aquí: el contrato de una tool es su texto, y adivinar en un sistema que toca datos reales sale caro.
La buena noticia es que ya sabes escribir contratos. Todo lo que aprendiste —nombres específicos en vez de vagos, esquema de entrada preciso, forma de salida clara— es exactamente lo que hace bueno el contrato de una herramienta. La diferencia es que ahora una pieza del contrato, la descripción, carga un peso nuevo: es lo que el modelo lee para decidir. En un contrato entre workflows, la descripción era documentación para el equipo; en un contrato para un agente, la descripción es funcional —el modelo la usa para actuar—.
Las dos formas en que un workflow se vuelve herramienta
n8n te da dos caminos para que un workflow sea consumible como herramienta, y conviene distinguirlos porque el llamador es distinto en cada uno. Los nombres exactos de los nodos pueden variar entre versiones —verifícalos en tu panel—, pero el concepto de cada camino es estable.
Camino 1 — Un sub-workflow como herramienta de un AI Agent, dentro de n8n. Cuando tienes un AI Agent en un workflow (como el que clasifica pedidos en order-triage), puedes conectarle un sub-workflow completo como una de sus herramientas, usando un nodo que expone ese sub-workflow al agente —en tu versión puede aparecer como "Call n8n Workflow Tool" o "Custom n8n Workflow Tool"; verifica la etiqueta—. El agente ve ese sub-workflow como una sola herramienta con un nombre y una descripción, sin saber que por dentro son varios nodos. Es la evolución natural del contrato de tool que enseña la guía de chatbots: allí una tool era un nodo (un Gmail, un HTTP Request); aquí una tool es un sub-workflow entero con su contrato. check-credit expuesto así se convierte en una herramienta que el agente de order-triage puede invocar cuando necesite decidir sobre crédito.
Camino 2 — Tu instancia como servidor MCP para clientes externos. MCP —Model Context Protocol— es un estándar que permite que herramientas de IA externas se conecten a servicios y usen sus capacidades. n8n puede actuar como servidor MCP mediante el nodo MCP Server Trigger: ese nodo convierte tu instancia en un punto de entrada al que clientes MCP externos —Claude Desktop, Cursor, ChatGPT— pueden conectarse para usar tus workflows como herramientas. Los workflows que quieres exponer se enganchan al MCP Server Trigger (con el mismo tipo de nodo de herramienta del camino 1), y el trigger publica una URL —hay una de prueba y una de producción— protegida por autenticación (Bearer o Header). Así, check-credit puede volverse una herramienta que un asistente de IA fuera de n8n invoca, dentro de los límites que tú definas.
Los dos caminos comparten lo esencial para esta lección: en ambos, el workflow se presenta como una herramienta con nombre + descripción + esquema de entrada, y en ambos el llamador es un modelo que decide leyendo ese texto. Lo que cambia es dónde vive el modelo —dentro de tu workflow (camino 1) o en una aplicación externa (camino 2)—. El contrato que escribes es el mismo.
El contrato de una herramienta: nombre, descripción, parámetros
Recojamos las tres piezas del contrato de una tool tal como las enseña la guía de chatbots, ahora aplicadas a un sub-workflow expuesto como herramienta. Es el mismo esqueleto de siempre —qué entra, con qué forma— pero con la descripción cargando el peso nuevo de ser leída por el modelo.
El nombre (Name). Cómo se llama la herramienta. El agente lo usa para referirse a ella y como primera pista de qué hace. Un nombre como check_credit dice de qué se trata; uno como subworkflow_1 no dice nada y obliga al modelo a apoyarse solo en la descripción. Los nombres específicos que practicaste en la lección 3 valen igual aquí: check_credit, no process.
La descripción (Description). El texto que le dice al modelo qué hace la herramienta y —tan importante como eso— cuándo NO usarla. Es la pieza que más forma el comportamiento del agente, porque decide en qué momento la herramienta entra o no en consideración. Una buena descripción de herramienta dice tres cosas: qué hace, cuándo usarla, y cuándo no. Para check-credit: "Consulta si un cliente tiene crédito suficiente para un pedido. Úsala antes de confirmar un pedido a crédito. No la uses para pedidos de contado ni para emitir reembolsos." Esa última frase —el "no la uses para…"— es lo que evita que el agente confunda esta herramienta con otra parecida, el problema de las descripciones que se superponen que la guía de chatbots trata en detalle.
Los parámetros (el esquema de entrada). Cada dato que la herramienta necesita. Cuando el sub-workflow está conectado a un Tools Agent, los parámetros se rellenan con la función $fromAI(key, description, type, defaultValue), donde key es el identificador del dato (de 1 a 64 caracteres), description le dice al modelo qué buscar para ese dato, type es string, number, boolean o json, y defaultValue es opcional. Fíjate que esto es tu esquema de entrada de la lección 3, con una capa más: cada campo no solo tiene nombre y tipo, sino una descripción para el modelo de dónde sacar su valor. $fromAI("customer_id", "El ID del cliente que hace el pedido, tomado del registro del pedido, nunca inventado", "string") le dice al modelo exactamente qué poner ahí y de dónde —el registro del pedido— y qué no hacer —inventarlo—.
La estructura completa del contrato de check-credit como herramienta:
HERRAMIENTA — check-credit
Name: check_credit
Description:
Consulta si un cliente tiene crédito suficiente para un pedido.
Úsala antes de confirmar un pedido a crédito, cuando necesites saber
si el monto del pedido cabe en el crédito disponible del cliente.
NO la uses para pedidos de contado, ni para emitir reembolsos
(para eso está issue_refund), ni para cambiar el límite de crédito.
Parámetros (vía $fromAI):
customer_id : string — "ID del cliente del registro del pedido, nunca inventado"
order_id : string — "ID del pedido que se esta evaluando"
amount : number — "Total del pedido a comparar contra el crédito. Debe venir
del pedido, no estimarse ni redondearse."
Ejemplo trabajado: la descripción decide qué herramienta usa el agente
Veamos por qué el texto del contrato es funcional y no decorativo. El agente de order-triage tiene conectadas dos herramientas expuestas como sub-workflows: check-credit (consulta crédito, solo lee) e issue-refund (emite un reembolso, mueve dinero). Un cliente escribe por el chat: "quiero hacer un pedido de 2000 pesos, ¿me alcanza mi crédito?".
Con contratos mal escritos. Digamos que las dos herramientas tienen descripciones pobres: check-credit dice "Maneja crédito de clientes" e issue-refund dice "Procesa operaciones de dinero del cliente". Las dos descripciones se superponen —las dos suenan a "algo con dinero del cliente"—, así que el modelo, al comparar la petición contra ambas, reparte su decisión entre las dos. Puede elegir check-credit, que es lo correcto; pero también puede malinterpretar "operaciones de dinero" y considerar issue-refund. En el peor caso, ante una petición que solo pedía consultar, el agente termina considerando una herramienta que mueve dinero.
Con contratos bien escritos. Ahora check-credit dice "Consulta si un cliente tiene crédito suficiente. Úsala para responder si a un cliente le alcanza el crédito. NO emite reembolsos ni mueve dinero." e issue-refund dice "Emite un reembolso sobre un pedido ya pagado. NO la uses para consultar crédito ni para pedidos nuevos." Las descripciones ahora son mutuamente excluyentes: cada una dice explícitamente qué hace y qué no, y nombra a la otra para deslindarse.
Qué esperar. Con los contratos bien escritos, ante la petición "¿me alcanza mi crédito?", el agente lee que check-credit es exactamente para eso y que issue-refund explícitamente no es para consultar; elige check-credit, la llama con el customer_id y el amount correctos, y responde con el resultado. La herramienta que mueve dinero ni siquiera entró en consideración, porque su propia descripción la descartó para esta petición. Con los contratos mal escritos, el mismo cliente y el mismo modelo pueden producir una elección equivocada —no porque el modelo sea peor, sino porque el texto del contrato no le dio con qué decidir bien—. La diferencia entre un agente confiable y uno impredecible, aquí, no vino del modelo: vino del contrato.
Lo que no cambia: la frontera sigue siendo la frontera
Es tentador pensar que exponer un workflow a un agente es un mundo aparte, con reglas nuevas. No lo es. Todo lo que construiste en el módulo sigue aplicando, y en algunos casos importa más, no menos. Vale la pena recorrerlo, porque es lo que evita el error de creer que "conectarlo a un agente" reemplaza a la ingeniería del contrato.
La validación en la frontera sigue siendo obligatoria (lección 5), y aquí más que nunca. Un workflow que llama a check-credit te manda campos que un desarrollador configuró; un modelo que llama a check-credit te manda campos que dedujo del contexto de una conversación. El modelo puede equivocarse: puede pasar un amount que malinterpretó, un customer_id que confundió, un número que inventó. Por eso la validación de la lección 5 —rechazar en la puerta lo que no cumple el contrato— no solo sigue vigente cuando el llamador es un agente, sino que es todavía más importante: es la red que atrapa los errores del modelo antes de que lleguen al efecto. La description de cada parámetro reduce esos errores (le dice al modelo qué poner), pero no los elimina; la validación en la frontera es la que de verdad los detiene.
El límite de confianza aplica a los efectos (guía de chatbots + Módulo 2). check-credit solo lee, así que dejar que el agente la llame libremente es seguro. Pero issue-refund mueve dinero, y ahí el contrato claro no basta. La guía de chatbots enseña el patrón de revisión humana: una acción irreversible o con impacto financiero se conecta detrás de un paso de aprobación humana, de modo que el efecto real no ocurra hasta que una persona lo apruebe —aunque el agente decida llamarlo—. Y la idempotencia del Módulo 2 garantiza que, aun aprobado, el efecto no se aplique dos veces si la llamada se repite. Un sub-workflow que mueve dinero, expuesto como herramienta de un agente, necesita las tres capas: contrato claro (para que el agente lo use bien), validación en la frontera (para atrapar los datos que el modelo dedujo mal), y límite de confianza más idempotencia (para que el efecto no ocurra mal ni dos veces). El contrato le dice al agente qué hacer; las otras capas garantizan qué pasa aunque el agente se equivoque.
El versionado sigue aplicando (lección 6). Cambiar la descripción o el esquema de una herramienta cambia cómo el agente la usa. Renombrar un parámetro, cambiar su tipo o reescribir la descripción de manera que el modelo la interprete distinto es un cambio que puede alterar el comportamiento del agente —el equivalente, en este mundo, de romper a un llamador—. Los mismos principios de compatible-vs-rompiente aplican: agregar un parámetro opcional con default es seguro; cambiar el tipo de uno existente o reescribir la descripción de forma que el agente deje de elegir la herramienta cuando debía, no lo es. Un cambio de contrato es un cambio de contrato, tenga del otro lado un workflow o un modelo.
Exponer con límites: qué pones detrás de una URL MCP
El camino 2 —tu instancia como servidor MCP— agrega una consideración que el camino 1 no tiene, y conviene tratarla con cuidado: cuando expones workflows por MCP, del otro lado hay un cliente externo a tu instancia. En el camino 1, el agente vive dentro de tu propio workflow, bajo tu control. En el camino 2, quien llama puede ser Claude Desktop en la máquina de otra persona, o un asistente que tú no configuraste. Eso cambia la pregunta de seguridad: ya no es solo "¿el agente elige bien?", sino "¿qué le estoy dando permiso de hacer a algo que vive fuera de mi instancia?".
De ahí salen tres límites que conviene fijar al exponer por MCP, y ninguno reemplaza al anterior:
Autenticación en la puerta del servidor. El MCP Server Trigger publica una URL protegida por autenticación —Bearer o Header—. Ese es el primer límite: solo quien tiene la credencial puede conectarse. Tratar esa credencial como un secreto de verdad —no pegarla en un chat, no dejarla en un repositorio— es el piso, porque quien la tenga puede invocar todo lo que expusiste. Los detalles de cómo gestionar secretos y URLs en producción son de la guía de operaciones; aquí el punto es que la URL MCP no es pública ni inofensiva: es una entrada a tu instancia.
Elegir con cuidado qué workflows enganchas al servidor. No todo workflow debería ser una herramienta MCP. Un buen candidato es una lectura con contrato claro —check-credit, get-order-status—: útil, acotada, sin efecto irreversible. Un mal candidato, o al menos uno que exige el máximo cuidado, es un workflow que mueve dinero o borra datos. La regla de la lección 5 y de la tabla de la guía de chatbots no desaparece porque el llamador sea externo; se vuelve más estricta. Si expones issue-refund por MCP, tiene que llevar su validación en la frontera, su límite de confianza (revisión humana) y su idempotencia —las tres—, porque ahora el que lo dispara ni siquiera está dentro de tu casa.
El contrato de cada herramienta es tu superficie de control. Lo que un cliente MCP externo puede hacer con tu instancia está definido, exactamente, por los contratos de las herramientas que expusiste: sus nombres, sus descripciones, sus esquemas de entrada y —sobre todo— sus límites de efecto. Un contrato flojo expuesto por MCP no es solo un riesgo de que el agente elija mal; es una puerta más ancha de lo que querías hacia tu instancia. Por eso todo lo del módulo converge aquí: un contrato bien diseñado, validado y con límites de efecto claros no es solo buena ingeniería —cuando lo expones por MCP, es tu control de seguridad—.
La conclusión práctica: exponer por MCP es potente y conviene hacerlo con la misma disciplina de contrato de todo el módulo, subida un escalón. Empieza por exponer lecturas con contrato claro; trata cualquier efecto con las tres capas de protección; y recuerda que cada herramienta que enganchas al servidor es una capacidad que le das a algo que vive fuera de tu instancia. La operación completa de un servidor MCP en producción —monitoreo, rotación de credenciales, escalado— es tema de la guía de operaciones; el diseño correcto de sus contratos es tema de este módulo.
Errores comunes
Creer que conectar el workflow a un agente reemplaza la validación (conceptual). Qué pasa: alguien expone check-credit como herramienta con una descripción cuidada, y como el agente "entiende" qué mandar, quita o no construye la validación de la frontera; en producción, el modelo deduce mal un amount y el sub-workflow lo procesa como si fuera correcto. Por qué pasa: una buena descripción de parámetro reduce tanto los errores del modelo que da la impresión de que la validación sobra. Cómo detectarlo: pregúntate "si el modelo pasa un dato equivocado, ¿algo lo rechaza?"; si la única defensa es la descripción del parámetro, no hay defensa real. Cómo corregirlo: la descripción para el modelo y la validación en la frontera son capas distintas y complementarias —una reduce los errores, la otra los detiene—. Un workflow expuesto a un agente necesita las dos, igual que uno llamado por otro workflow, y con más razón porque el modelo deduce sus entradas en vez de recibirlas configuradas.
Descripciones que se superponen entre dos herramientas (práctico). Qué pasa: check-credit e issue-refund tienen descripciones parecidas —las dos hablan de "dinero del cliente"— y el agente empieza a llamar la que no corresponde, o alterna entre las dos en peticiones parecidas. Por qué pasa: el modelo elige qué herramienta usar comparando la petición contra el texto de cada descripción; si dos descripciones se superponen, la probabilidad de elegir se reparte en vez de resolverse. Cómo detectarlo: revisa los logs del agente buscando casos donde la herramienta invocada no corresponde a lo que pidió el usuario. Cómo corregirlo: haz las descripciones mutuamente excluyentes de forma explícita —cada una dice qué hace, qué no, y nombra a la otra para deslindarse—, en vez de dejar que la diferencia quede implícita en el nombre. Es el mismo consejo de la guía de chatbots, aplicado a sub-workflows expuestos como herramientas.
Exponer un sub-workflow que mueve dinero sin límite de confianza (conceptual). Qué pasa: alguien expone issue-refund como herramienta del agente con un contrato claro, y lo deja conectado directo al agente sin ninguna barrera de aprobación; el agente, ante una conversación insistente o una formulación inusual, termina disparando un reembolso que no debía. Por qué pasa: el contrato claro y la validación hacen que todo funcione bien en las pruebas normales, y da la sensación de que el sistema ya es seguro. Cómo detectarlo: para cada herramienta expuesta al agente, pregúntate "¿qué pasa, en el peor caso, si el agente la llama cuando no debía?"; si la respuesta involucra dinero, datos borrados o un compromiso con un cliente, falta el límite de confianza. Cómo corregirlo: toda herramienta con efecto irreversible o financiero va detrás del patrón de revisión humana de la guía de chatbots, no solo detrás de una buena descripción. La descripción le dice al agente qué hacer; la revisión humana garantiza qué pasa aunque el agente se equivoque. Y la idempotencia del Módulo 2 asegura que, aun aprobado, el efecto no se duplique.
Ejercicios
Ejercicio 1 — Reescribe el contrato de una herramienta. Un sub-workflow expuesto al agente tiene este contrato: Name apply, Description "Aplica cosas al pedido", y un parámetro {{ $fromAI("v") }}. El sub-workflow en realidad aplica un descuento a un pedido, y solo debería usarse para descuentos ya autorizados, nunca para cambiar el precio base ni la cantidad. Reescribe Name, Description y el parámetro siguiendo el patrón de la lección.
Ver solución
Name: apply_authorized_discount
Description:
Aplica un descuento ya autorizado a un pedido existente.
Úsala solo cuando exista una autorización de descuento confirmada
para ese pedido. NO la uses para cambiar el precio base de un
producto, la cantidad de un pedido, ni para autorizar el descuento
(la autorización es un paso previo, no lo hace esta herramienta).
Parámetro:
order_id : {{ $fromAI("order_id", "ID del pedido al que se aplica el descuento,
tomado del registro del pedido", "string") }}
discount_pct : {{ $fromAI("discount_pct", "Porcentaje de descuento autorizado
para este pedido. Debe venir de la autorización, nunca inventarse.
Entre 0 y 100.", "number") }}
Por qué funciona: el Name pasó de apply (no dice nada) a apply_authorized_discount (dice exactamente qué hace). La Description dice qué hace, cuándo usarla (descuento ya autorizado) y —lo más importante— qué NO hace (precio base, cantidad, autorizar). Y el parámetro v, que no daba ninguna pista al modelo, se volvió dos parámetros con nombre y descripción que anclan cada valor a su fuente ("de la autorización, nunca inventarse"). Un contrato así deja poco margen para que el agente lo use mal o pase datos inventados.
Ejercicio 2 — ¿Directo al agente o detrás de revisión humana? Para cada uno de estos sub-workflows expuestos como herramientas del agente de order-triage, decide si puede conectarse directo al agente o si necesita ir detrás de un paso de revisión humana, y justifica con el criterio de reversibilidad e impacto:
(a) check-credit — consulta crédito, solo lee.
(b) issue-refund — emite un reembolso, mueve dinero.
(c) get-order-status — devuelve el estado de un pedido, solo lee.
(d) cancel-order — cancela un pedido en la transportadora, irreversible una vez procesado.
Ver solución
(a) check-credit — directo al agente. Solo lee; llamarla de más no cambia nada en el mundo. No hay efecto que proteger.
(b) issue-refund — detrás de revisión humana. Mueve dinero y es difícil de deshacer. Aunque el agente la llame por error, el reembolso real no debe ocurrir hasta que una persona lo apruebe. Además, su llamada debe ser idempotente (Módulo 2).
(c) get-order-status — directo al agente. Es una lectura; no produce ningún efecto. Segura de llamar libremente.
(d) cancel-order — detrás de revisión humana. Es irreversible una vez que la cancelación entra en proceso con la transportadora. El costo de una cancelación equivocada es alto, así que necesita aprobación humana antes de ejecutarse.
Por qué funciona: el criterio no es qué tan compleja es la herramienta, sino cuánto cuesta deshacer el error si el agente se equivoca. Las lecturas (a, c) no tienen costo de error porque no cambian nada; los efectos irreversibles o financieros (b, d) tienen un costo alto y por eso van detrás del límite de confianza. Es exactamente la tabla de la guía de chatbots, aplicada a sub-workflows expuestos como herramientas.
Ejercicio 3 — Compatible o rompiente, versión herramienta. Para check-credit expuesto como herramienta del agente, decide si cada cambio es compatible o rompiente respecto de cómo el agente la usa, aplicando la misma prueba de la lección 6:
(a) Agregar un parámetro opcional include_history con default false.
(b) Reescribir la Description para que ahora diga que la herramienta también sirve para emitir reembolsos.
(c) Cambiar el tipo del parámetro amount de number a string.
Ver solución
(a) Compatible. Un parámetro opcional con default; el agente que no lo manda obtiene el comportamiento de siempre. No cambia cuándo ni cómo el agente elige la herramienta.
(b) Rompiente (en el comportamiento del agente). Reescribir la Description para que abarque reembolsos hace que el agente empiece a considerar check-credit para peticiones de reembolso —justo la superposición que causa que elija la herramienta equivocada—. Cambió qué peticiones disparan la herramienta. Es una rotura del contrato, aunque no toque ningún campo: la descripción es parte del contrato de una tool.
(c) Rompiente. Cambiar el tipo de un parámetro es rompiente igual que en un contrato entre workflows: el agente y la validación esperaban un número, y ahora la forma cambió. Además, un amount como texto reintroduce el error silencioso del número disfrazado.
Por qué funciona: la prueba de la lección 6 —"¿el llamador que no se entera sigue funcionando igual?"— aplica idéntica, con el matiz de que aquí "el llamador" es un modelo y una de las piezas del contrato es texto en lenguaje natural. Cambiar esa descripción (b) es tan rompiente como cambiar un campo, porque la descripción es lo que el modelo usa para decidir. El versionado de contratos no es solo para campos; es para todo lo que el llamador —humano, workflow o modelo— usa para actuar.
Resumen y siguiente paso
En esta lección trasladaste el contrato a un llamador nuevo: un modelo. Viste el comensal que solo tiene el menú —un agente que no lee tus nodos, no puede preguntar, y decide leyendo únicamente el texto del contrato—, y entendiste que para ese llamador el nombre, la descripción y la descripción de cada parámetro son el contrato completo. Conociste los dos caminos para exponer un workflow como herramienta: un sub-workflow conectado a un AI Agent dentro de n8n (con el nodo "Call n8n Workflow Tool" / "Custom n8n Workflow Tool", según tu versión), y tu instancia como servidor MCP para clientes externos (Claude Desktop, Cursor, ChatGPT) vía el MCP Server Trigger con su URL autenticada. Armaste el contrato de una herramienta —Name específico, Description que dice qué hace y cuándo NO usarla, parámetros con $fromAI() que anclan cada valor a su fuente— y viste en el ejemplo trabajado que ese texto es funcional: la diferencia entre un agente que elige bien y uno que confunde check-credit con issue-refund vino del contrato, no del modelo. Y confirmaste que nada de lo que construiste en el módulo se vuelve opcional cuando el llamador es un agente: la validación en la frontera importa más (el modelo deduce sus entradas y puede equivocarse), el límite de confianza y la idempotencia protegen los efectos que mueven dinero, y el versionado aplica también a la descripción, porque cambiarla cambia cómo el agente usa la herramienta.
Antes de avanzar a la lección 8 deberías poder: escribir el contrato de un sub-workflow expuesto como herramienta, con una descripción que no se superponga con otra; decidir si una herramienta va directo al agente o detrás de revisión humana; y clasificar un cambio a una herramienta como compatible o rompiente.
Ya tienes todas las piezas del módulo: qué es un contrato, cómo se diseña, dónde vive la frontera, cómo se valida, cómo se versiona, y cómo se ve cuando lo consume un agente. La lección 8 las junta en un solo entregable: vas a construir check-credit de punta a punta —con su contrato documentado, su validación en la frontera que rechaza entradas inválidas, y una segunda versión compatible—, el sub-workflow validado con contrato que es la capacidad de salida de todo el módulo.
Recursos
- MCP Server Trigger — n8n Docs — el nodo que convierte tu instancia en un servidor MCP para que clientes externos usen tus workflows como herramientas, con su URL y autenticación.
- How tools work — n8n Docs — qué es una herramienta para un agente en n8n y cómo el modelo decide usarla a partir de su nombre y descripción.
- Use AI for parameters — n8n Docs — referencia completa de
$fromAI(): los cuatro argumentos (key,description,type,defaultValue) y sus tipos. - Human-in-the-loop for tools — n8n Docs — el patrón de revisión humana que protege los efectos irreversibles o financieros de una herramienta expuesta al agente.
- AI Agent node — n8n Docs — el nodo donde vive el conector de herramientas al que conectas un sub-workflow expuesto como tool.