Herramientas privadas

Qué ve una herramienta

Placeholder	Valor
$auth.subject	El sub del token
$auth.token	El JWT crudo, para reenviarlo a tu API
$auth.claims.<name>	Cualquier claim propio

# tools/my_bookings.yml
description: The visitor's upcoming bookings.
when_to_use: When they ask about their own bookings.
access: private
request:
  method: GET
  base_url: $env.API_URL
  path: /api/bookings
  headers:
    Authorization: Bearer $auth.token
respond:
  data:
    bookings: bookings

Tu endpoint verifica el mismo JWT con la misma clave pública, y acota la consulta a su sub.

Reglas

Nunca tomes el id del usuario como parámetro. El modelo llena los parámetros, y se le puede convencer de llenar ese con el id de otra persona. Una herramienta privada que declare user_id, customer_id, account_id, member_id, patient_id o subject falla el despliegue:

tool my_bookings: a private tool cannot take "user_id" as a parameter — the model
fills parameters and can be talked into filling that one with someone else's id.
Use $auth.subject, which comes from the verified token

Deriva el usuario desde el token. Un endpoint que acepta un id tiene que acordarse de acotarlo cada vez, para siempre; uno que lee el token no se puede olvidar.

Otros errores que puedes encontrar:

Error	Solución
access: private needs an auth: block	Agrega auth: con public_key:
auth.public_key ... is a PRIVATE key	Apunta a identity.pub, no a identity.pem
auth.algorithm must be one of RS256...	Firma con RS256/ES256, no HS256 — un secreto compartido no puede vivir en un manifiesto
auth.mint.url must be https://	Usa https:// o un placeholder $env.
access must be "public" or "private"	Los nombres de esquema ya no existen; usa private
auth/ holds JavaScript auth providers, which are gone	Borra auth/ y firma un JWT
JavaScript tools are gone	Borra tools/*.js y lib/*.js; describe la llamada en tools/<key>.yml

Un token rechazado — clave equivocada, expirado, aud equivocado — deja al visitante anónimo en vez de dar error, y el agente cae de vuelta a sus herramientas públicas. vatio chat muestra la razón.