Skip to main content
POST
Test a workflow tool
Este endpoint responde una pregunta concreta: ¿esta herramienta funciona tal como la va a llamar el agente? Ejecuta una vez una de las herramientas HTTP personalizadas de una tarea, por el mismo camino que usa el agente en una conversación real, y devuelve lo que se envió, lo que volvió y lo que leería el agente. Úsalo apenas configures o cambies una herramienta, antes de poner la tarea en live.

Qué hace la prueba

  • Arma la solicitud igual que el agente: secretos {{env.KEY}}, marcadores de contexto, parámetros de ruta {argumento}, el resto de los argumentos como parámetros de consulta (GET) o como cuerpo (otros métodos) y los encabezados guardados en la herramienta.
  • Funciona con herramientas inactivas, así que puedes probar una herramienta antes de activarla.
  • Llama de verdad a tu sistema externo.
  • A diferencia de una conversación, solo llega a hosts públicos, no sigue redirecciones y se ejecuta como máximo una vez. Una URL que apunta a una dirección de loopback, privada, link-local o de metadata de la nube se rechaza antes de enviar nada.
  • En Nexor no cambia nada: no toca ningún lead, etapa, campo ni conversación, y la ejecución no aparece en Salud de las herramientas.

Antes de empezar

  • Las llaves MCP necesitan workflows:write, porque la prueba llega de verdad a tu sistema. Las llaves REST de acceso completo no necesitan nada más.
  • Obtén el toolId en Listar Workflow Tools. Solo se pueden probar las herramientas personalizadas de la tarea.
  • Las herramientas de la plataforma Nexor devuelven 400 internal_tool_not_testable. Esas se prueban en el Playground.

Herramientas que cambian datos

Las herramientas GET se ejecutan directamente. Una herramienta con método POST, PUT, PATCH o DELETE cambia datos en tu sistema, así que la prueba solo corre con confirm_write: true. Sin ese campo la respuesta es 409 write_requires_confirmation y no se envía nada.
Envía confirm_write: true solo después de que la persona responsable del sistema externo lo apruebe, usa datos de prueba y define la limpieza antes de llamar. Anula la cita creada por una prueba de reserva. Para reagendar o anular, usa un registro descartable o una restauración que soporte el proveedor.

Qué enviar

Una prueba no tiene un lead real. Los marcadores que leen otros datos del lead, como {{lead.phone}}, quedan sin resolver y aparecen en checks.unresolved_placeholders. {{lead_id}} se envía vacío.

Marcadores en la URL de la herramienta

Un argumento de la herramienta entre llaves dobles, como /appointments/{{appointment_id}}, nunca recibe un valor: el texto literal llega a tu sistema. Guardar una herramienta así se rechaza con 400 invalid_url_placeholder, que nombra los argumentos en fields y propone la URL corregida en suggested_url:
Las herramientas guardadas antes de esta validación no cambian. Pruébalas: un argumento que haya quedado entre llaves dobles aparece en checks.unresolved_placeholders.

Cómo interpretar el resultado

success solo indica que la prueba se pudo ejecutar. El veredicto es passed, que viene en true cuando la solicitud se envió, tu sistema respondió con un 2xx y un cuerpo útil, y la URL final no tiene marcadores sin resolver.

Límites

  • Un intento por consulta, hasta el tiempo de espera de la herramienta. Una prueba que agota el tiempo de espera no se reintenta, así que una herramienta que cambia datos se ejecuta como máximo una vez.
  • body_excerpt y agent_sees se cortan en 2.000 caracteres.
  • Los valores que vienen de {{env.KEY}} aparecen en request.url como [Redacted]. Los encabezados no se devuelven. Los valores que envías en args o lead_metadata vuelven tal como los enviaste.

Autorizaciones

X-API-Key
string
header
requerido

API key for authentication. Keys are prefixed with nxr_live_.

Parámetros de ruta

id
string<uuid>
requerido

Task ID (workflow in the API) that owns the tool.

toolId
string<uuid>
requerido

Tool ID, as returned by List workflow tools.

Cuerpo

application/json
args
object

The arguments the AI agent would pass, checked against the tool's parameters. Arguments named in the URL as {argument} fill the path; the rest go as query parameters on GET or in the body on other methods. Default {}. Anything other than an object returns 400 Invalid input.

lead_metadata
object

Sample lead metadata used to fill {{lead.metadata.X}} and {X} placeholders, as a real lead's metadata would. Default {}. Anything other than an object returns 400 Invalid input.

confirm_write
boolean
predeterminado:false

Required as true for tools whose method is POST, PUT, PATCH, or DELETE, because the test really changes data in the external system. Send it only after the operator agreed, with test data, and undo the effect afterwards. The test runs at most once: a timeout is not retried. Ignored for GET tools.

Respuesta

The test ran. success only means the test could run; read passed for the verdict. passed is true when the request was sent, the external system answered with a 2xx and a usable body, and the final URL has no unresolved {{...}} placeholder.

success
boolean
requerido
tool_id
string<uuid>
requerido
name
string
requerido

Tool name as the agent calls it.

method
enum<string>
requerido
Opciones disponibles:
GET,
POST,
PUT,
PATCH,
DELETE
passed
boolean
requerido

true when called is true, response.ok is true, and checks.unresolved_placeholders is empty.

called
boolean
requerido

false when no answer came back. Usually the request never left Nexor, for example because args do not match the tool's parameters, a {{env.KEY}} secret is missing, or the final URL points to a host that is not public; it is also false when the single attempt timed out. agent_sees then explains why.

request
object | null
requerido

What Nexor sent. null when called is false. Headers are not returned.

response
object | null
requerido

What the external system answered. null when called is false.

agent_sees
string | null
requerido

What the AI model receives, as text, cut at 2,000 characters. It can differ from body_excerpt, because Nexor cleans the response and keeps only the fields in the tool's llm_response_fields when they are set.

checks
object
requerido
Última modificación el 2 de octubre de 2026