> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnexor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Probar Workflow Tool

> Ejecuta una herramienta personalizada una vez, tal como la llama el agente, y revisa la solicitud, la respuesta y lo que lee el agente.

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](/docs/es/api/reports/get-tool-health).

## 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](/docs/es/api/workflow-tools/list-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.

<Warning>
  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.
</Warning>

## Qué enviar

| Campo | Detalle |
| - | - |
| `args` | Los argumentos que pasaría el agente, validados contra los `parameters` de la herramienta. Opcional, por defecto `{}`. |
| `lead_metadata` | Metadata de ejemplo del lead, que completa los marcadores `{{lead.metadata.X}}` y `{X}` como lo haría la metadata de un lead real. Opcional, por defecto `{}`. |
| `confirm_write` | `true` para ejecutar una herramienta que cambia datos. Se ignora en herramientas GET. |

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

| Escribe | Para | Ejemplo |
| - | - | - |
| `{nombre}` (llaves simples) | Un argumento de la herramienta. Nexor pone el valor del argumento en la URL y no lo vuelve a enviar en la consulta ni en el cuerpo. Si la metadata del lead tiene una clave con el mismo nombre, se usa ese valor. | `/appointments/{appointment_id}` |
| `{{...}}` (llaves dobles) | Un valor que Nexor completa antes de la llamada: un secreto de la cuenta `{{env.KEY}}`, datos del lead como `{{lead.metadata.X}}` o contexto como `{{lead_id}}`. | `?token={{env.SCHEDULING_TOKEN}}` |

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`:

```json theme={null}
{
  "error": "invalid_url_placeholder",
  "message": "The URL uses {{appointment_id}} for a tool argument. Tool arguments use single braces: {appointment_id}. Double braces are only for context values such as {{env.KEY}}, {{lead.metadata.X}} and {{lead_id}}.",
  "fields": ["appointment_id"],
  "suggested_url": "https://api.example.com/v1/appointments/{appointment_id}"
}
```

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.

| Lo que ves | Lo que suele significar | Qué hacer |
| - | - | - |
| `called: false` | No volvió ninguna respuesta. Lo más común es que la solicitud nunca saliera de Nexor: los `args` no calzan con los parámetros de la herramienta, falta un secreto `{{env.KEY}}` o la URL final apunta a un host que no es público. También pasa cuando la solicitud agotó el tiempo de espera. | Lee `agent_sees`: nombra los argumentos inválidos, las claves que faltan, la dirección rechazada o el tiempo de espera agotado. |
| Elementos en `checks.unresolved_placeholders` | La URL final todavía tiene un marcador `{{...}}`. Por lo general es un argumento escrito entre llaves dobles o un dato del lead que una prueba no tiene. | Usa llaves simples para los argumentos. Envía el valor en `lead_metadata` cuando viene del lead. |
| `response.status` 401 o 403 | Tu sistema rechazó la credencial. | Revisa el secreto o el encabezado configurado en la herramienta. |
| `response.status` 3xx | Tu sistema respondió con una redirección. La prueba no sigue redirecciones, así que `passed` viene en `false`. | Apunta la herramienta a la URL final. |
| `response.status` 404 | La ruta está mal o un parámetro de ruta no se completó. | Compara `request.url` con la documentación de tu API. |
| `response.ok: true` pero con datos equivocados | El endpoint responde, pero no es el que necesita el agente. Por ejemplo, una lista de citas agendadas en vez de horarios libres. | Apunta la herramienta al endpoint que responde la pregunta del agente. |
| `agent_sees` más corto que `body_excerpt` | Nexor limpia la respuesta y, si la herramienta tiene `llm_response_fields`, deja solo esos campos. | Verifica que sigan ahí los campos que necesita el agente. |

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


## API Specification

The full API specification for this endpoint is available in the [documentation index](https://docs.getnexor.ai/llms.txt).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.