# Recetas

Lo que se arma encadenando piezas. Cada receta usa herramientas y endpoints que existen hoy, con los mismos nombres que la [referencia MCP](/docs/mcp) y la [API](/docs/api). Las llamadas al MCP van como las escribiría tu agente de código; los argumentos son los de la referencia.

## 1. Del editor a producción

Con el MCP conectado ([Quickstart](/docs/quickstart)), cuatro llamadas:

```text
crear_agente({ nombre: 'Cotizador', instruccion: 'Cotizá el pedido con la lista vigente…' })
cargar_caso({ agente_id, titulo: 'Cotizar 200 cajas', entrada: { cliente: 'ACME' }, esperado: [{ campo: 'total', operador: 'existe' }] })
ensayar_y_publicar({ agente_id })
camino_a_produccion({ agente_id })
```

`ensayar_y_publicar` corre la evaluación contra todos los casos habilitados y, cuando se mide el último, si pasaron todos sube la versión hasta producción. Si la organización pide cuatro ojos, queda el pedido de firma para otra persona. Si algún caso falla, no sube nada: `camino_a_produccion` trae en `publicacion` qué caso falló y por qué, y a quien lo pidió le llega un correo. Sin casos habilitados no corre: para subir sin evaluación está `promover_agente`.

## 2. Pedirle la credencial al cliente

La llave del ERP del cliente no tiene que pasar por un chat. Generás un link de un solo uso y se lo mandás a quien la tiene:

```text
crear_link_de_credencial({ credencial: 'crm_token', ambiente: 'prod', para: 'Juana, de sistemas de Acme' })
```

Devuelve `link` **una sola vez** (la base guarda su hash). Juana la pega en esa página, queda sellada —nadie la vuelve a ver— y te llega un correo con los últimos cuatro. El link vence (72 horas por defecto), sirve una vez, y no pisa una credencial ya cargada salvo `reemplaza: true`. Sólo sirve para una credencial que alguna conexión cita. Desde el portal: Conexiones → Credenciales → «Pedir por link».

Nunca le pases una credencial al MCP como argumento: para eso existe el link.

## 3. Una tarea desde tu backend

Con un token de API de alcance `escritura` (Accesos) en una variable de entorno:

```bash
curl -X POST https://yorobot.ai/api/v1/agentes/$AGENTE/tareas \
  -H "Authorization: Bearer $YOROBOT_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"entrada":{"cliente":"ACME"},"ambiente":"dev"}'
```

Contesta 201 con `id`, `estado` y `ambiente`. El resultado llega por webhook (`tarea.terminada`, con el veredicto de la verificación) o con `GET /api/v1/tickets/{id}`. Sin `ambiente` corre en `dev` a propósito: la primera prueba de una integración no le pega al sistema real.

Toda respuesta trae `X-Request-Id`: guardalo en tu log. Es lo que se busca después.

## 4. Recibir el aviso

En Accesos → Webhooks das de alta la URL y los eventos (`tarea.terminada`, `discrepancia.detectada`, `tarea.necesita_firma`…). El secreto se muestra una vez. Con «Mandar aviso de prueba» cerrás el ciclo sin esperar una tarea. Cómo comprobar la firma, con el código: [Webhooks](/docs/webhooks).

## 5. ¿Qué está fallando?

```text
hallazgos({ dias: 7 })
listar_pedidos({ request_id: 'req_…' })
```

`hallazgos` agrupa lo que se repite fallando —pedidos a la API o al MCP, herramientas que el sistema del cliente rechaza, casos que no pasan, discrepancias, webhooks que no entregan, llaves rechazadas— con cuántas veces pasó, la causa probable y dónde se arregla. `listar_pedidos` encuentra un pedido por su `X-Request-Id`. En el portal: Operación → Hallazgos, y Registros para ver la API, el MCP, los webhooks, las tareas y las herramientas en una sola lista.

## 6. La cuenta, en una función

Lo que el modelo no tiene que hacer a ojo —un impuesto, un descuento por volumen, una validación— va en una función: el cuerpo de JavaScript que recibe `entrada` y devuelve el resultado.

