Herramientas

Las herramientas le permiten al agente llamar a tus APIs. Una herramienta es una petición HTTP, descrita en YAML. El nombre del archivo es la clave de la herramienta: tools/check_stock.yml se convierte en check_stock.

Cualquier cosa que necesite ramificar, una segunda llamada o una respuesta derivada es código, y pertenece al backend que la herramienta ya llama — dale al agente un endpoint que haga el trabajo completo.

Agrega cada herramienta a agent.tools; crear su archivo no la habilita.

Herramientas HTTP declarativas

Define la URL de tu backend como un secreto del workspace:

vatio secrets set ACME_API https://api.acme.com

Crea tools/check_stock.yml. Este ejemplo espera que la API devuelva {"data": [{"name": "Picker", "stock": 3}]}:

description: Check product stock.
when_to_use: The visitor asks whether a product is available.
parameters:
  type: object
  properties:
    product: { type: string }
  required: [product]
access: public
request:
  method: GET
  base_url: "$env.ACME_API"
  path: /products
  requires: [params.product]
  query:
    name: "$params.product"
respond:
  data:
    products: "$.data"
  message:
    when_empty: No products matched that name.
    default: "Found {{count}} matching products."

Fusiona esto en tu bloque agent existente:

agent:
  instructions: Use check_stock to answer questions about product availability.
  tools: [check_stock]

La petición soporta GET, POST, PATCH y DELETE. Entrega method, base_url y path; la URL base debe incluir su esquema y host. headers y query son mapas; body es un mapa JSON usado para POST y PATCH.

Placeholders

Los valores en base_url, path, headers, query y body soportan:

Placeholder	Origen
$params.<name>	Argumentos de la herramienta
$env.<KEY>	Secretos del workspace
$auth.subject, $auth.token, $auth.claims.<key>	El principal autenticado de la herramienta
$contact.name, $contact.email, $contact.phone_number	Perfil del contacto

Un placeholder solo conserva el tipo de su valor. Un placeholder dentro de un string se interpola. || elige la primera alternativa no vacía, como "$params.name || $contact.name".

Valores requeridos

Los valores faltantes se omiten de la petición. Lista bajo request.requires, sin el prefijo $, cualquier valor que el endpoint necesite, para fallar antes de enviar una petición incompleta. Un teléfono, email o nombre de contacto faltante produce missing_contact_phone, missing_contact_email o missing_contact_name; otras rutas producen missing_requirement.

Mapeo de la respuesta

respond.data mapea claves de salida a rutas JSON: $ es el cuerpo entero, $.data es su campo data. respond.message puede ser un string literal o el mapeo when_empty / default que se muestra arriba. {{count}} es el largo del primer arreglo en los datos mapeados. Sin un arreglo, when_empty aplica cuando todos los valores mapeados están vacíos.

Omite respond.message para usar el campo message de la propia API. Un HTTP 2xx produce result: "ok"; un no-2xx produce result: "error", así que devuelve el status que describe lo que pasó en vez de codificar fallas dentro de un 200.

Resultados de herramienta

Toda herramienta devuelve un objeto con result (ok o error) y un message no vacío. Se permiten campos adicionales, como data y error_key.

{ "result": "ok", "message": "This product is out of stock.", "data": { "stock": 0 } }

{ "result": "error", "message": "Stock could not be checked.", "error_key": "backend_unavailable" }

Usa ok cuando la operación se completó, incluyendo un resultado vacío o una respuesta negativa. Usa error cuando no se pudo completar. Un resultado inválido se convierte en un error de plataforma. Los resultados de herramienta son visibles para el modelo; nunca devuelvas credenciales.

Valida con vatio tools check, despliega con vatio push y ejercita la herramienta a través de vatio chat. No hay un comando para invocar una herramienta directamente.

Herramientas incorporadas

Herramienta	Propósito
knowledge_lookup	Buscar en las bases listadas en knowledge
identify_contact	Guardar un nombre que el visitante entregó
request_contact_info	Pedirle a un visitante de WhatsApp que comparta su teléfono
handoff	Entregar la conversación a una persona — ver Humano en el loop

Habilita las herramientas incorporadas a través de agent.tools, igual que las tuyas. La única excepción es handoff, que no tiene interruptor propio: declarar agent.handoff es lo que la adjunta, así que un agente nunca puede poder escalar sin tener a dónde escalar. request_contact_info envía una solicitud para compartir; el número llega solo si el visitante lo comparte en un mensaje posterior. Termina el turno y reintenta la operación dependiente después de esa respuesta.

Una herramienta que lee los registros propios de un visitante con sesión necesita access: private y un bloque auth:.