```text
crear_funcion({ nombre: 'calcular_iva', descripcion: 'Suma los ítems y devuelve neto, IVA y total, ya calculados.', parametros: [{ nombre: 'items', tipo: 'lista', requerido: true }], codigo: 'const neto = entrada.items.reduce((s, i) => s + i.cantidad * i.precio, 0); return { neto, iva: Math.round(neto * 0.21), total: Math.round(neto * 1.21) };' })
editar_agente({ agente_id, herramientas: ['calcular_iva', …] })
```

Corre en el worker, en un contenedor sin red ni credenciales, con 128 MB y 5 segundos: no llama a ningún sistema, así que es de lectura y no pide aprobación. El portal compila el código para decir el error de sintaxis al guardar y no lo corre nunca. `ver_funcion` devuelve el código para editarlo.

## 7. El freno por minuto

Cada respuesta de un token que autenticó trae `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset`. Un `429` trae `Retry-After` en segundos: esperá eso y reintentá, en vez de reintentar en el acto. Lo que frena cada plan: [Límites](/docs/limites).
## 8. Mil contratos al Cerebro

Una colección agrupa los documentos que se cargan por lote y se tratan como uno. Con `clausulas`, cada contrato se parte donde empieza cada cláusula numerada («7.2», «CLÁUSULA PRIMERA», «Artículo 5»), así que la cita lleva a la cláusula y no a la página.

```text
crear_coleccion({ nombre: 'Contratos de proveedores', plantilla: 'clausulas', descripcion: 'Contratos de provisión vigentes: precio, ajuste, renovación y vigencia.' })
cargar_documentos({ coleccion: 'Contratos de proveedores', documentos: [{ nombre_archivo: 'acme-2026.pdf', contenido_base64: '…' }, …] })
```

Después, `buscar_en_cerebro({ consulta: 'renovación automática', coleccion: 'Contratos de proveedores' })` busca en el texto de todos y devuelve cada pasaje con su cita; un agente que corre con esa colección recibe la misma búsqueda. Hasta 20 documentos por llamada y 4 MB por pedido; la respuesta dice qué pasó con cada archivo (`ingerida`, `duplicada` o `rechazada` con el motivo) y volver a mandar el mismo archivo no lo carga dos veces. Desde la terminal, la carpeta entera: `yorobot cerebro subir ./contratos --coleccion "Contratos de proveedores" --crear --plantilla clausulas`. Por la API: `POST /api/v1/cerebro/lote` con un formulario (`curl -F archivos=@acme-2026.pdf -F coleccion=…`).

## 9. Compararlos: una tabla con la cita de cada campo

Comparar mil contratos no es leerlos juntos: es una fila por contrato y una consulta sobre la tabla. `configurar_extraccion` instala el Extractor de la biblioteca y encola una tarea por documento; cada una lee SU documento y llena la fila, con la cita del fragmento de cada campo. Lo que el contrato no dice queda sin valor y en `no_pude`, con el porqué.

```text
configurar_extraccion({ coleccion: 'Contratos de proveedores', plantilla: 'contratos' })
consultar_registros({ entidad: 'contratos', filtros: [{ campo: 'vigencia_hasta', op: '<', valor: '2027-03-01' }, { campo: 'renovacion_automatica', op: '=', valor: false }] })
comparar_documentos({ a: '<documento>', b: '<otro documento>' })
```

La respuesta de `configurar_extraccion` dice cuántas tareas creó, en qué ambiente y el techo de plata (documentos × presupuesto por documento). Lo que se publique después en la colección se extrae solo; con otras preguntas —un `esquema` propio, cada campo con la pregunta que contesta— se re-extrae todo. `!=` no incluye lo que no tiene valor: «no se renueva» y «no lo dice» son distintos, y los segundos están en `vacio`. `comparar_documentos` alinea las cláusulas por número aunque uno escriba «SEGUNDA» y el otro «2», y cada diferencia trae la cita a los dos lados.
