YoRobot.

Esta página en Markdown: /docs/mcp.md

Referencia MCP

Servidor: https://yorobot.ai/api/mcp (Streamable HTTP). 218 herramientas, generadas desde el código que las sirve.

Se entra con Authorization: Bearer <token>; el token se genera en el Inicio o en Accesos y actúa en nombre de una persona con su rol. Un token de lectura ve; uno de escritura además crea trabajo, o sea gasta. Ninguna herramienta aprueba trabajo: aprobar devuelve un enlace de un solo uso y la aprobación la firma la persona en el portal, con su sesión. La excepción es la segunda firma de una promoción a producción (aprobar_promocion), que da otra persona que la que la pidió.

El catálogo chico

tools/list no trae las 218: trae un núcleo de lo que se usa en casi toda sesión (quien_soy, inicio, listar_agentes, crear_agente, editar_agente, probar_agente, pedir_tarea, estado_de_tarea, listar_tareas, ver_actividad, aprobaciones_pendientes, listar_herramientas, proponer_memoria, cargar_documento; sin alcance de escritura, sólo las de lectura) y tres meta-herramientas:

  • buscar_herramientas — por intencion en castellano («conectar WhatsApp», «cuánto gasté») y/o por area. Devuelve las que ese token puede llamar, mejor puntuadas primero, con descripción, alcance y esquema completo; si recorta, lo dice en la respuesta y nombra el resto.
  • usar_herramienta_lectura — ejecuta una herramienta del catálogo que sólo lee, con { nombre, argumentos }. Rechaza las que escriben. Es la que conviene aprobar «siempre» en el editor: no abre nada que cambie algo.
  • usar_herramienta — ejecuta una herramienta del catálogo que escribe, con { nombre, argumentos }, por el mismo camino que la llamada directa: alias, alcance de la herramienta de destino, freno por minuto, idempotencia con clave_de_pedido (dentro de argumentos) y auditoría. No se ofrece a un token sin escritura.

Están separadas porque los editores piden permiso por nombre de herramienta: con una sola para todo, aprobarla «siempre» para leer abría también las que borran. buscar_herramientas dice en usar_con cuál corresponde a cada una.

Cualquier herramienta de esta página se sigue pudiendo llamar directo por su nombre con tools/call, esté o no en la lista: el CLI y los clientes que ya conocen los nombres no cambian nada. Las áreas de búsqueda son las secciones de esta página: empezar, agentes, evaluaciones, equipos, copilotos, trabajo, conexiones, canales, automatizaciones, webhooks, datos, consolas, conocimiento, consumo.

Errores

Una herramienta que falla vuelve con isError: true y un objeto { codigo, mensaje, que_hacer, link? }. El codigo es estable y cada uno lleva a un próximo paso distinto:

  • falta_argumento
  • argumento_invalido
  • no_existe
  • estado_invalido
  • sin_alcance
  • demasiados_pedidos
  • clave_reusada
  • en_curso
  • requiere_persona
  • herramienta_desconocida
  • no_valida
  • falla

Índice

  • Empezar (empezar) — instalar_ejemplo, quien_soy, revocar_mi_token, inicio, como_vamos, consultar_numeros, proximo_paso, explicar_yorobot, buscar_herramientas, usar_herramienta_lectura, usar_herramienta
  • Agentes (agentes) — crear_agente, hablar_con_el_constructor, editar_agente, promover_agente, listar_promociones, aprobar_promocion, rechazar_promocion, volver_a_version, metricas_por_version, politica_de_publicacion, configurar_publicacion, exportar_agente, importar_agente, listar_componentes, ver_componente, listar_trabajos, crear_agente_desde_trabajo, ensayar_agente, camino_a_produccion, listar_agentes, transferir_agente, eliminar_agente, traspasar_agentes, historial_de_traspasos, ranking_de_agentes, agentes, resumen_de_agente, tareas_del_agente, calidad_del_agente
  • Probar (evaluaciones) — ensayar_y_publicar, cargar_caso, listar_casos, habilitar_caso, deshabilitar_caso, probar_agente
  • Equipos y reparto (equipos) — fijar_autonomia_del_proyecto, declarar_equipo, listar_equipos, ver_equipo, exportar_equipo, importar_equipo, descomponer_tarea, mandar_mensaje, ver_comunicacion, arbol_de_tarea, armar_vigia_de_mercado, pedir_al_vigia
  • Copilotos por persona (copilotos) — mi_perfil, editar_mi_perfil, asignar_copiloto, programar_briefings, listar_objetivos, ver_objetivo, definir_objetivo, medir_objetivo, pausar_objetivo, configurar_despertadores, ver_diario_de_sueno, configurar_sueno, listar_aprendizajes, aceptar_aprendizaje, rechazar_aprendizaje
  • Tareas (trabajo) — pedir_tarea, preguntar_a_agente, listar_hilos, ver_hilo, escribir_en_hilo, generar_pdf, listar_recordatorios, pausar_recordatorio, borrar_recordatorio, ver_traza, ver_actividad, listar_tareas, estado_de_tarea, tareas_estancadas, repetir_tarea, contestar_pregunta, seguir_tarea, aprobaciones_pendientes, resolver_efecto_incierto, aprobar, rechazar, hallazgos, que_paso_en_la_tarea, traza_de_la_tarea, herramientas_de_la_tarea
  • Conexiones y credenciales (conexiones) — crear_funcion, ver_funcion, crear_herramienta, listar_servidores_mcp, conectar_servidor_mcp, conectar_base, conectar_aplicacion, listar_aplicaciones_conectadas, desconectar_aplicacion, probar_conexion, redescubrir_servidor_mcp, estado_descubrimiento_mcp, autorizar_servidor_mcp, estado_oauth_mcp, desconectar_servidor_mcp, listar_herramientas, habilitar_herramienta, elegir_modelo, prender_herramienta, apagar_herramienta, cargar_credencial, editar_herramienta, simular_herramienta, quitar_simulacion, pedir_conexion, crear_link_de_credencial, listar_pedidos_de_conexion, rechazar_pedido_de_conexion
  • Canales y avisos (canales) — listar_canales, abrir_canal, conectar_canal, conectar_whatsapp, conectar_instagram, estado_de_conexion, configurar_canal, probar_canal, prender_canal, apagar_canal, listar_conversaciones, ver_conversacion, cerrar_conversacion, listar_destinatarios, avisar_a, prender_destinatario, apagar_destinatario, borrar_destinatario, probar_destinatario
  • Automatizaciones (automatizaciones) — crear_rutina, editar_rutina, listar_cajas, agregar_disparador, prender_rutina, apagar_rutina, borrar_rutina, listar_workers, desplegar_workers, salud_de_la_instalacion, listar_rutinas, disparar_rutina
  • Webhooks (webhooks) — listar_webhooks, listar_entregas_de_webhook, ver_entrega_de_webhook, reenviar_entrega_de_webhook, disparar_evento_de_prueba
  • Datos (datos) — listar_entidades, definir_entidad, consultar_registros, ver_registro, guardar_registro, importar_registros
  • Consolas (consolas) — catalogo_de_consola, biblioteca_de_consolas, arrancar_consola, listar_consolas, ver_consola, proponer_consola, publicar_consola, descartar_borrador
  • Cerebro y memoria (conocimiento) — listar_memorias, proponer_memoria, medir_memoria, decidir_memoria, listar_skills, cargar_skill, asignar_skill, listar_fuentes, ver_documento, cargar_documento, listar_colecciones, crear_coleccion, cargar_documentos, configurar_extraccion, extraer_pendientes, comparar_documentos, publicar_documento, despublicar_documento, alcance_de_documento, medicion_del_cerebro, grafo_del_cerebro, listar_fuentes_vivas, conectar_fuente_viva, catalogo_de_fuentes_vivas, configurar_fuente_viva, sincronizar_fuente_viva, desconectar_fuente_viva, buscar_en_cerebro
  • Consumo y límites (consumo) — fijar_cuota_mensual, fijar_tope_diario, ver_cuotas, ver_plan, ver_membresia, fijar_tope_de_agente, listar_pedidos, fijar_cuota_por_ventana, consumo_por_esfuerzo, mi_cartera, instalar_en_clientes, promover_en_cliente, retencion, actividad_por_dia

Empezar

Quién sos, qué hay, cómo vamos y las cuentas de la organización, qué es YoRobot, la tienda de ejemplo y cómo encontrar el resto del catálogo. Área de búsqueda: empezar.

instalar_ejemplo

alcance: escritura · idempotente

El sandbox: instala la tienda de ejemplo de YoRobot —dos conexiones sin llave contra un sistema de pedidos de mentira que sirve YoRobot, un agente de plantilla que las usa (no ocupa lugar en el plan) y cuatro casos— con la versión en prueba, lista para probar_agente. Una conexión consulta pedidos; la otra le «avisa» al cliente y, como un aviso no se deshace, espera la aprobación de una persona (el aviso no le llega a nadie). Las organizaciones nuevas ya la traen; esto la instala en las de antes. No crea tareas ni resultados.

ArgumentoTipoQué es
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

quien_soy

alcance: lectura · sólo lee · idempotente

Confirma la conexión: la cuenta (cuenta.email) y la organización (organizacion.nombre) de este token —la que se eligió al autorizar, o donde se creó en Accesos; nunca otra de la persona—, con resumen listo para decírselo a la persona. Además, el rol de la persona en esa organización hoy, si publica a producción y aprueba (técnico y admin) o sólo arma y ensaya (desarrollador) y a qué agentes llega (null = todos). Y el token: cómo se llama, si es una conexión OAuth que se renueva sola (token.se_renueva_solo: entonces no hay nada que rotar) o uno de Accesos que vence (token.vence, token.dias_restantes, token.vence_hoy), y qué hacer cuando venza. Llamala primero: lo que el token puede hacer no es del token, es de la persona, y puede haber cambiado desde que se emitió.

Sin argumentos.

revocar_mi_token

alcance: lectura · destructiva · idempotente

Revoca ESTE token —el que autenticó esta llamada— en el acto: la próxima llamada con él da 401. No pide id ni acepta otro: para revocar el de otra persona está Accesos en el portal. Usala cuando el token quedó pegado en un transcript, un log o un mensaje. Cualquier alcance alcanza: apagarse uno mismo es siempre seguro.

ArgumentoTipoQué es
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

inicio

alcance: lectura · sólo lee · idempotente

Lo mismo que la pantalla de Inicio: casos cerrados y verificados este mes, discrepancias (el agente dijo una cosa y la verificación otra; no se facturan), tareas que esperan una aprobación, frenadas que nadie mueve, y el gasto contra el tope mensual con porcentaje. Más el desglose por agente. Y ahora, como el cockpit del Inicio: cuántos agentes trabajan y cada corrida en vivo con su tarea, desde cuándo y el silencio (sospechoso a los 5 min, critico a los 15); la madre que espera a sus hijas (espera_hijas). La primera para «¿cómo vamos?». Esfuerzo: consumo_por_esfuerzo; cola: aprobaciones_pendientes; frenadas: tareas_estancadas.

Sin argumentos.

como_vamos

alcance: lectura · sólo lee · idempotente

La organización entera en el mes en curso: cuántos agentes hay, casos cerrados y verificados, discrepancias, tareas que esperan aprobación, tareas frenadas, gasto contra el tope y el desglose por agente. Es la respuesta a «¿cómo vamos?»; para un agente en particular seguí con resumen_de_agente.

Sin argumentos.

consultar_numeros

alcance: lectura · sólo lee · idempotente

Cuenta o suma sobre una vista cerrada —tareas (tareas o frenadas), gasto (costo o ejecuciones) o aprobaciones (aprobadas o rechazadas)— por agente, columna, día o semana y en un período, sin escribir SQL. Es la respuesta a «¿cuántas tareas frenadas por agente este mes?» o «¿qué agente gastó más?»: el número lo calcula el servidor y llega con el total ya sumado, el nombre de cada grupo y lo que no entró. Frenada es la columna Frenada de Tareas (nada la mueve). El período se corta en la zona horaria de la organización (por defecto estemes; «todo» es sin corte). `agenteid` la acota a un agente, por su id o su nombre.

ArgumentoTipoQué es
vista (requerido)tareas · gasto · aprobacionesDe dónde se cuenta: tareas, gasto (las ejecuciones) o aprobaciones.
medidatareas · frenadas · costo · ejecuciones · aprobadas · rechazadasQué se cuenta. tareas: tareas o frenadas. gasto: costo o ejecuciones. aprobaciones: aprobadas o rechazadas. Sin ella, la primera de la vista.
poragente · columna · dia · semanaCómo se agrupa: agente, columna (sólo tareas), dia o semana. Sin él, el total.
periodohoy · ayer · esta_semana · semana_pasada · este_mes · mes_pasado · ultimos_7_dias · ultimos_30_dias · este_trimestre · este_anio · todoQué período. Por defecto este_mes.
agente_idstringSólo la de este agente: su id (de agentes) o su nombre.

proximo_paso

alcance: lectura · sólo lee · idempotente

El camino de la organización hacia «Implementador certificado», medido sobre lo que hizo de verdad: los siete ejercicios de la Academia y los módulos de la Escuela, cada uno con si está hecho o falta, dónde se hace y cuál es el PRÓXIMO PASO. Es la respuesta a «¿qué me falta para certificarme?», «¿cuál es mi próximo paso?» o «¿por dónde sigo?». No recomienda: lee los hechos.

Sin argumentos.

explicar_yorobot

alcance: lectura · sólo lee · idempotente

Qué es YoRobot y cómo se vende: qué hace, los precios y la prueba, la Escuela y la Academia. Es para preguntas sobre la plataforma misma —qué es, cuánto cuesta, cómo empieza un implementador—, no sobre esta organización; contestá con lo que dice y citalo.

Sin argumentos.

buscar_herramientas

alcance: lectura · sólo lee · idempotente

Esta lista trae sólo el núcleo. El resto del catálogo de YoRobot (canales como WhatsApp o Slack, conexiones, Datos, consolas, automatizaciones, evaluaciones, equipos, webhooks, consumo, producción…) se encuentra acá: describí lo que querés hacer en intencion («conectar WhatsApp», «cuánto gasté este mes») y/o elegí un area. Vuelven las que ESTE token puede llamar, mejor puntuadas primero, con descripción y esquema completo; ejecutalas con usar_herramienta o directo por su nombre.

ArgumentoTipoQué es
intencionstringQué querés hacer, en castellano y con tus palabras. Se busca por palabras en nombre, descripción y área.
areaempezar · agentes · evaluaciones · equipos · copilotos · trabajo · conexiones · canales · automatizaciones · webhooks · datos · consolas · conocimiento · consumoLimita a un área: empezar (Quién sos, qué hay, cómo vamos y las cuentas de la organización, qué es YoRobot, la tienda de ejemplo y cómo encontrar el resto del catálogo); agentes (Crear (también conversando con el Constructor), editar, versionar, llevar a producción y traspasar agentes); evaluaciones (Evaluaciones: ensayos, casos y la prueba con traza); equipos (Equipos de agentes, partir una tarea entre varios, pedirle algo a un par, ver el árbol y cuánta autonomía tiene el equipo técnico sobre cada proyecto); copilotos (El perfil de cada persona —canal, hora, intereses—, su copiloto, su North Star medido y el briefing diario con sus decisiones); trabajo (Pedir trabajo, seguirlo, leer su traza, las fallas que se repiten, preguntarle algo a un agente, tu conversación con cada agente, tus recordatorios y ver qué espera aprobación); conexiones (Herramientas, funciones propias, servidores MCP ajenos, aplicaciones conectadas (Che Tienda), credenciales, simulaciones y el modelo); canales (Por dónde entra la gente (chat, WhatsApp, Slack…) y a quién se le avisa); automatizaciones (Rutinas, disparadores, cajas y workers); webhooks (Avisos firmados hacia afuera: entregas, reenvío y el aviso de prueba); datos (Entidades y registros de la organización); consolas (Las pantallas declaradas del equipo del cliente); conocimiento (Conocimiento: documentos, fuentes vivas, memorias y skills); consumo (El plan y la membresía, gasto, topes (también el de cada agente), cuotas, el registro de pedidos, retención y la cartera partner). Sin intencion, trae el área entera.
limitenumberCuántas traer con esquema completo. Por defecto 5, máximo 10; las demás que coinciden vienen sólo por nombre.

usar_herramienta_lectura

alcance: lectura · sólo lee · idempotente

Ejecuta por su nombre una herramienta del catálogo que SÓLO LEE, aunque no esté en esta lista (la encontrás con buscar_herramientas, que en usar_con te dice cuál usar). Si la de destino escribe, la rechaza: esas van por usar_herramienta. Pasa por el mismo camino que llamarla directo: alcance, validación, freno por minuto y auditoría. No sirve para llamar a buscar_herramientas ni a las otras dos de este tipo.

ArgumentoTipoQué es
nombre (requerido)stringEl nombre exacto de la herramienta, como lo devuelve buscar_herramientas.
argumentosobjectLos argumentos de esa herramienta, con la forma de su inputSchema. Vacío si no lleva.

usar_herramienta

alcance: lectura · destructiva · toca sistemas ajenos

Ejecuta por su nombre una herramienta del catálogo que ESCRIBE (crea, cambia, borra, conecta, publica), aunque no esté en esta lista (la encontrás con buscar_herramientas). Para las que sólo leen usá usar_herramienta_lectura: así tu editor te pide permiso sólo cuando algo va a cambiar. Pasa por el mismo camino que llamarla directo: alcance, validación, freno por minuto, idempotencia y auditoría, y exige el alcance de la herramienta de destino. Mandá clave_de_pedido adentro de argumentos. No sirve para llamar a buscar_herramientas ni a las otras dos de este tipo.

ArgumentoTipoQué es
nombre (requerido)stringEl nombre exacto de la herramienta, como lo devuelve buscar_herramientas.
argumentosobjectLos argumentos de esa herramienta, con la forma de su inputSchema. Vacío si no lleva.

Agentes

Crear (también conversando con el Constructor), editar, versionar, llevar a producción y traspasar agentes. Área de búsqueda: agentes.

crear_agente

alcance: escritura

Crea un agente: un trabajador digital con oficio, instrucciones y herramientas. Queda activo pero sin credenciales: puede razonar y no toca nada real hasta que alguien las conecte. Con clave, volver a declararlo con la misma clave lo ACTUALIZA (versión nueva en dev) en vez de crear otro: es lo que hace que una terminal pueda repetir la llamada sin llenar la organización de duplicados.

ArgumentoTipoQué es
nombre (requerido)stringCómo se lo va a llamar en la pantalla. Corto y humano.
clavestringClave estable elegida por vos (p. ej. «triaje-guardia»), única en la organización. Si ya hay un agente con esa clave, se actualiza en vez de crear otro; la respuesta dice creado o actualizado. Opcional.
instruccion (requerido)stringEscrita EN SEGUNDA PERSONA, dirigida al agente: qué hace, en qué orden, cuándo frena y pide aprobación, y qué no debe hacer nunca.
conocimientostringLo que necesita saber del negocio. Vacío si no aplica.
como_se_verificastringQué consulta de sólo lectura, contra qué sistema, demuestra que el trabajo se hizo. Es lo que va a releer el verificador: obligatorio si pedís verificacion distinta de «ninguna», y tiene que NOMBRAR una herramienta de riesgo read de herramientas o una entidad de Datos (por clave o nombre); si no cita ninguna, se rechaza y el error dice cuáles puede citar. La respuesta trae criterio_de_verificacion.releible.
aceptar_sin_relecturabooleantrue para guardar un como_se_verifica que ninguna lectura de la caja puede releer, a sabiendas de que toda tarea va a terminar en «lo mira una persona». Por defecto false.
human_in_the_loopsiempre · excepciones · solo_irreversibleCuándo entra una persona: «siempre» (toda acción con efecto y todo cierre esperan aprobación), «excepciones» (lo irreversible, montos fuera de tope, fallos y discrepancias) o «soloirreversible» (default: el agente nace barato y se sube después con editaragente). Lo destructivo, el guardarriel y las herramientas en cuarentena piden persona con cualquier valor.
verificacioncompleta · relectura · muestreo · ningunaQué relee el verificador independiente después de cada tarea: «completa» (antes y después, 2 corridas), «relectura» (1 corrida), «muestreo» (relectura en un porcentaje de las tareas) o «ninguna» (default: la tarea cierra sin verificar y no cuenta como verificada). Cada nivel arriba de «ninguna» es una corrida más que se cobra; se prende con editar_agente cuando el proceso lo amerita.
verificacion_muestreointegerSólo con verificacion=muestreo: porcentaje de tareas que se releen (1–99). Default 20.
herramientaslistaNombres de conexiones ya existentes en la organización (listar_herramientas). Un nombre que no exista es un ERROR (el mensaje dice cuáles y qué hay), salvo ignorar_desconocidas: true.
ignorar_desconocidasbooleantrue para crearlo igual, sin las herramientas que no existan. La respuesta las lista en ignoradas_porque_no_existen. Por defecto false.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

hablar_con_el_constructor

alcance: escritura

La misma entrevista que el Constructor de la app, turno a turno: le contás qué tarea querés sacarte de encima y te pregunta lo que falta —qué sistemas toca, dónde se comprueba el trabajo, un ejemplo excelente y uno inaceptable, qué no puede hacer solo—. Cada respuesta trae plan_parcial: la ficha del agente como va, con lo entendido, lo que falta y, cuando hay plan, los sistemas en palabras, el escalón de autonomía, qué le va a preguntar a la persona antes de actuar (que_te_pregunta), el tope y los actos. El tope solo no dice qué espera aprobación: leé todo_con_efecto_espera_aprobacion y el_tope_decide_algo. El primer turno va sin sesion y la respuesta trae una: mandala en los siguientes. Cuando alcanza, arma el plan con la misma validación que la app y lo deja como BORRADOR: creado es false y confirmar_en es el link donde la persona lo revisa y lo confirma con su sesión. Ningún agente se crea desde acá: mostrale el link tal cual. Si ya tenés el agente escrito entero, crear_agente.

ArgumentoTipoQué es
mensaje (requerido)stringLo que le decís al Constructor, en lenguaje natural. Hasta 4000 caracteres.
sesionstringLa sesion que devolvió el turno anterior. Sin ella, arranca una charla nueva.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

editar_agente

alcance: escritura

Cambia lo que un agente ya existente sabe y hace: su instrucción, su conocimiento, cómo se verifica, Human in the Loop y verificación (o modo), y qué herramientas usa. Queda versionado, así que se puede ver qué cambió y cuándo. La versión nueva va a dev, y en el modo Libre también a producción (la respuesta trae deshacer); con desplegar_hasta («staging» o «prod») se promueve en la misma llamada, con los chequeos de promoveragente. La correa (`nivel`, `topesinfirmausd, presupuestoportarea_usd`) también se edita acá, con una asimetría: APRETAR (bajar nivel, tope o presupuesto) lo puede cualquier operador; AFLOJAR exige técnico o admin, igual que sacar una herramienta de cuarentena, y deja su propio evento en la bitácora.

ArgumentoTipoQué es
agente_id (requerido)stringEl id que devolvió crearagente o listaragentes.
nombrestringSólo si querés renombrarlo.
instruccionstringReemplaza la instrucción entera, en segunda persona. No se concatena a la anterior.
conocimientostringReemplaza el conocimiento entero.
como_se_verificastringReemplaza la verificación. Vaciarlo deja al agente sin poder medirse. Tiene que nombrar una herramienta read de la caja o una entidad de Datos; si con el cambio (de este campo, de herramientas o de verificacion) el criterio deja de poder releerse, se rechaza salvo aceptar_sin_relectura: true.
aceptar_sin_relecturabooleantrue para guardar igual un criterio que ninguna lectura de la caja puede releer. Por defecto false.
modolibre · con_controles · reguladoLos diales de un modo, de una vez: «libre» (hace y avisa, persona sólo en lo irreversible, sin verificación), «con_controles» (persona por excepción, relee el 20 %) o «regulado» (aprobación por acción, persona siempre, verificación completa). Lo que mandes además lo pisa. Rige ya; aflojar exige técnico o admin.
human_in_the_loopsiempre · excepciones · solo_irreversibleCuándo entra una persona: «siempre» (toda acción con efecto y todo cierre esperan aprobación), «excepciones» (lo irreversible, montos fuera de tope, fallos y discrepancias) o «soloirreversible» (default: el agente nace barato y se sube después con editaragente). Lo destructivo, el guardarriel y las herramientas en cuarentena piden persona con cualquier valor.
verificacioncompleta · relectura · muestreo · ningunaQué relee el verificador independiente después de cada tarea: «completa» (antes y después, 2 corridas), «relectura» (1 corrida), «muestreo» (relectura en un porcentaje de las tareas) o «ninguna» (default: la tarea cierra sin verificar y no cuenta como verificada). Cada nivel arriba de «ninguna» es una corrida más que se cobra; se prende con editar_agente cuando el proceso lo amerita.
verificacion_muestreointegerSólo con verificacion=muestreo: porcentaje de tareas que se releen (1–99). Default 20.
herramientaslistaReemplaza la lista entera, por nombre. Un nombre que no exista en la organización es un ERROR (el mensaje dice cuáles y qué hay), salvo ignorar_desconocidas: true.
ignorar_desconocidasbooleantrue para que las herramientas que no existan se salteen en vez de rechazar la llamada. La respuesta las lista en herramientas_ignoradas. Por defecto false: un nombre mal tipeado no deja al agente sin la herramienta en silencio.
activobooleanfalse lo manda a descanso: no toma tareas nuevas ni atiende sus rutinas, pero conserva su historia entera (un agente no se borra: sus corridas y versiones son el registro) y deja de contar para el límite de agentes del plan. true lo despierta.
nivelshadow · assisted · delegated · gated_autoNivel de autonomía, de menor a mayor: «shadow» (propone, no ejecuta), «assisted» (ejecuta con aprobación), «delegated» (ejecuta solo dentro del tope; lo irreversible sigue pidiendo firma), «gated_auto» (también cierra solo si el verificador aprueba; un sistema de cliente no pasa de delegated). Subirlo exige técnico o admin.
tope_sin_firma_usdnumbernullMonto en USD que el agente puede mover sin aprobación (sólo con nivel delegated o gated_auto). 0 es CERO: lo que no maneja montos sale solo y un peso pide firma. null lo saca: TODA acción con efecto vuelve a pedir aprobación (es apretar). Subir el número, o pasar de null a un número, es aflojar: exige técnico o admin. Sin mandar, no cambia.
presupuesto_por_tarea_usdnumberPresupuesto duro de modelo por tarea, en USD (mayor que cero). Subirlo exige técnico o admin.
reparte_trabajobooleantrue le deja repartir su tarea en tareas hijas a cargo de OTROS agentes, y pedirle algo puntual a un par. Por defecto false: un agente hace su tarea solo. Prenderlo es aflojar —le da la capacidad de crear trabajo que se paga sin que nadie lo pida tarea por tarea— así que exige técnico o admin; apagarlo lo puede cualquier operador.
reparto_profundidad_maxnumberCuántos niveles de reparto se permiten desde esta tarea (1 a 10, por defecto 3). Es lo que corta un bucle entre dos agentes que se delegan entre sí sin tener que detectar el ciclo: cada vuelta cuesta un nivel. Subirlo exige técnico o admin.
reparto_hijas_maxnumberCuántas tareas hijas puede crear de una vez (1 a 20, por defecto 8). Subirlo exige técnico o admin.
desplegar_hastastaging · prodAdemás de editar, promover la versión nueva hasta ese ambiente en la misma llamada (dev → staging → prod, cada escalón con sus chequeos). Si producción exige dos firmas, queda el pedido pendiente en despliegue.promocion_id.
notastringSólo con desplegar_hasta: por qué se promueve. Queda en el historial de despliegues.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

promover_agente

alcance: escritura

Sube la versión de un agente hasta el ambiente que pidas: hasta: «prod» recorre en UNA llamada todos los escalones que falten (dev → staging → prod), cada uno con sus chequeos (ensayo en verde antes de producción, ventana de cambios), y devuelve los escalones que recorrió. Editar un agente despliega la versión nueva sólo a dev (en el modo Libre, también a producción); SIN promoverla, producción sigue corriendo la anterior y los relojes de sus automatizaciones no disparan. Si la organización prendió cuatro ojos para producción y tiene dos o más publicadores (técnicos/admins), la llamada deja una promoción PENDIENTE (promocion_id) y la firma OTRA persona con aprobar_promocion; quien la pidió no puede aprobarla. Si hay UN solo publicador, la segunda persona no existe: se despliega con una firma, la respuesta lo dice (una_firma: true) y queda constancia en la bitácora. Al subir una versión, los pedidos pendientes de versiones anteriores del mismo agente se cancelan solos. Un desarrollador llega hasta pedir.

ArgumentoTipoQué es
agente_id (requerido)stringEl agente, de listar_agentes.
hastastaging · prodHasta dónde subir: «staging» (preproducción) o «prod». Recorre los escalones que falten.
desdestringOpcional (compatibilidad): «dev» o «staging». Sin hasta, sube UN escalón desde ahí, como antes.
notastringPor qué se promueve. Opcional; queda en el historial de despliegues.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_promociones

alcance: lectura · sólo lee · idempotente

Las promociones a producción de los agentes a los que la persona llega: pendientes de firma, aprobadas, rechazadas y canceladas, con quién pidió, quién decidió y si preproducción todavía corre la versión pedida. puedo_firmar dice si quien llama puede aprobar cada una.

ArgumentoTipoQué es
estadopendiente · aprobada · rechazada · canceladaSólo las de este estado. Por defecto, todas.
agente_idstringSólo las de este agente.
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

aprobar_promocion

alcance: escritura · idempotente

La segunda firma: despliega a producción la versión que otra persona pidió. La firma un técnico o un admin DISTINTO de quien pidió; un desarrollador no. Se rechaza si preproducción ya no corre esa versión o si la organización está fuera de su ventana de cambios. Mirá antes metricas_por_version.

ArgumentoTipoQué es
promocion_id (requerido)stringEl pedido, de listar_promociones o de promover_agente.
notastringQué se miró para firmar. Opcional; queda en el historial.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

rechazar_promocion

alcance: escritura · idempotente

Cierra un pedido pendiente sin desplegar. Si lo llama quien lo pidió, queda cancelado; si lo llama un técnico o un admin, rechazado. El motivo es obligatorio y es lo que va a leer quien pidió.

ArgumentoTipoQué es
promocion_id (requerido)stringEl pedido, de listar_promociones.
motivo (requerido)stringPor qué no sale.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

volver_a_version

alcance: escritura

Rollback: pone a correr en un ambiente una versión que YA corrió ahí. Es un despliegue nuevo apuntando a la vieja —el historial no se toca—. A producción lo hace un técnico o un admin, sin segunda firma ni ventana; en el modo Libre vuelve también la definición del agente (herramientas, control, correa), así la próxima edición no republica lo deshecho. Una versión que nunca corrió en ese ambiente se rechaza: eso es promover, no volver.

ArgumentoTipoQué es
agente_id (requerido)stringEl agente, de listar_agentes.
ambiente (requerido)dev · staging · prodDónde volver.
version (requerido)numberA qué versión volver, de metricas_por_version o historial_del_agente.
motivo (requerido)stringPor qué se vuelve. Obligatorio; queda en el historial de despliegues.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

metricas_por_version

alcance: lectura · sólo lee · idempotente

Por versión de un agente: en qué ambientes corre hoy, cuántas tareas hizo, cuántas verificadas, discrepancias y fallidas, costo total y por tarea, duración mediana y el último ensayo contra casos. Las tareas se cuentan por la versión con la que corrieron, no por la que corre ahora. Es lo que se mira antes de firmar una promoción o de volver.

ArgumentoTipoQué es
agente_id (requerido)stringEl agente, de listar_agentes.

politica_de_publicacion

alcance: lectura · sólo lee · idempotente

El modo de control de la organización («libre», «concontroles» o «regulado»: con qué diales nacen sus agentes) y la política de producción: si rige cuatro ojos, la ventana de cambios (días y horas en el huso del cliente) y si ahora mismo está abierta. Se cambia desde la pantalla Seguridad o con `configurarpublicacion`.

Sin argumentos.

configurar_publicacion

alcance: escritura · idempotente

Cambia el modo de control de la organización y su política de producción. modo («libre», «concontroles» o «regulado») dice con qué diales nacen los agentes nuevos; con `aplicara_actuales: true se los pone también a los que ya existen (la respuesta lista qué le cambió a cada uno). El modo deja cuatro ojos y la ventana como dice él: «regulado» los prende y los otros dos los apagan. Aflojar el modo exige técnico o admin; apretarlo, cualquier operador; si toca cuatro ojos o la ventana, un admin. Sin modo, sólo un admin: prende o apaga cuatro ojos y fija o quita la ventana de cambios: ventana es {dias: [1..7], desde: "HH:MM", hasta: "HH:MM"}` en hora del cliente (1 = lunes; una ventana que cruza medianoche vale), o null para no tener ventana. Todo queda asentado en la bitácora.

ArgumentoTipoQué es
modolibre · con_controles · reguladoEl modo de control de la organización. Libre es el de nacimiento: los controles se prenden.
aplicar_a_actualesbooleanCon modo: true para ponerles sus diales también a los agentes que ya existen. Por defecto false: sólo los nuevos.
cuatro_ojosbooleanSi la promoción a producción exige dos personas.
ventanaobjectnull{dias, desde, hasta} o null para quitarla.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

exportar_agente

alcance: lectura · sólo lee · idempotente

Devuelve el agente entero como un paquete yorobot/agente@1 para guardarlo en un repo: instrucción, conocimiento, cómo se verifica, herramientas con su riesgo, permisos y límites, Human in the Loop y verificación, las skills con su SKILL.md, los criterios vigentes y los casos de ensayo. Sin credenciales (sólo sus nombres), sin canales ni ids. Trae el hash del paquete y la versión actual del agente.

ArgumentoTipoQué es
agente_id (requerido)stringEl agente, de listar_agentes.

importar_agente

alcance: escritura · idempotente

Crea un agente desde un paquete yorobot/agente@1 —o, con agente_id, le deja una versión nueva a uno existente— y lo despliega SÓLO a prueba (dev). Producción no cambia hasta ensayaragente en verde y promoveragente. Guarda las skills del paquete (versión nueva si el cuerpo cambió), suma los criterios y casos que no estaban y valida todo antes de tocar nada: formato, límites, y que ningún texto traiga una credencial pegada. Si el paquete usa herramientas que la organización no declaró, falla y las lista; con sin_faltantes: true el agente nace sin ellas.

ArgumentoTipoQué es
paqueteobjectEl paquete entero, el JSON de exportar_agente o del archivo del repo. O en su lugar componente.
componentestringEn vez de paquete: la clave de un componente de la biblioteca (listarcomponentes). Se importa tal cual, con `sinfaltantes` implícito porque sus herramientas tienen nombres genéricos que hay que mapear.
nombrestringOpcional, con componente: el nombre que va a tener el agente.
agente_idstringOpcional: a qué agente existente aplicarle el paquete. Sin esto se crea uno nuevo.
clavestringClave estable elegida por vos (p. ej. «triaje-guardia»), única en la organización: si ya hay un agente con esa clave se le aplica el paquete (versión nueva en dev); si no, el que nace la lleva. Es lo que hace que yorobot agente aplicar se pueda repetir sin duplicar. Opcional; agente_id manda si vienen los dos.
sin_faltantesbooleantrue: importar aunque falten herramientas, y reportarlas. Por defecto falla.
notastringPor qué se importa (el commit, el PR). Opcional; queda en la auditoría.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_componentes

alcance: lectura · sólo lee · idempotente

Las primitivas reutilizables que salieron de implementaciones reales —Conector, Monitor, Conversador, Validador, Entrevistador, Parte, Cola de excepciones—, cada una un paquete de agente completo con instrucción, herramientas por nombre genérico, permisos, Human in the Loop, verificación, criterios y casos de ensayo. Devuelve el resumen con hash y versión; el paquete entero se ve con vercomponente y se importa con importaragente(componente).

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

ver_componente

alcance: lectura · sólo lee · idempotente

El paquete completo de un componente de la biblioteca, para leerlo o editarlo antes de importar: cambiarle las herramientas genéricas por las de la organización, ajustar umbrales del conocimiento, sumar casos.

ArgumentoTipoQué es
clave (requerido)stringLa clave del componente, de listar_componentes.

listar_trabajos

alcance: lectura · sólo lee · idempotente

Los trabajos que una empresa delega —«Growth: conseguir reuniones», «Atención de clientes», «Cobranzas», «Reporte para gerencia», «Seguimiento de CRM», «Facturación»—, cada uno con lo que gana la empresa, qué hace el agente, los sistemas que usa (y si esta organización ya los conectó), lo que siempre pregunta antes de hacer y el North Star sugerido. se_crea_al_llamar: true: hay una pieza armada (en la biblioteca, o un conector de la casa como el de AFIP) y crearagentedesde_trabajo la instala tal cual; false: se arma con el Constructor, y el pedido es con qué empezar. Es lo mismo que ofrece «Crear un agente» en el portal.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

crear_agente_desde_trabajo

alcance: escritura

Crea el agente de un trabajo de listartrabajos, igual que «Crear un agente» del portal: si el trabajo tiene pieza en la biblioteca (un equipo o una plantilla) la instala tal cual. Nace en producción (`ambiente: prod`) si la organización publica con una firma y vos podés publicar; si pide dos firmas o no podés, queda en prueba (`dev`) y `enpruebaporque` dice por qué. Lo que se edite después cae en prueba y sube con ensayaragente y promoveragente. De un equipo devuelve el líder, que es quien reparte. Nace aunque sus sistemas no estén conectados; se conectan después. El agente deja su primer mensaje en tu conversación con él; el de Facturación lo deja recién cuando AFIP queda conectado, porque esa conexión se hace en su chat del portal, guiada paso a paso (la persona saca el certificado con su clave fiscal en la página de AFIP: no se carga por acá). Con `meta`, fija además tu North Star (el `northstarsugerido` de listartrabajos, si se_mide_al_nacer) y lo devuelve medido. Si el trabajo se arma con el Constructor no crea nada (creado: false) y devuelve el pedido para hablarconel_constructor.

ArgumentoTipoQué es
trabajo (requerido)stringLa clave del trabajo, de listar_trabajos.
preguntar_todobooleantrue: que pida aprobación también antes de lo que se puede deshacer. Por defecto la pide sólo antes de lo que no se deshace.
metanumberOpcional: la meta de tu North Star (por ejemplo, 3 reuniones por semana). Con esto queda fijado como el tuyo; si ya tenías uno, lo cambia.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

ensayar_agente

alcance: escritura

Corre la versión actual del agente contra sus casos habilitados, en la misma cola y por el mismo camino que una tarea real. Sin lote ni casos corre todos los habilitados (techo 100); con lote corre los N más viejos habilitados, con casos sólo esos ids. Los casos deshabilitados nunca entran. Devuelve el id del ensayo y las tareas abiertas; el resultado se lee con caminoaproduccion o tarea por tarea con vertraza. Es el requisito para promover a producción cuando el agente tiene casos: sin ensayo en verde de ESTA versión, promoveragente se niega.

ArgumentoTipoQué es
agente_id (requerido)stringEl agente, de listar_agentes.
lotenumberCuántos casos correr, de los habilitados y del más viejo al más nuevo (1 a 100).
casoslistaSólo estos casos, por id de listar_casos. Los deshabilitados se saltean.
ambientedev · staging · prodDónde corre. Por defecto prod, como el ensayo de siempre; para iterar la instrucción conviene dev.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

camino_a_produccion

alcance: lectura · sólo lee · idempotente

Qué versión corre en prueba, preproducción y producción, cuántos casos tiene el agente, cómo salió el último ensayo (contra qué versión, cuántos pasaron) y, por escalón, si se puede promover ahora o qué lo frena. Es lo que se mira después de importaragente y antes de promoveragente.

ArgumentoTipoQué es
agente_id (requerido)stringEl agente, de listar_agentes.

listar_agentes

alcance: lectura · sólo lee · idempotente

Los agentes del tenant, con su oficio y cuántas herramientas tienen habilitadas.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

transferir_agente

alcance: escritura · idempotente

Cambia el dueño de un agente, una conexión o una fuente del Cerebro dentro de la organización. Lo hace el dueño actual, un técnico o un admin; quien recibe tiene que ser admin, técnico o desarrollador con asiento vigente. Si el que entrega o el que recibe está recortado por agente, el recorte sigue al agente. Queda en el historial de traspasos y en la bitácora.

ArgumentoTipoQué es
claseagente · conexion · fuenteQué se traspasa. Por defecto agente.
objeto_id (requerido)stringEl id del agente (listaragentes), la conexión (listarherramientas) o la fuente (listar_fuentes).
a_usuario (requerido)stringEl id de la persona que recibe, de listar_equipo o quien_soy.
motivo (requerido)stringPor qué; queda en el historial.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

eliminar_agente

alcance: escritura · destructiva · idempotente

Borra el agente de verdad: versiones, despliegues, casos, evaluaciones, memorias, canales, automatizaciones y llamadas, y también sus conversaciones (el chat con cada persona y los mensajes de sus canales). No se puede deshacer. Las tareas que hizo quedan, sin agente ni versión, porque son de quien las pidió y del consumo de la organización. Si era el copiloto de alguien, esa persona se queda sin copiloto. Queda el evento agente.eliminado en la auditoría. Sólo un admin, sólo si el agente está en descanso (editar_agente con activo: false) y sin tareas corriendo, y con confirmar igual a su nombre. Si lo que querés es que deje de trabajar sin perder nada, mandalo a descanso: no cuenta para el plan.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_agentes.
confirmar (requerido)stringEl nombre del agente, tal cual lo devuelve listar_agentes.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

traspasar_agentes

alcance: escritura · idempotente

Traspasa de una vez todos los agentes, conexiones y fuentes que una persona tiene a su nombre. Es lo que se hace antes de sacar a un desarrollador del equipo o cuando termina un consultor. Sólo técnico o admin. Cada objeto deja su propio traspaso en el historial.

ArgumentoTipoQué es
de_usuario (requerido)stringQuién entrega.
a_usuario (requerido)stringQuién recibe: admin, técnico o desarrollador con asiento vigente.
motivo (requerido)stringPor qué; queda en el historial.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

historial_de_traspasos

alcance: lectura · sólo lee · idempotente

Los traspasos de propiedad de la organización: clase, objeto, de quién, a quién, quién lo hizo, por qué y cuándo. Se puede acotar a un objeto.

ArgumentoTipoQué es
claseagente · conexion · fuenteSólo los traspasos de esa clase de objeto.
objeto_idstringSólo los traspasos de ese objeto.
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

ranking_de_agentes

alcance: lectura · sólo lee · idempotente

Lo mismo que la pantalla Ranking: los agentes de la organización comparados por lo que la verificación dio por bueno en los últimos dias (30 por defecto), no por tokens. Por agente: tareas, verificadas {n, de, tasa} sobre sus tareas, sin_discrepancia {n, de, tasa} sobre las medidas, costo por tarea y crecimiento contra el período anterior (nuevo si antes no trabajaba; null si no hay con qué comparar). orden: verificadas (por defecto), discrepancias (menos discrepancias primero), costoportarea (más barato primero) o crecimiento. Un agente sin tareas va al final; una tasa sin denominador es null, no 100 %. El gasto entero se mira en consumo_por_esfuerzo.

ArgumentoTipoQué es
ordenverificadas · discrepancias · costo_por_tarea · crecimientoPor qué ordenar: verificadas, discrepancias, costoportarea o crecimiento. Por defecto verificadas, como la pantalla.
diasnumberCuántos días mirar, de 1 a 90. Por defecto 30, como la pantalla.

agentes

alcance: lectura · sólo lee · idempotente

Los agentes de la organización con su id, si están activos y cómo vienen trabajando en los últimos 30 días. Es por dónde se empieza: el resto de las herramientas de lectura piden un agente_id.

Sin argumentos.

resumen_de_agente

alcance: lectura · sólo lee · idempotente

Cómo viene trabajando un agente en una ventana de días: cuántas tareas, cuántas pasaron verificación a la primera y sobre cuántas medidas, cuántas discrepancias, cuánto costó, cuánto tardó la mediana, y cuántas tareas están esperando a una persona.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de agentes.
diasnumberVentana en días. Por defecto 30.

tareas_del_agente

alcance: lectura · sólo lee · idempotente

Las tareas de un agente, de la más nueva a la más vieja, con su veredicto. El corte espera son las que reclaman a una persona y discrepancia las que el verificador contradijo: son las dos preguntas que se hacen todos los días.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente.
cortestringtodas \abiertas \espera \discrepancia \cerradas. Por defecto todas.
limitenumberCuántas traer. Máximo 30.

calidad_del_agente

alcance: lectura · sólo lee · idempotente

Lo que dicen los criterios sobre un agente en las últimas horas: la tasa de la auditoría de bitácora, cuánto coinciden las personas con el auditor, qué dice el juez con su costo aparte, y qué criterios no cubre nadie.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente.
horasnumberVentana en horas. Por defecto 24.

Probar

Evaluaciones: ensayos, casos y la prueba con traza. Área de búsqueda: evaluaciones.

ensayar_y_publicar

alcance: escritura

El camino a producción en una llamada: corre la evaluación de la versión actual contra todos sus casos habilitados y, cuando se mide el último, si pasaron todos la sube hasta producción con tu firma — o deja el pedido de firma si la organización pide cuatro ojos. Si algún caso falla, no sube nada y queda escrito qué caso y por qué. Llega un correo cuando termina; camino_a_produccion lo muestra en publicacion. Sin casos habilitados no corre: para subir sin evaluación está promover_agente.

ArgumentoTipoQué es
agente_id (requerido)stringEl agente, de listar_agentes.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

cargar_caso

alcance: escritura

Guarda un caso para ensayar al agente: una entrada y, si se quiere, qué se espera de la salida y qué herramientas tiene que usar o no puede tocar. Nace habilitado. Un paquete importado con importar_agente trae los suyos.

ArgumentoTipoQué es
agente_id (requerido)stringEl agente, de listar_agentes.
titulo (requerido)stringQué prueba este caso, en una línea.
entrada (requerido)objectLos datos con los que entra el agente: lo mismo que pediría pedir_tarea.
esperadolistaAserciones sobre salida.json: { campo, operador, valor } con operador igual, contiene, existe, falta o entre (entre lleva valor y hasta numéricos). El campo va con puntos: cotizacion.total.
herramientas_esperadaslistaHerramientas que el agente tiene que usar.
herramientas_prohibidaslistaHerramientas que no puede tocar.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_casos

alcance: lectura · sólo lee · idempotente

Los casos del agente, habilitados y deshabilitados, con qué esperan. Los ids sirven para ensayar_agente(casos), habilitar_caso y deshabilitar_caso.

ArgumentoTipoQué es
agente_id (requerido)stringEl agente, de listar_agentes.
solo_habilitadosbooleanSólo los que entrarían en un ensayo.
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

habilitar_caso

alcance: escritura · idempotente

Prende un caso deshabilitado: vuelve a entrar en los ensayos. No cambia nada más del caso.

ArgumentoTipoQué es
caso_id (requerido)stringEl caso, de listar_casos.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

deshabilitar_caso

alcance: escritura · idempotente

Apaga un caso: deja de entrar en los ensayos pero queda con su historia, para volverlo a prender. Es lo que se usa para iterar de a diez: se apagan los que todavía no se trabajan y se prenden a medida que se suman.

ArgumentoTipoQué es
caso_id (requerido)stringEl caso, de listar_casos.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

probar_agente

alcance: escritura

Corre el agente UNA vez en prueba (dev o staging, nunca prod) y espera el resultado: estado, costo, turnos, herramientas usadas con sus argumentos ya redactados, bloqueos, citas al Cerebro y el veredicto del verificador independiente. El agente no puede pedir más presupuesto ni más turnos que los suyos. Si el worker no la cierra en el plazo, devuelve el estado parcial y el id para seguirla con ver_traza. Antes de gastar, mide si como_se_verifica se puede releer con las lecturas de la caja y lo devuelve en criterio_de_verificacion (con aviso_verificacion si no); el veredicto del verificador viene en verificacion.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_agentes.
entradaobjectLos datos que el agente declara en su formulario.
titulostringQué se prueba, en una línea. Opcional.
ambientedev · stagingDónde corre. Por defecto dev.
presupuesto_usdnumberTope de esta corrida en dólares. Sólo puede ser menor que el del agente.
max_turnosnumberMáximo de turnos del modelo. Sólo puede ser menor que el del agente; techo 50.
espera_snumberCuánto esperar el cierre, en segundos (5 a 120). Por defecto 60.
en_secobooleanCorrida en seco: las herramientas con efecto se anotan y no se ejecutan; las lecturas corren. Sólo dev/staging. Lo decide quien prueba; el agente no puede cambiarlo.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

Equipos y reparto

Equipos de agentes, partir una tarea entre varios, pedirle algo a un par, ver el árbol y cuánta autonomía tiene el equipo técnico sobre cada proyecto. Área de búsqueda: equipos.

fijar_autonomia_del_proyecto

alcance: escritura · idempotente

Fija qué hace el agente programador con el trabajo verificado de un proyecto: shadow (0 · Sombra, propone y el cambio queda en YoRobot), assisted (1 · Asistido, tampoco publica), delegated (2 · Delegado, abre el PR y lo mergea una persona) o gated_auto (3 · Autónomo con gate: abre el PR y se mergearía solo con verificación, CI y revisión en verde, pero el worker todavía no corre la revisión, así que hoy también lo mergea una persona). Un equipo técnico recién instalado no abre PRs hasta que su proyecto llega a delegated. Bajar lo hace cualquier operador; subir, un técnico o un admin; gated_auto sólo un admin y nunca en un proyecto de cara al cliente. Rige desde el próximo pedido y queda en la auditoría con el antes y el después. La respuesta dice abre_pr y mergea_solo con el nivel que rige.

ArgumentoTipoQué es
proyecto_idstringEl id del proyecto. O repo.
repostringEl repositorio del proyecto, owner/nombre. O proyecto_id.
nivel (requerido)shadow · assisted · delegated · gated_autoEl nivel nuevo.
motivostringOpcional: por qué, para la auditoría.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

declarar_equipo

alcance: escritura · idempotente

Crea o actualiza un equipo de agentes: un líder que recibe el pedido y reparte, especialistas, y la matriz de a quién le puede pedir cada uno. Con la misma clave se ACTUALIZA en vez de crear otro, así que se puede aplicar dos veces. El equipo ANGOSTA: sus topes se combinan con los del agente y gana el más chico, y su matriz limita a quién se le puede pedir. Ojo: declarar el equipo NO le prende el reparto al líder — eso es aflojar y lo decide un técnico o un admin con editar_agente; la respuesta avisa si falta.

ArgumentoTipoQué es
clave (requerido)stringClave estable del equipo, única en la organización («redes»).
nombre (requerido)stringCómo se lo va a llamar en la pantalla.
lider_agente_id (requerido)stringEl agente que recibe el pedido y reparte.
presupuesto_arbol_usdnumbernullTecho en USD para TODA la tarea del equipo, hijas incluidas. Es el único techo agregado que existe: sin él, seis hijas respetan prolijamente su presupuesto individual y el total no lo autorizó nadie. null lo saca.
profundidad_maxnumberNiveles de reparto (1 a 10, por defecto 2).
hijas_maxnumberHijas por reparto (1 a 20, por defecto 6).
activobooleanfalse apaga el equipo: no se le pueden pedir tareas nuevas.
miembroslistaLos miembros, reemplazan a los que había (se DECLARA el equipo, no se parchea: un miembro que sacaste del archivo tiene que desaparecer de la base). Cada uno: {agenteid, rol?, puedepedirlea?}. `puedepedirle_a` son ids de OTROS miembros del equipo.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_equipos

alcance: lectura · sólo lee · idempotente

Los equipos de la organización con su líder, sus miembros, la matriz de delegación y sus topes.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

ver_equipo

alcance: lectura · sólo lee · idempotente

Un equipo por clave o por id: líder, miembros con su rol, a quién le puede pedir cada uno, y los topes.

ArgumentoTipoQué es
equipo (requerido)stringLa clave del equipo («redes») o su id.

exportar_equipo

alcance: lectura · sólo lee · idempotente

El equipo entero como paquete portable: los agentes por CLAVE (no por id, porque en otra organización los ids son otros) y la matriz reescrita con esas claves. Trae además lo que el equipo usa: las automatizaciones que le piden a él o a sus agentes, las consolas publicadas de sus agentes, las entidades de Datos que esas consolas y automatizaciones miran, y el proyecto del líder. Sin credenciales ni secretos: viajan los nombres de las herramientas y «tiene un webhook», no su URL. Lo que sale de acá entra por importar_equipo tal cual.

ArgumentoTipoQué es
equipo (requerido)stringLa clave del equipo o su id, de listar_equipos.

importar_equipo

alcance: escritura · idempotente

Crea o actualiza un equipo entero desde un paquete: primero las entidades de Datos y el proyecto que el paquete declare, después cada agente por su clave —la segunda vez se le deja una versión nueva en vez de crear otro—, la matriz, las automatizaciones (que NACEN APAGADAS) y la consola (nueva se publica; si ya estaba publicada y cambia, queda propuesta). Aplicar el mismo paquete dos veces deja la organización igual y la respuesta dice sin_cambios: true. También dice qué herramientas nombra el paquete que esta organización no tiene declaradas, si al líder le falta prender el reparto, y la URL y el secreto de cada webhook NUEVO — una sola vez.

ArgumentoTipoQué es
paquete (requerido)objectEl paquete, como lo devuelve exportar_equipo o como está en el bloque equipo: de yorobot.yaml.
sin_faltantesbooleantrue para que los agentes nazcan sin las herramientas que esta organización no tiene declaradas, en vez de rechazar el paquete. Por defecto false: un nombre mal tipeado no deja a un agente sin su herramienta en silencio.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

descomponer_tarea

alcance: escritura · idempotente

Parte una tarea en tareas hijas, cada una con UN agente responsable. La madre queda bloqueada por las hijas y se despierta cuando terminan, con lo que cada una devolvió. Es idempotente por el conjunto de claves: volver a llamarla con el mismo plan no duplica nada y contesta ya_estaba. Los límites del agente de la madre (profundidad y cuántas hijas por vez) y el presupuesto del árbol se aplican igual acá que cuando reparte el agente solo.

ArgumentoTipoQué es
tarea_id (requerido)stringLa tarea que se reparte. Es la que va a esperar a las hijas.
hijas (requerido)listaLas hijas. Cada una: {clave, titulo, descripcion, agente_id, entrada?, bloquea?}. clave es un nombre corto y estable del paso: es lo que permite reanudar sin duplicar. bloquea: false si la madre puede seguir sin esperarla.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

mandar_mensaje

alcance: escritura

Crea una tarea para otro agente con un pedido puntual adentro: coordinación lateral, no reparto. No entra al árbol de quien pide —a propósito, porque el destinatario puede no tener permiso para leerlo—, así que el pedido tiene que ser autocontenido. Cuesta cuota de mensajero: dos agentes que se mandan pedidos son la forma más barata de un bucle que se paga por vuelta.

ArgumentoTipoQué es
tarea_id (requerido)stringLa tarea desde la que se pide. Queda como origen del pedido.
agente_id (requerido)stringEl agente al que se le pide.
titulo (requerido)stringDe qué se trata, en una línea.
descripcion (requerido)stringEl pedido completo, autocontenido. Mínimo 30 caracteres.
bloqueabooleanSi quien pide no puede seguir sin la respuesta. Por defecto no.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

ver_comunicacion

alcance: lectura · sólo lee · idempotente

El hilo de una tarea que se repartió: quién repartió qué, quién le pidió algo puntual a quién, qué volvió con su veredicto y qué espera una firma, en orden, con el costo de cada tramo. No es un chat: son los actos que quedaron registrados. Sirve para contestar «quién autorizó a quién a gastar cuánto» sin leer la bitácora cruda.

ArgumentoTipoQué es
tarea_id (requerido)stringCualquier tarea del árbol: el hilo se arma desde la raíz.

arbol_de_tarea

alcance: lectura · sólo lee · idempotente

La madre y las hijas de una tarea, con estado en castellano, si el VERIFICADOR la dio por hecha, si se canceló, cuánto costó y cuáles siguen bloqueando. verificada no es lo mismo que terminada: una hija puede estar cerrada sin que nadie la haya comprobado, y ahí su trabajo no se puede dar por hecho.

ArgumentoTipoQué es
tarea_id (requerido)stringLa tarea desde la que se mira el árbol.

armar_vigia_de_mercado

alcance: escritura · idempotente

Arma (o devuelve, si ya existe) el Vigía de mercado de quien llama: el sub-agente de su copiloto que sale a internet a buscar noticias, competidores, estrategias e ideas, y vuelve con recomendaciones citadas. Sólo lee: busca y lee páginas públicas por el portal, nunca escribe, publica ni manda nada, y corre contenido porque lo que lee lo escribió un tercero. Lo suma al equipo del copiloto y, salvo semanal: false, programa una automatización del copiloto los lunes a las 8 (zona de la organización) que le reparte una vuelta por internet. Cada hecho del informe vuelve marcado comprobado sólo si su cita está en la página que el portal le trajo en esa tarea. Pide un copiloto prendido; lo arma un técnico o un admin.

ArgumentoTipoQué es
semanalbooleanfalse para no programar la vuelta de los lunes. Por defecto, true.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

pedir_al_vigia

alcance: escritura

Le pide al Vigía de mercado una búsqueda ahora, sin esperar al lunes. La tarea es del copiloto: le reparte al Vigía y recibe su informe ya comprobado (hechos con url, fuente, fecha de publicación y de consulta; señales, inferencias y recomendaciones con confianza y si requieren aprobación). Seguila con estado_de_tarea. Antes, armar_vigia_de_mercado.

ArgumentoTipoQué es
pregunta (requerido)stringQué querés que busque afuera, en una o dos oraciones («qué están haciendo los competidores de VelaFi en cobranzas»).
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

Copilotos por persona

El perfil de cada persona —canal, hora, intereses—, su copiloto, su North Star medido y el briefing diario con sus decisiones. Área de búsqueda: copilotos.

mi_perfil

alcance: lectura · sólo lee · idempotente

Tu perfil en esta organización para tu copiloto: por qué canal te llega el briefing (portal, correo, WhatsApp, Slack, Telegram, Teams) y a qué hora, en qué zona e idioma, qué temas querés ver y cuáles evitar, y cuál es tu copiloto. entrega dice por dónde te llega HOY y, si no es tu canal, por qué: un WhatsApp o un Slack sin vincular no recibe nada hasta que mandes el código desde ahí (editar_mi_perfil con vincular: true). Quien opera puede pedir el de otra persona con persona (su correo).

ArgumentoTipoQué es
personastringEl correo de otra persona de la organización (sólo admin o técnico). Vacío: el tuyo.

editar_mi_perfil

alcance: escritura · idempotente

Cambia tu perfil: canal (portal, app —los avisos al teléfono de la app—, email, whatsapp, slack, telegram, teams), direccion (tu WhatsApp con código de país, tu id de Slack «U…», tu chat de Telegram), hora (HH:MM, 24 h), zona (IANA, «America/Argentina/Buenos_Aires»), idioma, pais (ISO-2) e intereses ({ temas, evitar, longitud: corta|media|larga }). Cambiar el canal o la dirección la deja SIN VINCULAR. Con vincular: true devuelve un código de un solo uso: mandalo desde ese canal al copiloto de la organización y recién ahí el briefing te llega por ahí y podés elegir decisiones contestando. Así nadie pone su número en tu perfil y firma por vos. Con hora, zona y copiloto, tu briefing diario queda programado solo. Quien opera edita el de otra persona con persona (su correo): queda sin vincular hasta que esa persona mande su código.

ArgumentoTipoQué es
personastringEl correo de otra persona (sólo admin o técnico). Vacío: el tuyo.
canalstringportal, app, email, whatsapp, slack, telegram o teams. app avisa al teléfono donde activaste los avisos de la app (app.yorobot.ai → Yo).
direccionstringTu dirección en ese canal. No va con portal ni email (el correo es el de tu usuario).
horastringLa hora del briefing, HH:MM en 24 horas.
zonastringTu zona horaria IANA.
idiomastringes, en, pt…
paisstringCódigo de dos letras: AR, CL, MX…
interesesobject{ "temas": ["caja", "competencia"], "evitar": ["fútbol"], "longitud": "corta" }.
silencio_desdestringDesde qué hora no te interrumpe tu copiloto (HH:MM, en tu zona). Va con silencio_hasta; los dos en null lo sacan.
silencio_hastastringHasta qué hora (HH:MM). Puede cruzar la medianoche: 22:00 a 07:00.
avisos_por_dianumberCuántos avisos por día acepta (0 a 20; por defecto 3). Lo que sobra te llega en el briefing.
vincularbooleanDevolver el código para vincular el canal. Sólo para tu propio perfil.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

asignar_copiloto

alcance: escritura · idempotente

Le asigna a una persona su copiloto: el agente de proceso que le escribe el briefing y al que le contesta. Varias personas pueden compartir el mismo agente —cada corrida lleva el perfil de su persona—, que es lo que se sostiene en el tiempo; un agente por persona, no. Con agente_id vacío se lo saca. Si la persona ya tiene hora y zona, su briefing diario queda programado.

ArgumentoTipoQué es
persona (requerido)stringEl correo de la persona.
agente_idstringEl agente, de listar_agentes. Vacío para sacárselo.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

programar_briefings

alcance: escritura · idempotente

Deja al día la rutina diaria del briefing de cada persona con copiloto: a SU hora, en SU zona, prendida si tiene copiloto, hora y zona, y apagada si le falta alguno. Es lo mismo que pasa solo al editar un perfil; sirve después de un alta en tanda. Devuelve cada persona con su hora, su zona y si quedó programada, y por qué no si no.

ArgumentoTipoQué es
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_objetivos

alcance: lectura · sólo lee · idempotente

Cada North Star con su número de hoy, ya medido por el sistema: valor y meta con su unidad, falta, avance_pct, va_bien (null = todavía no se sabe) con va_bien_por, la proyeccion_a_fecha_meta marcada estimada, medido_at, la cita de dónde sale el número, y no_pude_medir si la última medición falló. Más sus métricas de entrada y sus contramétricas (cruzo_el_umbral). Ves el tuyo y el de la organización; quien opera ve además el de cada persona. No sumes ni proyectes vos: está calculado.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

ver_objetivo

alcance: lectura · sólo lee · idempotente

Un North Star con lo mismo que listar_objetivos, más cómo se mide (como_se_mide), su definición (metrica, entradas, contrametricas, limites, cadencia) y su version. Sin objetivo_id, el tuyo.

ArgumentoTipoQué es
objetivo_idstringEl id, de listar_objetivos. Sin él, tu North Star.

definir_objetivo

alcance: escritura · idempotente

El North Star: el número que, si mejora este trimestre, sabés que te fue bien. Se mide contra una fuente que el sistema sabe leer —una entidad de Datos, una lectura del copiloto o la carga manual— y el número lo calcula el servidor, nunca el modelo. Sin guardar: true es la vista previa: valida la métrica contra las fuentes (la entidad, el campo y la herramienta existen y el copiloto los lee) y la MIDE una vez, sin guardar nada: hoy dice «Hoy está en US$ 740.000. La meta de US$ 1.200.000 es +62 % en 91 días». Con guardar: true queda como tu North Star, arrancando con ese valor. El de la organización lo fija un admin en su conversación con el copiloto: por acá nadie entra como admin. Uno activo por persona: definirlo de nuevo lo CAMBIA, y si cambia la métrica o la meta es una versión nueva (queda en la bitácora). Lo persigue tu copiloto, o el agente de agente_id. Hasta 3 entradas (lo que lo mueve) y 2 contrametricas (lo que no puede empeorar, con su umbral). limites es lo que el copiloto no puede hacer para llegar: contexto, no permiso.

ArgumentoTipoQué es
titulo (requerido)stringEl número en tus palabras: «Pipeline calificado de Chile en Q4».
porquestringPor qué ese número, en una línea.
metrica (requerido)objectContra qué se mide. De Datos: { "fuente": "datos", "entidad", "agregado": "suma"\"cuenta"\"promedio"\"ultimo"\"proporcion" (el % de los registros con "campo" lleno; va con "unidad": "%", y sin registros que contar queda «no pude medir», no 0 %), "campo" (no hace falta para cuenta), "estado"?: el estado del registro ("demo"), o "estados"?: varios (["lead", "demo"]), "filtro"?: [{ "campo", "op", "valor" }] (o como en los bloques: { "campo", "igual" }), "ventana"?: "todo" (por defecto: el saldo de hoy) \"semana" \"mes" \"trimestre" \"desde" (con "desde": AAAA-MM-DD), "fecha"?: por qué fecha corta la ventana ("creado", "actualizado" o un campo fecha), "unidad": moneda ISO \"%" \"cantidad", "sentido": "subir" \"bajar" }. De una lectura del copiloto: { "fuente": "herramienta", "herramienta", "args", "ruta": dónde está el número en la respuesta ("total", "data.items[0].monto"), "unidad", "sentido" }. Sin fuente que lo calcule: { "fuente": "manual", "unidad", "sentido" }.
meta (requerido)numberLa meta, en la unidad de la métrica.
linea_basenumberDesde dónde se cuenta el avance. Sin ella, la primera medición.
fecha_metastringPara cuándo (AAAA-MM-DD).
cadenciadiaria · semanalCada cuánto lo mide el sistema (por defecto diaria).
entradaslistaHasta 3 métricas que lo mueven: [{ "nombre", "metrica" }].
contrametricaslistaHasta 2 que no pueden empeorar: [{ "nombre", "metrica", "umbral" }].
limitesstringLo que el copiloto no puede hacer para llegar («no ofrecer descuento arriba de 10 %»).
agente_idstringEl agente que lo persigue. Sin él, tu copiloto.
padre_idstringEl objetivo de arriba del que cuelga (opcional), de listar_objetivos.
guardarbooleantrue lo guarda; sin él es la vista previa (mide y no guarda).
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

medir_objetivo

alcance: escritura

Mide ahora un North Star (el tuyo, sin objetivo_id) y devuelve cómo quedó. Uno de carga manual se mide con el valor que mandás (lo carga su dueña); uno que mide el sistema no acepta un valor a mano. Si no se pudo medir, la falla queda escrita (no_pude_medir) y el último valor bueno sigue a la vista.

ArgumentoTipoQué es
objetivo_idstringEl id, de listar_objetivos. Sin él, tu North Star.
valornumberSólo para uno de carga manual: el número de hoy.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

pausar_objetivo

alcance: escritura · idempotente

Pausa un North Star (deja de medirse y de viajar al copiloto) o, con pausar: false, lo reanuda. No borra nada. Uno activo por persona: para reanudar uno, el otro tiene que estar pausado. El tuyo lo pausás vos; el de la organización, un admin.

ArgumentoTipoQué es
objetivo_idstringEl id, de listar_objetivos. Sin él, tu North Star.
pausarbooleantrue (por defecto) lo pausa; false lo reanuda.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

configurar_despertadores

alcance: escritura · idempotente

De día tu copiloto se despierta por tu North Star y te avisa, con cuota: despertadores es la lista de lo que lo despierta — { "tipo": "umbral", "serie": "principal"|"entrada:0"…|"contra:0"…, "operador": "<"|"<="|">"|">=", "valor" } · { "tipo": "fuenteviva", "temas"?: [..] } (algo nuevo en una fuente viva de la organización que toca tus temas) · { "tipo": "evento", "entidad", "a"?: estado } (un registro de Datos que cambia de estado) · { "tipo": "decisionvence", "horas"? } · { "tipo": "reloj", "hora": "HH:MM" }. Una contramétrica que cruza su umbral lo despierta siempre, y es urgente. escalon: investigar (sólo avisa), borrador (te deja la tarea armada para aprobar) o piloto (hace lo que se deshace y no mueve plata sin tu aprobación, y te lo cuenta). Lo irreversible lo firmás siempre vos. Cada despertar pasa antes por una evaluación barata: si no importa para tu número, no te escribe. Lo que cae en tu silencio o pasa tu cuota de avisos (editar_mi_perfil) te llega en el briefing.

ArgumentoTipoQué es
objetivo_idstringTu North Star, de listar_objetivos. Sin él, el tuyo.
despertadoreslistaHasta 6; reemplaza los que había. [] los saca.
escaloninvestigar · borrador · pilotoQué hace cuando se despierta.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

ver_diario_de_sueno

alcance: lectura · sólo lee · idempotente

La noche de tu copiloto (la última, o la de fecha): si durmió, se salteó (no hubo nada que repasar: costo cero) o no terminó, y por qué; el diario con cada oración marcada con_evidencia o es_inferencia; lo que aprendió con quién lo decide (lo_decide: vos, si es una preferencia tuya; un admin o un técnico, si es del negocio); el plan de hoy con su impacto (impacto_es_estimado: true), su costo estimado, si es reversible y qué encargaría «Hacerlo»; las preguntas; las lecturas que dejó preparadas, ya calculadas; y la autoevaluacion de lo que propuso ayer (efecto verificado o coincidencia). Dormir no es actuar: de noche sólo lee y propone. Las propuestas se eligen como cualquier decisión (elegir_decision).

ArgumentoTipoQué es
fechastringAAAA-MM-DD, en tu zona. Sin ella, la última noche.

configurar_sueno

alcance: escritura · idempotente

Tu noche: prendido (true/false), hora (HH:MM en tu zona; corre siempre antes de tu briefing, y si la pedís después se corre a 3 horas antes y te lo dice corrida) y tope_usd (lo que puede gastar una noche, entre US$ 0,05 y US$ 5). Sin nada para cambiar, es error. Devuelve cómo quedó: la hora real, si va a dormir esta noche (duerme) y por qué no, y el techo del mes de la organización (provisorio).

ArgumentoTipoQué es
prendidobooleanfalse la apaga; true la prende.
horastringHH:MM, en tu zona (por defecto 02:00).
tope_usdnumberLo que puede gastar una noche (por defecto US$ 0,50).
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_aprendizajes

alcance: lectura · sólo lee · idempotente

Cada cosa que propuso aprender tu copiloto de noche, con cómo está hoy (propuesto, guardado, descartado, frenado), quién lo decide (lo_decide) y cuántas evidencias del día la respaldan. estado filtra: propuesta, activa o todas (por defecto). Tus preferencias se guardan con aceptar_aprendizaje; lo del negocio lo acepta un admin o un técnico en Memoria.

ArgumentoTipoQué es
estadopropuesta · activa · todasCuáles (por defecto todas).
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

aceptar_aprendizaje

alcance: escritura · idempotente

Guarda una preferencia tuya que tu copiloto aprendió de noche (de listar_aprendizajes o ver_diario_de_sueno): desde ahí viaja a lo que trabaja para vos, y a nadie más. Con contenido, la guarda editada; el texto vuelve a pasar por el filtro de memorias (sin órdenes al modelo, credenciales ni datos de contacto). Sólo las tuyas: lo del negocio lo acepta un admin o un técnico en Memoria.

ArgumentoTipoQué es
memoria_id (requerido)stringEl id del aprendizaje.
contenidostringCómo querés que lo recuerde, si no tal cual.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

rechazar_aprendizaje

alcance: escritura · idempotente

Descarta una preferencia tuya que propuso tu copiloto, o la olvida si ya estaba guardada: deja de viajar en la próxima corrida. Queda la constancia en la bitácora. Sólo las tuyas.

ArgumentoTipoQué es
memoria_id (requerido)stringEl id del aprendizaje.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

Tareas

Pedir trabajo, seguirlo, leer su traza, las fallas que se repiten, preguntarle algo a un agente, tu conversación con cada agente, tus recordatorios y ver qué espera aprobación. Área de búsqueda: trabajo.

pedir_tarea

alcance: escritura

Le pide una tarea a un agente, o a un EQUIPO de agentes. La ejecuta un worker; esto sólo la encola. Con equipo la tarea va al líder y nace con el presupuesto de árbol del equipo; con agente_id va a ese agente y sin techo agregado, que es el comportamiento de siempre.

ArgumentoTipoQué es
agente_idstringEl id del agente, de listar_agentes. Uno de los dos: agente_id o equipo.
equipostringLa clave del equipo («redes»), de listar_equipos. La tarea va a su líder, que la reparte entre los miembros según la matriz, con el presupuesto de árbol del equipo como techo de todo.
titulo (requerido)stringQué se le pide, en una línea.
entradaobjectLos datos que el agente declara en su formulario.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

preguntar_a_agente

alcance: escritura

Le hace UNA pregunta a un agente y devuelve su respuesta en segundos, sin crear una tarea: el agente contesta sólo con sus herramientas de LECTURA (también las que leen la base del cliente conectada con conectar_base), con su instrucción y su memoria. No cambia nada afuera: si la pregunta pide algo que escribe, la respuesta trae requiere_tarea y hay que usar pedir_tarea. Un agente que también tiene herramientas que escriben contesta por acá sólo con solo_lectura: true. Si tarda más que espera_s, devuelve consulta_id: volvé a llamar con ese id (sin pregunta) para leer la respuesta. Cuenta contra el tope diario de charla del sujeto.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_agentes.
preguntastringLo que se le pregunta, en lenguaje natural.
historialistaTurnos anteriores de esta conversación, si los hay, en orden: {de: "persona" \"agente", texto}. La pregunta va aparte.
solo_lecturabooleanPara un agente que también escribe: contestar sólo con sus lecturas. Lo que escribe no se ejecuta nunca por acá.
sujetostringDe parte de quién se pregunta (la empresa, el cliente). El tope diario se cuenta contra esto; si falta, contra el agente.
espera_snumberCuánto esperar la respuesta, en segundos (5 a 60). Por defecto 45.
consulta_idstringPara retomar una consulta que devolvió termino: false. Con esto no hace falta pregunta. La retoma sólo la persona que la pidió, y la respuesta se guarda 24 h.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_hilos

alcance: lectura · sólo lee · idempotente

Tu bandeja: cada agente al que llegás, con tu conversación con él si ya le escribiste —el último mensaje, cuándo, y cuántos tenés sin leer—. Primero las fijadas y las que tienen algo sin leer, después las más recientes. Es la misma conversación que ves en la app: lo que escribas con escribir_en_hilo aparece ahí, y al revés. Para leer una entera, ver_hilo.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

ver_hilo

alcance: lectura · sólo lee · idempotente

Tu conversación con un agente, en orden: tus mensajes y los suyos (con los nombres de lo que leyó para contestar), las tareas que encargó desde la charla con su estado, y los briefings que te entregó como copiloto con sus decisiones (pendiente, vencida y, por opción, se_firma_en_el_portal). Sólo la tuya: nadie —tampoco un admin— lee la conversación de otra persona. Con antes (el cuando del primer item que ya tenés) trae la página anterior. Leerla no la marca como leída.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_hilos o listar_agentes.
antesstringPara la página anterior: el cuando (ISO) del primer item que ya tenés.
limitenumberCuántos items traer. Por defecto 50, máximo 200.

escribir_en_hilo

alcance: escritura

Le escribís a un agente en TU conversación con él —la misma de la app— y te contesta en segundos con sus herramientas de lectura y la versión publicada en producción. Si lo que pedís es trabajo (algo que cambia datos), lo encarga como tarea: la respuesta trae tarea_id, y la tarea sigue el camino de siempre (worker, verificación y, si hace falta, aprobación). Con como_tarea: true va directo como tarea, sin charla. Cuenta contra tu tope diario de charla con ese agente. Mandá clave_de_pedido: con la misma clave, un reintento no manda el mensaje dos veces ni encarga otra tarea (la respuesta completa queda en tu conversación: leela con ver_hilo). Estas herramientas piden un token que generaste vos: uno que otra persona emitió a tu nombre no abre tu conversación.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_hilos o listar_agentes.
texto (requerido)stringLo que le escribís, en lenguaje natural. Hasta 4000 caracteres.
como_tareabooleanMandarlo directo como tarea, sin charla: lo que escribís es el pedido.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

generar_pdf

alcance: escritura

Arma un PDF con bloques de Datos —contador, tabla, lista, gráfico, línea de tiempo, mapa— que el servidor resuelve con tu alcance: los números los calcula el sistema, con el período en fechas y lo recortado dicho debajo de cada tabla. Los bloques son los mismos que un agente muestra en el chat, por ejemplo { "tipo": "grafico", "titulo": "Pedidos por estado", "entidad": "pedidos", "por": "estado", "periodo": "este_mes" }. El PDF queda como archivo en TU conversación con ese agente (lo ves en la app) y la respuesta trae el link para bajarlo con tu sesión, las páginas y el peso. Con incluir_contenido: true, además el PDF en base64 (hasta 2 MB).

ArgumentoTipoQué es
agente_id (requerido)stringEl agente, de listar_hilos o listar_agentes: el archivo queda en tu conversación con él.
titulo (requerido)stringEl título del documento.
bloques (requerido)listaHasta 3 bloques de datos, como los del chat.
textostringUn párrafo que va arriba de los bloques. Opcional.
incluir_contenidobooleanDevolver también el PDF en base64 (hasta 2 MB).
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_recordatorios

alcance: lectura · sólo lee · idempotente

Los recordatorios que confirmaste en tus conversaciones con los agentes: qué dice cada uno (que), con qué agente, cuándo (cuando, con día, hora y zona: «todos los lunes a las 09:00 ART»), si se_repite, qué pasa a esa hora (que_hace: te llega el texto, o el agente te lo contesta con tus datos), el estado con sus booleanos (activo, pausado, cumplido), el proximo aviso y cómo te llegó el ultimo_aviso (por dónde, y si no llegó por tu canal, por qué). Sólo los tuyos: nadie más los ve, tampoco un admin. vivos y tope dicen cuántos te quedan. Un recordatorio se crea proponiéndolo en el chat (escribir_en_hilo: «recordame el jueves a las 9 que…») y confirmándolo en la app; propuestas_sin_confirmar son las que un agente te propuso y todavía no existen.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

pausar_recordatorio

alcance: escritura · idempotente

Pausa uno de tus recordatorios (deja de avisar hasta que lo reanudes) o, con pausar: false, lo reanuda. No borra nada. Uno de una sola vez cuyo momento pasó mientras estaba pausado no se reanuda: pedile al agente uno nuevo.

ArgumentoTipoQué es
recordatorio_id (requerido)stringEl id, de listar_recordatorios.
pausarbooleantrue (por defecto) lo pausa; false lo reanuda.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

borrar_recordatorio

alcance: escritura · destructiva · idempotente

Borra uno de tus recordatorios: deja de avisar y no vuelve (para frenarlo sin perderlo, pausar_recordatorio). Lo que ya te llegó queda en tu conversación con el agente.

ArgumentoTipoQué es
recordatorio_id (requerido)stringEl id, de listar_recordatorios.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

ver_traza

alcance: lectura · sólo lee · idempotente

Todo lo que quedó registrado de una tarea: cada tramo del modelo con duración y costo, cada herramienta con sus argumentos ya redactados y si el puente la dejó pasar, los bloqueos, las citas al Cerebro comprobadas y el veredicto del verificador. Sólo de tareas de agentes a los que la persona llega.

ArgumentoTipoQué es
tarea_id (requerido)stringEl id de la tarea, de probar_agente, pedir_tarea o listar_tareas.

ver_actividad

alcance: lectura · sólo lee · idempotente

El hilo de actividad de un agente o de un registro, del más nuevo al más viejo: tareas pedidas y cerradas, tramos del modelo, herramientas con duración y costo, frenos y bloqueos, esperas a una persona, mensajes por canal, llamadas y registros movidos. Es el mismo flujo que la pantalla Actividad del agente, con los mismos filtros. Sólo de agentes y registros a los que la persona llega; el detalle viene recortado y sin argumentos crudos. Para una tarea puntual, ver_traza trae más.

ArgumentoTipoQué es
agente_idstringEl agente. Obligatorio si no se da equipo_id ni registro_id.
equipo_idstringUn equipo (clave o id, de listar_equipos): los hechos de sus últimas corridas, el árbol entero —lo que hizo el líder y lo que hicieron las hijas—. Si se da, agente_id se ignora.
registro_idstringUn registro de Datos: sólo lo que los agentes hicieron sobre él. Si se da, agente_id se ignora.
clasestringSólo hechos de esta clase (una o varias separadas por coma): tarea, modelo, herramienta, freno, verificacion, espera, mensaje, llamada, registro, cierre.
herramientastringSólo hechos de esta herramienta.
solo_erroresbooleanSólo lo que salió mal o se frenó.
tarea_idstringSólo lo de esta tarea.
buscastringUna palabra del título o el detalle.
limitenumberCuántos traer por página (1 a 100). Por defecto 50.
desdenumberDesde qué posición arrancar, para paginar.

listar_tareas

alcance: lectura · sólo lee · idempotente

Las tareas de los agentes a los que la persona llega, de la más nueva a la más vieja, con estado, ambiente, origen y su columna del tablero (columna_texto; frenada: que_la_mueve; madre: hijas; corriendo: silencio). Filtra por agente, estado, columna, ambiente o sólo abiertas. El total cuenta lo visible para esta persona.

ArgumentoTipoQué es
agente_idstringSólo las de este agente.
estadostringSólo las que están en este estado: new, dispatched, running, verified, inreview, approved, merged, needshuman, rejected o rehearsed.
columnapendiente · trabajando · te_espera · frenada · hechoSólo las de esta columna.
ambientedev · staging · prodSólo las de este ambiente.
abiertasbooleanSólo las que todavía se mueven.
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

estado_de_tarea

alcance: lectura · sólo lee · idempotente

En qué anda una tarea y qué midió el verificador, si ya corrió. resultado: lo que devolvió el agente (lo dice él, no la verificación). conversacion: el hilo con sus hijas, los últimos 30 turnos con el aviso adentro.

ArgumentoTipoQué es
tarea_id (requerido)stringEl id que devolvió pedir_tarea.

tareas_estancadas

alcance: lectura · sólo lee · idempotente

Las tareas abiertas que no tienen quién las mueva: nadie las está corriendo, no esperan a una persona nombrada y no tienen despertador. Es la lista que contesta «esto está frenado y nadie se enteró», con desde cuándo.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

repetir_tarea

alcance: escritura

Encola una tarea nueva con la misma entrada y el mismo agente que una anterior. La original no se modifica ni se borra: queda su corrida, su claim y lo que midió el verificador. Sirve para reintentar lo que falló por algo de afuera; si falló por cómo está configurado el agente, repetir sin cambiar nada vuelve a fallar y vuelve a costar.

ArgumentoTipoQué es
tarea_id (requerido)stringEl id de la tarea a repetir.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

contestar_pregunta

alcance: escritura

Contesta la pregunta que un agente dejó en una tarea («Te pregunta» en Te espera). La tarea vuelve a la cola y sigue desde donde quedó, con lo que ya hizo, lo que ya salió y todas las respuestas anteriores. Contesta quien pidió la tarea o quien opera. Una respuesta que parece una clave se rechaza: las credenciales van en Conexiones. Una pregunta que pide una llave o trae órdenes no se contesta por acá.

ArgumentoTipoQué es
tarea_id (requerido)stringLa tarea que espera la respuesta.
respuesta (requerido)stringLa respuesta, en una línea (hasta 1.000 caracteres).
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

seguir_tarea

alcance: escritura

Para una tarea a la que le faltó una herramienta («Le falta algo» en Te espera) o que el agente dejó sin terminar («Frenada»). Si le faltaba algo que la organización ya tiene, se lo prende; si la app no está conectada, dice qué conectar. Si no terminó, la tarea sigue desde donde quedó con lo que ya hizo. Lo hace quien opera.

ArgumentoTipoQué es
tarea_id (requerido)stringLa tarea que esperaba la herramienta o que no terminó.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

aprobaciones_pendientes

alcance: lectura · sólo lee · idempotente

Lo que espera a una persona, en el orden que importa: primero las discrepancias (el agente declaró éxito y la medición dijo otra cosa), después lo que el verificador rechazó, al final lo verde, que es trámite. Cada fila dice tramite (verificada en limpio, sin discrepancia ni nada que salga al mundo: lo que se aprueba en lote) o por_que_no_es_tramite; tramite arriba cuenta toda la cola. Trae el link de cada una. Vos no aprobás: aprobar le da a la persona un enlace, por una (tarea_id) o por el lote de trámite (tarea_ids).

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

resolver_efecto_incierto

alcance: escritura · idempotente

Para una tarea RETENIDA: su corrida murió con una acción con efecto pedida y sin resultado (un mail, un post), y no se vuelve a correr sola porque repetirla podría mandarlo dos veces. La persona de este token mira el sistema y dice qué pasó; queda en la auditoría con su nombre. no_salio y salio la vuelven a la cola con una continuación (salio marca lo que salió para que no se repita); a_medias la deja esperando a una persona. Sólo quien opera, y siempre con evidencia de al menos 20 caracteres: qué se miró y qué se vio.

ArgumentoTipoQué es
tarea_id (requerido)stringLa tarea retenida.
resultado (requerido)no_salio · salio · a_mediasQué pasó con lo pedido.
evidencia (requerido)stringQué se miró y qué se vio («revisé enviados y el mail no está»). Al menos 20 caracteres.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

aprobar

alcance: escritura

NO aprueba: la IA no se aprueba a sí misma. Devuelve un enlace al portal que la persona de este token abre con SU sesión, donde ve qué se aprueba (qué hace, con qué, costo, verificación) y decide. Sirve una vez y vence a los 15 minutos. Pasale el enlace tal cual y decile que la decisión es suya. Para una tarea que espera aprobación (tarea_id, de aprobaciones_pendientes) o una promoción a producción pendiente (promocion_id, de listar_promociones). Rigen las reglas del portal: aprueban un técnico o un admin, y una promoción la aprueba otra persona que la que la pidió. Varias de una vez: tarea_ids (hasta 50) con tareas que son trámite (tramite: true en aprobaciones_pendientes: verificadas en limpio, sin discrepancia y sin nada que salga al mundo). Devuelve UN enlace a Aprobaciones con el lote preseleccionado, que la persona aprueba con su sesión y un botón; lo que no es trámite vuelve en rechazadas_del_lote con su motivo y se aprueba de a una, desde la tarea. Tampoco acá aprobás vos.

ArgumentoTipoQué es
tarea_idstringLa tarea, de aprobaciones_pendientes.
promocion_idstringO la promoción, de listar_promociones.
tarea_idslistaO varias tareas de aprobaciones_pendientes que sean trámite (tramite: true), hasta 50: un solo enlace para que la persona apruebe el lote. No va con tarea_id ni con promocion_id.
notastringOpcional: qué se miró, para que la persona lo lea en el enlace (sólo de a una).
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

rechazar

alcance: escritura · idempotente

Rechaza una tarea que espera aprobación (tarea_id) o una promoción pendiente (promocion_id; si la pediste vos, queda cancelada). Rechazar no ejecuta nada afuera, por eso no pide enlace. El motivo es obligatorio: lo lee quien la pidió y queda en la auditoría.

ArgumentoTipoQué es
tarea_idstringLa tarea, de aprobaciones_pendientes.
promocion_idstringO la promoción, de listar_promociones.
motivo (requerido)stringPor qué no sale.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

hallazgos

alcance: lectura · sólo lee · idempotente

Las fallas que se repiten en la organización, agrupadas y con su causa probable: pedidos a la API o al MCP que fallan igual, herramientas que el sistema del cliente rechaza (un 401 que vuelve), casos de evaluación que no pasan, discrepancias de la verificación, webhooks que no entregan y llaves rechazadas. Es la respuesta a «¿qué está fallando?». Cada hallazgo trae cuántas veces pasó, el último motivo y dónde se arregla. Lo ven quienes operan la organización.

ArgumentoTipoQué es
diasnumberVentana en días, hasta 30. Por defecto 7.

que_paso_en_la_tarea

alcance: lectura · sólo lee · idempotente

Una tarea contada entera: en qué estado está, qué versión del agente la corrió, qué dijo el agente de su propio trabajo, qué midió el verificador aparte, si hay discrepancia, a quién está esperando y qué herramientas llegó a usar. Lo que el agente declara NO es el veredicto: viene marcado como claim.

ArgumentoTipoQué es
tarea_id (requerido)stringEl id de la tarea, de tareas_del_agente.

traza_de_la_tarea

alcance: lectura · sólo lee · idempotente

Los pasos de la ejecución en orden, con lo que tardó y lo que costó cada tramo del modelo. Es con lo que se contesta en qué tramo se fue el tiempo o la plata, y dónde se frenó.

ArgumentoTipoQué es
tarea_id (requerido)stringEl id de la tarea.
limitenumberCuántos pasos como máximo. Máximo 30.

herramientas_de_la_tarea

alcance: lectura · sólo lee · idempotente

Qué quiso hacer el agente y qué lo dejaron hacer: cada intento de herramienta con su estado, incluidos los que la correa DENEGÓ y los que quedaron esperando una aprobación. Además dice si la cadena de la bitácora sigue sellada.

ArgumentoTipoQué es
tarea_id (requerido)stringEl id de la tarea.

Conexiones y credenciales

Herramientas, funciones propias, servidores MCP ajenos, aplicaciones conectadas (Che Tienda), credenciales, simulaciones y el modelo. Área de búsqueda: conexiones.

crear_funcion

alcance: escritura · idempotente

Guarda una función propia: el cuerpo de una función JavaScript asíncrona que recibe entrada (los argumentos que manda el agente) y devuelve algo que se pueda pasar a JSON. Es una herramienta más —se habilita por agente con editar_agente—, para lo que el catálogo no cubre y el modelo no tiene que hacer a ojo: un cálculo con las reglas del negocio, un formato, una validación. Corre en el worker, en un contenedor SIN RED, sin credenciales, con 128 MB y 5 segundos: no puede llamar a ningún sistema ni tener efecto, así que es de lectura y no pide aprobación. Para hablar con un sistema, una conexión; para la cuenta, una función. Si ya existe una función con ese nombre, la reescribe. Ejemplo de codigo: const neto = entrada.items.reduce((s, i) => s + i.cantidad * i.precio, 0); return { neto, iva: Math.round(neto * 0.21) };

ArgumentoTipoQué es
nombre (requerido)stringEn minúsculas y guión bajo, como una herramienta: calcular_envio.
descripcion (requerido)stringQué hace y qué devuelve: es lo que lee el agente para decidir cuándo llamarla.
parametroslistaLos argumentos que manda el agente, como en crear_herramienta: { nombre, tipo, requerido, descripcion }. Llegan juntos en entrada.
codigo (requerido)stringEl cuerpo de la función: recibe entrada y hace return del resultado. Hasta 20.000 caracteres.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

ver_funcion

alcance: lectura · sólo lee · idempotente

Una función propia con su código, su descripción y sus parámetros, para leerla o editarla con crear_funcion.

ArgumentoTipoQué es
nombre (requerido)stringEl nombre de la función.

crear_herramienta

alcance: escritura · idempotente · toca sistemas ajenos

Declara una conexión HTTP para que los agentes puedan llamar a un sistema del cliente. NACE ACTIVA: queda usable apenas se declara. Redeclarar una que ya existe la actualiza y NO cambia su estado — la que alguien apagó a mano sigue apagada. Si la redeclaración le SACA parámetros o cabeceras a la existente, se rechaza salvo reemplazar: true; para cambiarle una cosa usá editar_herramienta. Para que nazca apagada, pedilo con en_cuarentena: true. La credencial NO se manda acá: se nombra con secreto y se carga aparte, cifrada, desde el portal.

ArgumentoTipoQué es
nombre (requerido)stringCómo la llama el agente. Minúsculas y guiones bajos: es el nombre MCP. Ej: consultar_movimientos.
descripcion (requerido)stringPara qué sirve, dicho PARA EL MODELO: es lo que decide si la usa bien y cuándo.
metodostringGET, POST, PUT, PATCH o DELETE. Por defecto GET.
url (requerido)stringURL completa. Puede llevar {param}, que se reemplaza con los argumentos de la llamada. local://<puerto>/<ruta> apunta al proyecto que corre en la máquina de quien pide la tarea (por yorobot puente): sólo corre en prueba y no lleva secreto.
cabecerasobjectCabeceras fijas. Para autenticar se escribe el MARCADOR del secreto entre llaves, nunca el valor: { "X-Api-Key": "{mi_credencial}" }. El puente lo sustituye afuera de la jaula y el modelo jamás ve la credencial.
parametroslistaQué puede mandar el agente: [{ nombre, tipo, en, requerido, descripcion, esquema }]. tipo: texto (por defecto), numero, booleano, objeto, lista o json. en es dónde viaja el parámetro: "cuerpo" (por defecto), "query" o "ruta" — que sustituye {nombre} en la URL. Se aceptan también "body" y "path". esquema (sólo lista u objeto) es un JSON Schema acotado —type, description, enum, properties, required, items— con la forma de cada elemento: así una lista puede ser de objetos, p. ej. { nombre: "filterGroups", tipo: "lista", esquema: { type: "object", properties: { filters: { type: "array", items: { type: "object", properties: { propertyName: { type: "string" }, operator: { type: "string" }, value: { type: "string" } }, required: ["propertyName", "operator"] } } }, required: ["filters"] } }.
reemplazarbooleantrue para aceptar que esta declaración le saque parámetros o cabeceras a una herramienta que ya existe con ese nombre. Sin esto, un recorte se rechaza y el error dice qué se perdería.
riesgo (requerido)stringread = sólo lee. write = cambia algo reparable. destructive = irreversible, y entonces pide firma humana SIEMPRE. Ante la duda, el más alto.
lectura_por_postbooleantrue para declarar read un POST que sólo consulta: una búsqueda cuyo filtro viaja en el cuerpo (HubSpot search, GraphQL, Elasticsearch) y que no cambia nada afuera. Sin esto, un POST no puede ser read. Sólo POST: un PUT o un DELETE nunca son de lectura.
secretostringNombre (kind) de la credencial del sobre que usa. Vacío si no necesita ninguna.
en_cuarentenabooleantrue para que nazca APAGADA y nadie la pueda usar hasta que una persona la habilite en Conexiones. Por defecto false: nace activa. Pedila en cuarentena cuando la estés declarando a ciegas —una URL que todavía no probaste, un sistema ajeno, un riesgo que no terminás de medir—.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_servidores_mcp

alcance: lectura · sólo lee · idempotente

Los servidores MCP ajenos que la organización conectó: nombre, URL, qué credencial usan, cuándo se descubrieron por última vez y cuántas herramientas trajeron (y cuántas están activas).

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

conectar_servidor_mcp

alcance: escritura · idempotente

Registra un servidor MCP remoto (streamable HTTP) por URL y le pregunta qué herramientas publica. Lo que trae entra según el modo de control (Libre: sólo queda en cuarentena lo que borra, paga o manda en masa; Con controles: lo que escribe; Regulado: todo) y ningún agente lo usa hasta prenderherramienta, de a una; el riesgo lo clasificamos nosotros (un nombre destructivo es destructivo aunque el servidor jure que sólo lee; sin anotaciones es `write`). La credencial NO viaja acá: se carga antes con cargarcredencial bajo un nombre (credencial) y se dice en qué cabecera va (cabecera, p. ej. Authorization con Bearer {secreto}). Volver a llamar con el mismo nombre actualiza la URL y redescubre sin reactivar lo apagado.

ArgumentoTipoQué es
nombre (requerido)stringNombre del servidor en la organización (p. ej. «hubspot»). Único; repetirlo actualiza.
url (requerido)stringLa URL del endpoint MCP (https://…/mcp).
credencialstringOpcional: el nombre de la credencial cargada con cargar_credencial que este servidor usa.
cabecerastringOpcional: la cabecera donde va la credencial. Por defecto Authorization.
formatostringOpcional: cómo se escribe la cabecera; {secreto} se reemplaza en el puente. Por defecto Bearer {secreto}.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

conectar_base

alcance: escritura · idempotente · toca sistemas ajenos

Conecta la base de datos o la API del proyecto del cliente para que los agentes la lean y la usen: tipo supabase (PostgREST), openapi (un documento OpenAPI 3) o mcp (un servidor MCP). Dos pasos, porque qué entra y con qué riesgo lo decide la persona, no vos: 1) modo: previsualizar lee el documento y devuelve las operaciones propuestas (nombre, método, descripción, riesgo sugerido). No guarda nada. Mostrásela a la persona. 2) modo: confirmar con las operaciones que eligió y su riesgo (read sólo lee; write escribe y pide aprobación según los permisos del agente; destructive no se deshace y pide aprobación siempre), la credencial (se guarda sellada y nunca vuelve) y, si querés, agentes donde habilitarlas (cada uno queda con versión nueva en prueba). Prueba una lectura y devuelve el dato. mcp: lo que trae entra según el modo de control (en Regulado, todo en cuarentena), no hay operaciones que elegir. Guía para la base (regla 7): exponé VISTAS pensadas para el agente —etiquetas y no códigos, números ya calculados, fechas con zona horaria—; escribí sólo por funciones (rpc), donde viven las reglas; usá un rol de la base con permisos mínimos y un JWT de ese rol. Nunca la servicerole ni una sbsecret: se rechazan. La llave secreta de Supabase va sólo en `llavedelectura`, para leer el esquema, y no se guarda. Las llaves: la persona puede dártelas y las mandás en `llavedelectura` y `credencial`; o, si prefiere que no pasen por vos, llamá con `cargarenelportal: true (mismo modo, sin llaves) y devuelve un enlace para ella: las pega en el portal, elige y confirma ahí. Preguntale cuál prefiere antes de pedirle una llave. El proyecto tiene que ser alcanzable desde internet por https: YoRobot corre en la nube y no llega a tu localhost ni a una red privada. Para desarrollo hay puente local: herramientas con URL local://<puerto>/<ruta> (crear_herramienta) y yorobot puente --puerto <puerto>` en tu máquina; sólo en prueba.

ArgumentoTipoQué es
modo (requerido)previsualizar · confirmarPrimero previsualizar; confirmar con lo que eligió la persona.
tipo (requerido)supabase · openapi · mcpQué se conecta.
nombre (requerido)stringCómo se llama la conexión (p. ej. «Reservas»). Es el prefijo de las herramientas.
url (requerido)stringsupabase: la del proyecto (https://<ref>.supabase.co); openapi: la del documento; mcp: la del endpoint.
llave_de_lecturastringsupabase: la llave secreta, SÓLO para leer el esquema; no se guarda. openapi: si el documento pide una.
llave_publicastringsupabase, opcional: la publicable (sbpublishable… o anon), que va en apikey.
credencialstringconfirmar: con qué se autentican las herramientas (supabase: el JWT del rol mínimo). Sellada; no vuelve.
cabecerastringmcp, opcional: en qué cabecera va la credencial. Por defecto Authorization: Bearer.
operacioneslistaconfirmar: las elegidas, por id o nombre de la previsualización, con su riesgo.
agenteslistaconfirmar, opcional: agente_id donde habilitarlas.
probarbooleanconfirmar: false para no probar una lectura al terminar.
cargar_en_el_portalbooleantrue: no conecta todavía; devuelve un enlace para que la persona pegue las llaves en el portal y confirme ahí, sin que pasen por vos. Mandá lo demás igual (tipo, nombre, url, y en confirmar las operaciones y los agentes); llaves no.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

conectar_aplicacion

alcance: escritura · toca sistemas ajenos

Conecta una aplicación conocida con esta organización sin que nadie copie un token: YoRobot crea un token nuevo a nombre de la persona (alcances lectura y topes, sin vencimiento), se lo entrega a la app de servidor a servidor y firmado, y la app devuelve su credencial, que queda sellada; sus lecturas (GET) quedan como conexiones activas, de sólo lectura. Hoy: aplicacion: "che-tienda". Si la persona dice «conectá mi tienda de Che Tienda con YoRobot», llamá esta herramienta. NUNCA le pidas un token ni una llave en el chat, y nunca muestres uno: no hacen falta y la respuesta no los trae. Respuesta: conectada (booleano), estado, mensaje (pasáselo a la persona tal cual) y que_hacer si no conectó. Si estado es varias_tiendas, preguntale cuál de tiendas es y volvé a llamar con tienda. Si no conectó, el token del intento ya quedó revocado: reintentar es un vínculo nuevo. Un vínculo nuevo reemplaza al anterior de la misma aplicación. Lo hace un técnico o un admin.

ArgumentoTipoQué es
aplicacion (requerido)che-tiendaQué aplicación: che-tienda.
tiendastringOpcional: cuál tienda, si la persona administra varias (el nombre, el dominio o el subdominio). Sólo si la app contestó varias_tiendas.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_aplicaciones_conectadas

alcance: lectura · sólo lee · idempotente

Las aplicaciones conectadas con vínculo (Che Tienda): por cada una, la tienda, quién la conectó y cuándo (conectada_el, ISO en UTC), los últimos 4 caracteres de su token (token_termina_en; el token nunca), si el token sigue vigente (token_vigente: false = alguien lo revocó en Accesos y la app ya no entra) y las conexiones que creó. El vinculo_id es el que pide desconectar_aplicacion.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

desconectar_aplicacion

alcance: escritura · destructiva · idempotente · toca sistemas ajenos

Da de baja un vínculo: revoca su token, borra la credencial sellada y las conexiones que creó, y le avisa a la app con una entrega firmada (la_app_confirmo dice si contestó). No se deshace: para volver a conectar, conectar_aplicacion crea un vínculo nuevo. Lo hace un técnico o un admin.

ArgumentoTipoQué es
vinculo_id (requerido)stringEl vinculo_id de listaraplicacionesconectadas.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

probar_conexion

alcance: escritura · idempotente · toca sistemas ajenos

Llama UNA herramienta de lectura contra el sistema real y devuelve lo que contestó, recortado a 600 caracteres (recortada dice si se cortó). Sólo lecturas: probar una que escribe sería ejecutarla sin tarea ni aprobación. Con credencial sellada, este servidor sólo la prueba donde puede abrirla; si no, lo dice (probada: false) y la prueba es la de conectar_base al confirmar o probar_agente. Una local:// se prueba contra TU máquina por tu puente local (yorobot puente --puerto <n>): sin puente, probada: false con el comando.

ArgumentoTipoQué es
herramienta (requerido)stringEl nombre o el id, de listar_herramientas o de conectar_base.
argumentosobjectLos argumentos de la lectura (p. ej. { "limit": "3" }). Vacío si no lleva.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

redescubrir_servidor_mcp

alcance: escritura · idempotente

Relee el catálogo de un servidor MCP ya conectado. Las herramientas nuevas entran según el modo de control (en Regulado, en cuarentena), las que ya estaban conservan su estado (redescubrir no reactiva lo que alguien apagó) y las que el servidor dejó de publicar pasan a cuarentena con motivo, sin borrarse.

ArgumentoTipoQué es
servidor_id (requerido)stringEl servidor, de listarservidoresmcp.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

estado_descubrimiento_mcp

alcance: lectura · sólo lee · idempotente

Cuando el servidor usa una credencial, el catálogo lo trae el worker de la organización (el portal no abre credenciales ni sale a la red del cliente) y conectar/redescubrir devuelven estado: pendiente con un encargo_id. Esto dice si el encargo sigue pendiente, terminó (listo, con cuántas herramientas trajo) o falló (con el motivo, sin la credencial).

ArgumentoTipoQué es
servidor_idstringEl servidor, de listarservidoresmcp: se mira su último descubrimiento.
encargo_idstringO el encargo puntual que devolvió conectar/redescubrir.

autorizar_servidor_mcp

alcance: escritura · idempotente

Para servidores MCP que exigen OAuth 2.1 (Slack oficial, Atlassian, Linear…) en vez de un token estático. Descubre al autorizador desde la URL del servidor (RFC 9728 → RFC 8414/OpenID), registra un cliente por Dynamic Client Registration si el autorizador lo ofrece (o usa client_id/client_secret si los pasás), y devuelve la URL que UNA PERSONA tiene que abrir en el navegador, logueada en el portal, para dar el permiso. PKCE S256 y state de un solo uso, vence a los 10 minutos. Al volver, la llave (access + refresh) queda sellada en la bóveda para el worker —el portal no la ve, y esta respuesta tampoco— y el servidor pasa a usarla en Authorization. Después: redescubrirservidormcp.

ArgumentoTipoQué es
servidor_id (requerido)stringEl servidor, de listarservidoresmcp (conectado sin credencial).
scopestringOpcional: los permisos a pedir, separados por espacio. Por defecto los que anuncia el autorizador.
client_idstringOpcional: si el autorizador no registra clientes solo, el client_id de una app ya creada.
client_secretstringOpcional, junto con client_id: el secreto de esa app. Se sella; no se devuelve ni se registra.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

estado_oauth_mcp

alcance: lectura · sólo lee · idempotente

Dice si la autorización de un servidor está pendiente (falta que la persona abra la URL), autorizada (con cuándo vence el token y cuándo se renovó por última vez) o falló (con el motivo). Nunca devuelve tokens.

ArgumentoTipoQué es
servidor_id (requerido)stringEl servidor, de listarservidoresmcp.

desconectar_servidor_mcp

alcance: escritura · idempotente

Borra el servidor y con él todas las herramientas que trajo: los agentes que las tenían puestas se quedan sin ellas. Sólo un admin. Devuelve cuántas herramientas se fueron.

ArgumentoTipoQué es
servidor_id (requerido)stringEl servidor, de listarservidoresmcp.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_herramientas

alcance: lectura · sólo lee · idempotente

Las conexiones que existen en el tenant, con su nombre, qué hace cada una, su riesgo, si está usable y qué credencial necesita. LLAMALA ANTES DE crear_agente o editar_agente: esos dos reciben los nombres y rechazan el que no existe, así que adivinar un nombre es una llamada perdida. También dice cuáles están apagadas o en cuarentena, y cuáles no tienen la credencial cargada todavía: una herramienta habilitada sin credencial razona pero no toca nada real. Con detalle: true agrega además la URL y los PARÁMETROS de cada una: LLAMALA ASÍ ANTES DE REDECLARAR con crear_herramienta, que reescribe la definición entera — todo parámetro que no vuelvas a mandar desaparece, y el agente pierde la mitad de la herramienta sin que nada falle hasta la próxima corrida.

ArgumentoTipoQué es
detallebooleantrue para incluir url, cabeceras y parámetros de cada conexión. Las cabeceras salen con el MARCADOR del secreto ({mi_credencial}), nunca con su valor.
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

habilitar_herramienta

alcance: escritura · idempotente

Saca una conexión de cuarentena para toda la organización (la que nació apagada con en_cuarentena, la que trajo un servidor MCP, o la que alguien apagó a mano). Es una decisión de gobierno: la toma un técnico o un admin. No se la da a ningún agente: para eso está prender_herramienta. La que ya estaba activa queda igual.

ArgumentoTipoQué es
herramienta (requerido)stringEl nombre de la conexión (de listar_herramientas) o su id.
motivostringOpcional: por qué se habilita. Queda en la bitácora junto al motivo de la cuarentena.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

elegir_modelo

alcance: escritura · idempotente

Qué modelo usa cada rol, y con qué modelo trabaja cada uno. Sin rol sólo informa; con rol y modelo lo cambia. El trabajo no es homogéneo: el ejecutor es el que se lleva el grueso de los tokens —ahí se decide casi todo el costo—, mientras que revisor y juez leen poco y rinden con un modelo chico. Un modelo vacío borra el override y ese rol vuelve al modelo de base. NO toca la credencial del proveedor: elegir el modelo y entregar la llave para pagarlo son dos decisiones distintas, y la segunda sigue siendo de un admin en Ajustes → Llave.

ArgumentoTipoQué es
rolstringorquestador (planifica y decide), ejecutor (hace el trabajo: acá se va el grueso del gasto), revisor (lee poco), encargado (relee el sistema y verifica), juez (califica). Sin esto, sólo informa.
modelostringEl identificador tal cual lo pide el proveedor: claude-sonnet-5 en la API de Anthropic, anthropic/claude-sonnet-5 en un gateway, un inference profile en Bedrock. Vacío borra el override y vuelve al modelo de base.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

prender_herramienta

alcance: escritura · idempotente

Habilita una herramienta de la organización para un agente. Le da CON QUÉ, no permiso: la correa, el tope sin firma y la aprobación de las irreversibles siguen iguales. Si la herramienta está apagada globalmente o en cuarentena, queda asignada pero no corre hasta que eso se levante.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_agentes.
herramienta_id (requerido)stringEl id de la herramienta, de listar_herramientas.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

apagar_herramienta

alcance: escritura · idempotente

Le saca una herramienta a un agente. La herramienta sigue en la organización y en los otros agentes.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_agentes.
herramienta_id (requerido)stringEl id de la herramienta, de listar_herramientas.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

cargar_credencial

alcance: escritura · idempotente

Guarda, cifrada, la credencial que las conexiones citan por secreto (el kind): un private app token de HubSpot, la API key de un ERP. Se sella con la llave pública de la bóveda y no se vuelve a mostrar nunca — la respuesta trae los últimos cuatro caracteres y qué conexiones la usan. Cargarla de nuevo la reemplaza. La llave del proveedor de modelos no entra por acá: es de un admin, en Ajustes → Llave.

ArgumentoTipoQué es
nombre (requerido)stringEl kind con el que las conexiones la citan: minúsculas y guiones bajos, p. ej. hubspottoken. Tiene que ser el mismo que puso `crearherramienta en secreto`.
valor (requerido)stringLa credencial en claro. Viaja una vez, se sella y no vuelve a salir.
ambientestringprod (por defecto), staging o dev: para qué ambiente vale esta llave.
forzarbooleantrue para guardar una credencial que NINGUNA conexión cita todavía. Sin esto, un nombre huérfano se rechaza y el error dice qué nombres sí están esperando llave: un nombre mal tipeado guardaba una credencial que nadie buscaba y el 401 aparecía en la primera tarea.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

editar_herramienta

alcance: escritura · idempotente

Cambia UNA O VARIAS cosas de una conexión ya declarada sin reescribirla: descripción, método, URL, cabeceras, parámetros, riesgo o el nombre de la credencial (secreto). Lo que no se manda no se toca. Bajar el riesgo (destructive → write → read) lo hace un técnico o un admin. Si parametros o cabeceras le sacan algo a lo que hay, se rechaza salvo reemplazar: true. Las herramientas que trae un servidor MCP ajeno sólo aceptan descripción, riesgo y secreto.

ArgumentoTipoQué es
nombre (requerido)stringEl nombre MCP de la herramienta a editar (el de listar_herramientas).
descripcionstringNueva descripción para el modelo.
metodostringGET, POST, PUT, PATCH o DELETE.
urlstringNueva URL completa; puede llevar {param}.
cabecerasobjectCabeceras completas (reemplaza el mapa). Las sensibles citan el secreto entre llaves, nunca el valor.
parametroslistaLista completa de parámetros, con el mismo formato que crear_herramienta.
riesgostringread, write o destructive.
secretostringNombre de la credencial que usa. Cadena vacía para que no use ninguna.
reemplazarbooleantrue para aceptar que parametros/cabeceras le saquen algo a lo que hay.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

simular_herramienta

alcance: escritura · idempotente

Graba la respuesta que una conexión devuelve en dev o staging. Mientras está simulada, el agente la ve y la llama, pero el puente devuelve la respuesta grabada y anota «simulado»: el sistema real no se llama y no viaja ninguna credencial. Producción no se simula nunca. Para volver a la conexión real, quitar_simulacion.

ArgumentoTipoQué es
herramienta_id (requerido)stringLa conexión, de listar_herramientas.
ambiente (requerido)dev · stagingDónde vale la simulación.
respuesta (requerido)stringLo que el agente va a recibir cuando la llame, tal cual (texto o JSON como texto). Máximo 20.000 caracteres.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

quitar_simulacion

alcance: escritura · idempotente

La conexión vuelve a llamar al sistema de ese ambiente: la dirección propia del ambiente si la tenía, o nada (una escritura externa sin conexión propia no entra a la corrida).

ArgumentoTipoQué es
herramienta_id (requerido)stringLa conexión, de listar_herramientas.
ambiente (requerido)dev · stagingDe qué ambiente sacarla.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

pedir_conexion

alcance: escritura · idempotente

Deja un pedido: «necesito esta conexión en este ambiente y no tengo la credencial». Le llega a quien puede cargarla (técnico, admin, operador) con link a Conexiones; al guardar la credencial el pedido se cierra solo. Quien pide no ve ni recibe el secreto. Un segundo pedido para la misma conexión y ambiente devuelve el que ya estaba pendiente.

ArgumentoTipoQué es
herramienta_id (requerido)stringLa conexión, de listar_herramientas.
ambiente (requerido)dev · staging · prodPara qué ambiente falta.
motivo (requerido)stringPara qué la necesitás; lo lee quien la carga.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

alcance: escritura

Genera un link de un solo uso para que la persona que tiene la llave (el cliente, su equipo de sistemas) la pegue ella en una página de YoRobot, en vez de mandarla por chat o por correo: queda sellada y nadie la vuelve a ver. Sólo para una credencial que alguna conexión cita. Si ya hay una cargada con ese nombre en ese ambiente, el link no la pisa salvo reemplaza: true. Vence (por defecto a las 72 horas) y quien lo generó recibe un correo con los últimos cuatro cuando se usa. Mostrale el link a la persona tal cual: se devuelve una sola vez. NUNCA pidas ni pases la credencial por acá.

ArgumentoTipoQué es
credencial (requerido)stringEl nombre de la credencial que cita la conexión (erp_token, hubspot_token…).
ambientedev · staging · prodPara qué ambiente. Por defecto prod.
parastringA quién se lo mandás, en palabras: sale en el aviso y en la bitácora.
horasnumberEn cuántas horas vence, de 1 a 168. Por defecto 72.
reemplazabooleantrue para que pise una credencial ya cargada con ese nombre en ese ambiente.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_pedidos_de_conexion

alcance: lectura · sólo lee · idempotente

Qué credenciales están pedidas, por quién, para qué ambiente y en qué estado. Un desarrollador ve los suyos; técnico, admin, operador y auditor ven todos. Nunca trae el valor de una credencial.

ArgumentoTipoQué es
estadopendiente · cumplido · rechazado · todosPor defecto pendiente.
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

rechazar_pedido_de_conexion

alcance: escritura · idempotente

Cierra un pedido pendiente sin cargar la credencial, con motivo. Lo hace un técnico, un admin o un operador. Un pedido se cumple cargando la credencial (cargar_credencial o Conexiones), no con esta herramienta.

ArgumentoTipoQué es
pedido_id (requerido)stringEl pedido, de listar_pedidos_de_conexion.
motivo (requerido)stringPor qué no; lo lee quien pidió.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

Canales y avisos

Por dónde entra la gente (chat, WhatsApp, Slack…) y a quién se le avisa. Área de búsqueda: canales.

listar_canales

alcance: lectura · sólo lee · idempotente

Por dónde le hablan a un agente: chat público/widget, WhatsApp, Instagram, Slack y Telegram, con nombre, ambiente, dominios permitidos, si está atendiendo, último uso y el link (sin token: el token se muestra UNA vez al abrir).

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_agentes.
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

abrir_canal

alcance: escritura

Abre un canal de chat para un agente y devuelve UNA sola vez el link completo con el token y el <script> para embeber el widget en la web del cliente: guardalos, no se vuelven a mostrar. Lo que entra por ahí es de un tercero: la tarea nace contenida y la cuota es del canal. Con dominios el widget puede hablar desde esas webs (CORS); sin dominios sólo funciona nuestra página /charla. Mandá clave_de_pedido: un reintento sin clave abre un segundo canal. Slack y Telegram van por conectar_canal; WhatsApp e Instagram, por conectar_whatsapp y conectar_instagram.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_agentes.
ambientestringdev (por defecto), staging o prod: qué versión del agente atiende ese canal.
nombrestringCómo lo llama la organización: «Chat de la web», «Soporte». Opcional.
dominioslistaOrígenes desde los que el widget puede hablar: https://www.clinica.com. Hasta 20. Sin esto el canal sólo atiende desde nuestra página.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

conectar_canal

alcance: escritura

Conecta un bot de Slack o un bot de Telegram a un agente, y devuelve la URL del webhook que hay que pegar del otro lado. Los secretos se guardan sellados y no se vuelven a mostrar. Slack: token = Bot User OAuth Token (xoxb-…), secreto = Signing Secret; suscribí message.im y app_mention en Event Subscriptions con la URL devuelta. Telegram: token = el del bot de @BotFather; la respuesta trae secreto_webhook para registrar con setWebhook (secret_token). WhatsApp e Instagram NO van por acá: conectar_whatsapp y conectar_instagram. Mandá clave_de_pedido.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_agentes.
tipo (requerido)stringslack o telegram.
token (requerido)stringCon qué sale la respuesta: el bot token.
secretostringSólo Slack: el Signing Secret, con que se comprueba el webhook. Telegram no lo lleva: lo generamos.
nombrestringCómo lo llama la organización. Opcional.
ambientestringdev (por defecto), staging o prod.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

conectar_whatsapp

alcance: escritura

Conecta a un agente el WhatsApp Business que la organización ya usa; el número sigue andando en la app del celular. Devuelve un enlace a la pantalla de YoRobot y los pasos para la persona, que hay que pasarle tal cual y en orden: hoy el número se conecta en una cuenta propia de la organización en el servicio de WhatsApp que nombran los pasos (gratis para un número), y la llave de esa cuenta la pega la persona en la pantalla de YoRobot. Esa llave no pasa por acá: no la pidas. Cuando la persona termina, el canal aparece prendido en listar_canales con su número. Si la respuesta trae canal_id (el alta directa con Meta, cuando esté habilitada), consultalo con estado_de_conexion. Los cargos de los mensajes los cobra Meta a la cuenta de la organización. Mandá clave_de_pedido.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente que va a contestar, de listar_agentes.
ambientestringprod (por defecto: es el número de los clientes de verdad, y contesta la versión publicada), staging o dev.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

conectar_instagram

alcance: escritura

Conecta a un agente los mensajes directos de la cuenta de Instagram de la organización (profesional: empresa o creador). Devuelve un enlace a YoRobot: la persona lo abre con su sesión, entra con su Instagram y autoriza los mensajes. La contraseña no pasa por acá. Cuando la persona termina, el canal queda prendido solo: consultalo con estado_de_conexion { canalid }. El agente contesta dentro de las 24 h del último mensaje de la persona, como pide Instagram. Mandá `clavede_pedido`.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente que va a contestar, de listar_agentes.
ambientestringprod (por defecto: es la cuenta de los clientes de verdad, y contesta la versión publicada), staging o dev.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

estado_de_conexion

alcance: lectura · sólo lee · idempotente

El estado de un alta de conectar_whatsapp o conectar_instagram, en una palabra y qué hacer: esperando_alta (la persona todavía no terminó), conectado (el agente ya contesta), fallida, vencida o reemplazada. Con la cuenta, el agente y conectado como booleano. No cambia nada.

ArgumentoTipoQué es
canal_id (requerido)stringEl canal_id que devolvió conectar_whatsapp o conectar_instagram.

configurar_canal

alcance: escritura · idempotente

Cambia el nombre de un canal y, si es de chat, los dominios desde los que el widget puede hablar. Lo que no mandás no cambia. Los secretos no se editan: se reconecta.

ArgumentoTipoQué es
canal_id (requerido)stringEl id del canal, de listar_canales.
nombrestringEl nombre nuevo, o vacío para sacarlo.
dominioslistaLa lista completa de orígenes permitidos (reemplaza la anterior). Sólo canales de chat.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

probar_canal

alcance: escritura

Crea una tarea por ese canal como si alguien hubiera escrito, con la misma contención, cuota y ambiente. Devuelve el id de la tarea para leer la respuesta con ver_tarea. No manda nada al proveedor: es para comprobar que el agente atiende.

ArgumentoTipoQué es
canal_id (requerido)stringEl id del canal, de listar_canales.
mensajestringQué decirle. Por defecto le pide que se presente.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

prender_canal

alcance: escritura · idempotente

Prende un canal apagado: vuelve a responder. Idempotente.

ArgumentoTipoQué es
canal_id (requerido)stringEl id del canal, de listar_canales o abrir_canal.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

apagar_canal

alcance: escritura · idempotente

Apaga un canal: el link o el número dejan de responder, pero nada se borra y se vuelve a prender con prender_canal. Es el freno de mano cuando un agente dice algo que no debía.

ArgumentoTipoQué es
canal_id (requerido)stringEl id del canal, de listar_canales.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_conversaciones

alcance: lectura · sólo lee · idempotente

Las sesiones de conversación por canal e interlocutor (una por link de chat, por teléfono en WhatsApp, por hilo en Slack/Telegram): agente, canal, estado (abierta o cerrada y por qué), turnos, último mensaje y el resumen que el agente dejó. Sin el teléfono ni el id del interlocutor. Una sesión se cierra sola tras 6 horas sin mensajes.

ArgumentoTipoQué es
agente_idstringSólo las de este agente. Opcional.
canal_idstringSólo las de este canal, de listar_canales. Opcional.
estadostringabierta o cerrada. Sin esto, todas.
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

ver_conversacion

alcance: lectura · sólo lee · idempotente

Una sesión con lo que la persona escribió en cada turno, lo que la corrida contestó de verdad (leído de la ejecución, no del relato), la tarea de cada turno para abrirla con ver_tarea, y el resumen y los datos de trabajo que el agente dejó para el turno siguiente.

ArgumentoTipoQué es
conversacion_id (requerido)stringEl id, de listar_conversaciones.

cerrar_conversacion

alcance: escritura · idempotente

Cierra una sesión abierta: el próximo mensaje de ese interlocutor abre una nueva sin este contexto. No borra nada: las tareas y los turnos quedan. Idempotente.

ArgumentoTipoQué es
conversacion_id (requerido)stringEl id, de listar_conversaciones.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_destinatarios

alcance: lectura · sólo lee · idempotente

Las personas y canales de equipo que reciben avisos (correo, WhatsApp, Slack, Teams) cuando una tarea espera aprobación, termina o la verificación discrepa. Con cuántos avisos llegaron, fallaron o esperan. Sin direcciones completas ni URLs de webhooks.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

avisar_a

alcance: escritura

Da de alta a quién avisar: tipo es email, whatsapp, slack o teams. Por defecto recibe tarea.necesita_firma: el aviso lleva la tarea, lo que el agente quiere hacer y el link a la cola. El link ABRE la cola; aprobar pide sesión. Para slack, direccion es la URL del incoming webhook; para teams, la del webhook de Workflows del canal («Post to a channel when a webhook request is received»). Las dos se sellan y no se vuelven a mostrar, y canal es el nombre visible. Para whatsapp, direccion es el número y plantilla la plantilla aprobada por Meta con dos parámetros (título y link). Mandá clave_de_pedido.

ArgumentoTipoQué es
tipo (requerido)stringemail, whatsapp, slack o teams.
nombre (requerido)stringQuién es: «Jefa de guardia», «#aprobaciones».
direccion (requerido)stringCorreo, número de WhatsApp, URL del incoming webhook de Slack o URL del webhook de Workflows de Teams.
eventoslistaQué avisar: tarea.necesita_firma (por defecto), tarea.terminada, discrepancia.detectada, tarea.firmada, tarea.rechazada.
agente_idstringOpcional: sólo lo que le pase a ese agente.
plantillastringSólo WhatsApp: el nombre de la plantilla aprobada.
idiomastringSólo WhatsApp: el idioma de la plantilla, es_AR por defecto.
canalstringSólo Slack y Teams: cómo se llama el canal, para mostrarlo.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

prender_destinatario

alcance: escritura · idempotente

Prende un destinatario apagado. Idempotente.

ArgumentoTipoQué es
destinatario_id (requerido)stringEl id, de listar_destinatarios.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

apagar_destinatario

alcance: escritura · idempotente

Apaga un destinatario sin borrarlo: lo que estaba en cola para esa persona no sale. Idempotente.

ArgumentoTipoQué es
destinatario_id (requerido)stringEl id, de listar_destinatarios.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

borrar_destinatario

alcance: escritura · destructiva · idempotente

Borra a quién avisar, con su historial de entregas. Para una pausa usá apagar_destinatario.

ArgumentoTipoQué es
destinatario_id (requerido)stringEl id, de listar_destinatarios.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

probar_destinatario

alcance: escritura · idempotente

Encola un aviso de prueba con el mismo texto que llega cuando un agente espera aprobación. Uno por minuto por destinatario: apretar dos veces manda uno.

ArgumentoTipoQué es
destinatario_id (requerido)stringEl id, de listar_destinatarios.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

Automatizaciones

Rutinas, disparadores, cajas y workers. Área de búsqueda: automatizaciones.

crear_rutina

alcance: escritura

Crea una automatización: una rutina que le pide una tarea a un agente cada vez que un disparador suena. NACE APAGADA: queda escrita pero no dispara nada hasta que alguien la prenda — una persona en Automatizaciones, o este mismo token con prenderrutina. Los disparadores se agregan aparte con agregardisparador. Con clave, volver a declararla con la misma clave la ACTUALIZA (conservando disparadores y estado) en vez de crear otra.

ArgumentoTipoQué es
nombre (requerido)stringCómo se llama la automatización en la pantalla. Corto y humano.
clavestringClave estable elegida por vos (p. ej. «cierre-diario»), única en la organización. Si ya hay una rutina con esa clave, se actualiza en vez de crear otra; la respuesta dice actualizada: true. Opcional.
agente_idstringEl agente que atiende cada disparo: el id que devolvió crearagente o listaragentes. Uno de los dos: agente_id o equipo.
equipostringLa clave o el id de un equipo (de listar_equipos), en vez de un agente. Cada disparo va al líder de ESE momento —si el equipo cambia de líder, la rutina lo sigue— y la tarea nace con el presupuesto de árbol del equipo, que es el techo de todo lo que reparta.
titulo (requerido)stringEl título de la tarea que crea cada disparo. Fijo: el payload del disparo viaja aparte, como entrada de la tarea.
descripcionstringQué tiene que hacer la tarea, si el título solo no alcanza. Opcional.
entradaobjectDatos fijos que acompañan cada disparo. El payload del webhook se suma solo: esto es para lo que no cambia.
concurrenciastringQué pasa cuando un disparo llega y la corrida anterior sigue viva (y «viva» incluye la que espera una firma). «coalesceifactive» (por defecto): el disparo se absorbe — bien para trabajo que no conviene apilar. «skipifactive»: se saltea y queda registrado. «always_enqueue»: corre SIEMPRE — es la política para vigilancia periódica, donde una medición esperando firma no puede callar al vigía; las firmas se juntan en Aprobaciones y el vigilante las recuerda, pero nada se frena.
cajastringCon qué caja de herramientas corre cada tarea de la rutina: el id o el nombre exacto de una caja de listar_cajas. Sin declararla corre con la caja completa del agente. Una caja de otra organización se rechaza. Alias: perfil.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

editar_rutina

alcance: escritura · idempotente

Cambia lo declarado de una automatización existente sin tocar su estado (prendida/apagada) ni sus disparadores: nombre, título de la tarea, descripción, entrada fija, concurrencia, caja de herramientas. Y el cron de UN disparador de reloj, dando disparador_id (de listar_rutinas) junto con cron y opcionalmente zona: un disparador que no sea de reloj, o que no sea de esta rutina, se rechaza. Cada cambio queda en la auditoría.

ArgumentoTipoQué es
rutina_id (requerido)stringEl id que devolvió crearrutina o listarrutinas.
nombrestringNuevo nombre visible. Opcional.
titulostringNuevo título de la tarea que crea cada disparo. Opcional.
descripcionstringNueva descripción. Opcional; vacío la borra.
entradaobjectNueva entrada fija; reemplaza la anterior entera. Opcional.
concurrenciastringcoalesceifactive, skipifactive o always_enqueue. Opcional.
cajastringId o nombre exacto de una caja de listar_cajas; la palabra «completa» vuelve a la caja completa del agente. Opcional. Alias: perfil.
disparador_idstringSólo para cambiar el cron: el id del disparador de reloj, de listar_rutinas.
cronstringSólo con disparador_id: los cinco campos nuevos (min hora día mes díasemana).
zonastringSólo con disparador_id: zona horaria IANA nueva. Opcional; sin ella se conserva la que tiene.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_cajas

alcance: lectura · sólo lee · idempotente

Las cajas de herramientas de la organización (perfiles): id, nombre y qué herramientas incluye cada una. El id o el nombre es lo que crear_rutina/editar_rutina aceptan en caja.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

agregar_disparador

alcance: escritura

Le agrega un disparador a una rutina: «reloj» (cron), «webhook» (otro sistema avisa con un POST firmado), «api» (sólo dispara cuando se lo llama) u «odoo» (el worker mira el Odoo conectado cada cada_min minutos y dispara una tarea por registro de modelo que cambió y cumple dominio, con el registro ya resuelto en la entrada; más de 20 en una vuelta van en UNA tarea). Para un webhook devuelve la URL pública y el secreto de firma UNA SOLA VEZ: guardalos en el momento, porque no se pueden volver a leer.

ArgumentoTipoQué es
rutina_id (requerido)stringEl id que devolvió crearrutina o listarrutinas.
tipo (requerido)stringreloj, webhook, api u odoo.
cronstringSólo para reloj: cinco campos (min hora día mes díasemana), evaluados en zona.
zonastringSólo para reloj: zona horaria IANA. Por defecto UTC.
modostringSólo para webhook: hmacsha256 (por defecto), bearer o hubsha256. HMAC firma ${instante}.${cuerpo}; bearer es un token fijo en Authorization; hub_sha256 es X-Hub-Signature: sha256=<hmac del cuerpo>, el que mandan Jira Cloud y GitHub (pegá el secreto en el campo Secret del webhook de Jira).
ventana_segnumberSólo para webhook: ventana anti-replay en segundos, entre 30 y 3600. Por defecto 300.
modelostringSólo para odoo: el modelo que se mira, p. ej. account.move.
dominiolistaSólo para odoo: tripletas de Odoo; "{{hoy}}" es la fecha del día. Factura vencida: [["movetype","=","outinvoice"],["paymentstate","in",["notpaid","partial"]],["invoicedatedue","<","{{hoy}}"]].
cada_minnumberSólo para odoo: cada cuántos minutos mira, mínimo 5. Por defecto 15.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

prender_rutina

alcance: escritura · idempotente

Prende una automatización: desde ese momento sus disparadores crean tareas de verdad. Pide alcance de escritura. Se revierte con apagar_rutina, y el cambio queda asentado en la auditoría.

ArgumentoTipoQué es
rutina_id (requerido)stringEl id que devolvió crearrutina o listarrutinas.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

apagar_rutina

alcance: escritura · idempotente

Apaga una automatización: sus disparadores dejan de crear tareas (un webhook que llega responde como si la rutina no existiera). No borra nada; se vuelve a prender con prender_rutina.

ArgumentoTipoQué es
rutina_id (requerido)stringEl id que devolvió crearrutina o listarrutinas.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

borrar_rutina

alcance: escritura · destructiva · idempotente

Borra una automatización con sus disparadores (un webhook borrado deja de responder). Las tareas que ya creó no se tocan. No hay papelera: para frenarla sin perderla, apagar_rutina. Queda asentado en la auditoría.

ArgumentoTipoQué es
rutina_id (requerido)stringEl id que devolvió crearrutina o listarrutinas.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_workers

alcance: lectura · sólo lee · idempotente

Los workers de la organización y lo que cada uno contó de sí al reclamar: si está vivo (reclamó en el último minuto), qué huellas de bóveda puede abrir (huellas), qué versión corre, qué modelo usa por rol, contra qué portal habla, cuántos carriles, si corre con entorno aislado y qué sabe hacer su puente (capacidades: sin efectos_aprobados no ejecuta lo aprobado, sin composio no corre acciones de Composio). misma_version_que_el_portal: false quiere decir «corrés X, main es Y». version_deseada es la que el portal le pidió correr (desplegarworkers) y `actualizacionpendiente: true que todavía no la corre; actualizacionfallida` trae versión y motivo si la máquina tuvo que volver atrás. Un worker sin `sepresento` es anterior a esta versión: redesplegalo. Nada de acá es secreto.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

desplegar_workers

alcance: escritura · idempotente

Le pide a los workers de la organización que pasen a correr una versión del código (sha de git). Sin version, la del portal (version_del_portal en listarworkers): es «poné a los workers al día con main». Nadie entra a la máquina: el worker recibe el pedido en su próximo reclamo, termina la tarea que tenga en curso, y un proceso local trae el código y lo reinicia; si la versión nueva no vuelve a reclamar en cinco minutos, vuelve solo a la anterior y listarworkers muestra actualizacion_fallida con el motivo. Esa versión no se vuelve a pedir sola: llamar de nuevo con la misma es la forma de reintentar. Devuelve qué workers quedaron con el pedido, cuáles ya la corrían y cuáles no están vivos (un worker apagado la va a tomar cuando arranque). Un worker cuya máquina no tiene el actualizador instalado lo dice en su log y sigue reclamando con la versión vieja: salud_de_la_instalacion lo marca a los 10 minutos.

ArgumentoTipoQué es
versionstringEl sha, de 7 a 40 hex. Opcional: sin él, la versión que corre el portal.
worker_idstringSólo este worker (id de listar_workers). Opcional: sin él, todos los de la organización.
notastringPor qué se despliega. Opcional; queda en la actividad.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

salud_de_la_instalacion

alcance: lectura · sólo lee · idempotente

El diagnóstico de la instalación en una llamada, para no tener que abrir la base: variables que le faltan al portal (nombres, nunca valores), con qué huella sella hoy, los workers con lo que declararon, las credenciales selladas y si algún worker vivo puede abrirlas («sellada con A; ningún worker activo tiene A»), el modelo por rol del tenant y la divergencia worker/main. problemas es la lista ya redactada de lo que hay que arreglar, en orden. Si una tarea falla al abrir un sobre o el worker reclama y no pasa nada, empezá por acá.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

listar_rutinas

alcance: lectura · sólo lee · idempotente

Las automatizaciones del tenant: qué agente atiende cada una, con qué disparadores (id, tipo, cron), si están prendidas, y los disparos de la última semana que NO crearon tarea (disparos_sin_tarea_7d) con el último motivo (ultimo_disparo_sin_tarea): p. ej. «rebotado» porque el agente no tiene versión en producción, o «absorbido» detrás de una tarea abierta. absorbidos_7d cuenta sólo los absorbidos, y absorbiendo dice qué tarea viva está tapando la rutina hoy, cuántos disparos seguidos y desde cuándo. Cada rutina y cada disparador vienen además dichos como en la pantalla de Rutinas: cuando (cuándo corre), proxima (la próxima corrida, en la zona de quien pregunta —horas_en_zona—; null si no va a correr sola) y ultima (qué pasó la última vez que disparó: creó una tarea, fue absorbida, salteada o rebotó, y hace cuánto). El cron crudo se queda, para quien edita. Si prendiste una rutina y no pasa nada, la respuesta está acá.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

disparar_rutina

alcance: escritura

Dispara una automatización una vez, ahora, como si hubiera saltado su reloj. Sirve para probarla sin esperar el cron. Encola la tarea igual que un disparo real —cuesta lo mismo— y una rutina apagada no dispara.

ArgumentoTipoQué es
rutina_id (requerido)stringEl id de la rutina, de listar_rutinas.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

Webhooks

Avisos firmados hacia afuera: entregas, reenvío y el aviso de prueba. Área de búsqueda: webhooks.

listar_webhooks

alcance: lectura · sólo lee · idempotente

Los destinos de avisos (webhooks) de la organización, con cuántas entregas salieron, cuántas esperan y cuántas fallaron, y el último error. Para ver entrega por entrega, listarentregasde_webhook.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

listar_entregas_de_webhook

alcance: lectura · sólo lee · idempotente

El registro de entregas de un webhook, de la más nueva a la más vieja (sobre las últimas 100; limite/desde para paginar, busca filtra por evento o sobre): evento, estado (pendiente, entregado, fallado), intentos, status HTTP que contestó el endpoint, error y fechas. prueba: true marca las que salieron de disparareventodeprueba. Con `entregaid` de una fila, verentregade_webhook trae el cuerpo crudo, la firma y el curl.

ArgumentoTipoQué es
webhook_id (requerido)stringEl id del webhook (listar_webhooks).
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

ver_entrega_de_webhook

alcance: lectura · sólo lee · idempotente

Una entrega con el JSON crudo exactamente como viajó (es lo que se firma: no lo reformatees antes de verificar), una firma t=…,v1=… fresca calculada con el secreto real (vale 5 minutos), y el comando curl listo para pegar en una terminal y reproducir el aviso contra tu endpoint —sirve para probar un localhost o un túnel. Exige ser operador: con una firma válida cualquiera falsifica un aviso nuestro contra el endpoint del cliente. El secreto no se muestra nunca.

ArgumentoTipoQué es
entrega_id (requerido)stringEl id de la entrega (listarentregasde_webhook).

reenviar_entrega_de_webhook

alcance: escritura · idempotente

Vuelve a mandar una entrega ahora —fallada, entregada o en cola—, con el mismo sobre para que un receptor idempotente la reconozca como el mismo hecho. Los intentos arrancan de cero. Devuelve el status que contestó el endpoint y el estado en que quedó (entregado, pendiente con reintento programado, fallado). Exige operador.

ArgumentoTipoQué es
entrega_id (requerido)stringEl id de la entrega (listarentregasde_webhook).
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

disparar_evento_de_prueba

alcance: escritura

Manda al webhook un aviso sintético FIRMADO con su secreto real, ahora, y devuelve cómo le fue: status HTTP del endpoint, estado, el cuerpo crudo, la firma y el curl para repetirlo. Es la forma de cerrar el ciclo (recibir → comprobar x-yorobot-signature → contestar 2xx) sin esperar a que una tarea termine. El cuerpo tiene la forma exacta del aviso real de tarea.terminada (tarea, lo que el agente afirmó, veredicto, url) más prueba: true y un id prueba-…; el sobre termina en :prueba. Se manda aunque el webhook no esté suscripto a ese evento (suscripto: false lo dice). Queda en la cola como cualquier entrega. Exige operador.

ArgumentoTipoQué es
webhook_id (requerido)stringEl id del webhook (listar_webhooks).
eventostringQué evento simular. Por defecto tarea.terminada. Cualquiera de los eventos de aviso (ver /docs o listar_webhooks).
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

Datos

Entidades y registros de la organización. Área de búsqueda: datos.

listar_entidades

alcance: lectura · sólo lee · idempotente

Qué objetos del negocio tiene definidos esta organización en Datos (lead, pedido, repartidor…): por cada una sus campos con tipo, cuáles son requeridos, los estados del ciclo de vida en orden (el primero es el inicial), la versión del esquema y cuántos registros tiene. Es lo primero que hay que mirar antes de consultar o guardar registros, y antes de definir una entidad nueva (para no duplicar una que ya existe con otro nombre).

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

definir_entidad

alcance: escritura · idempotente

Crea una entidad de Datos o cambia una que ya existe (misma clave): el CRM, la flota, la cola de triaje arrancan por acá. Si el cuerpo es idéntico al que ya hay no pasa nada; si cambió, se apila una versión y los registros escritos con la anterior siguen leyéndose. Cada campo: { nombre, tipo, requerido?, descripcion? } más lo del tipo. Tipos: texto · numero · booleano · fecha (ISO) · opcion (con opciones: 2 a 30) · referencia (con entidad: la clave de otra entidad, que tiene que existir; el valor es la clave natural de un registro de ella) · dinero (con moneda ISO 4217; el valor es un número) · geo (el valor es { lat, lng }) · persona (el valor es el correo o el id de alguien del equipo; se guarda el id) · telefono (E.164) · email (se guarda en minúsculas) · url (una dirección web; «acme.com» se guarda como https://acme.com). Nombres de campo y estados: minúsculas, números y guión bajo. id, clave, estado y entidad están reservados. Los estados son opcionales (una entidad de consulta no tiene ciclo); si hay, el orden ES la declaración. Al definirla, el agente recibe solo las herramientas leer_registros, guardar_registro y mover_estado sobre ella (si el tenant no las tenía). Definir una entidad no otorga permisos a nadie.

ArgumentoTipoQué es
clave (requerido)stringLa clave de la entidad («lead», «repartidor»). Minúsculas, números y guión bajo.
nombrestringCómo se lee en la pantalla («Lead», «Repartidor»). Si falta, se usa la clave.
campos (requerido)listaLos campos, en orden. Entre 1 y 40.
estadoslistaEl ciclo de vida, en orden; el primero es el inicial. Hasta 20. Omitilo si la entidad no tiene ciclo.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

consultar_registros

alcance: lectura · sólo lee · idempotente

Los registros de una entidad, con el total real y una página. Filtrá por estado, por una palabra de la clave natural (busca), por igualdad sobre un campo declarado (campo + valor) o con filtros, que comparan: <, <=, >, >= para números, montos y fechas (AAAA-MM-DD), = y !=, y vacio / con_valor. != NO incluye los que no tienen valor: «no se renueva» y «no dice» son distintos, y los segundos están en vacio. Cada registro trae datos ya interpretados: por campo el valor crudo y su texto (el dinero con moneda, la ubicación como «lat, lng», la persona con su nombre); y si salió de un documento, citas (de dónde salió cada campo) y no_pude (lo que el documento no dice). Del más reciente al más viejo. Si total es mayor que mostrando, paginá con siguiente_desde: no cuentes la lista.

ArgumentoTipoQué es
entidad (requerido)stringLa clave de la entidad, de listar_entidades.
estadostringSólo los que están en este estado.
buscastringUna parte de la clave natural (un mail, un número de pedido).
campostringUn campo de la entidad para filtrar por igualdad. Va con valor.
valorobjectEl valor exacto de campo (texto, número o booleano).
filtroslistaHasta 6, y se cumplen todos: [{"campo": "vigenciahasta", "op": "<", "valor": "2027-03-01"}, {"campo": "renovacionautomatica", "op": "=", "valor": false}].
limitenumberCuántos traer por página (1 a 200). Por defecto 50.
desdenumberDesde qué posición arrancar, para paginar.

ver_registro

alcance: lectura · sólo lee · idempotente

Un registro de Datos completo: sus datos interpretados, su estado, y la historia de quién lo movió (persona o agente), cuándo, con qué tarea y qué cambió —del hecho más nuevo al más viejo—. Se pide por registro_id, o por entidad + clave (la clave natural). Para lo que los agentes hicieron alrededor de él, ver_actividad con registro_id.

ArgumentoTipoQué es
registro_idstringEl id del registro, de consultar_registros.
entidadstringLa clave de la entidad, si se busca por clave natural.
clavestringLa clave natural del registro (el mail, el número de pedido).

guardar_registro

alcance: escritura · idempotente

Crea o actualiza UN registro de una entidad. La clave natural identifica al objeto en el negocio (el mail del lead, la patente del vehículo): si no existe se crea —con todos los campos requeridos—; si existe, los campos que mandes se combinan con los que tiene, y los que no mandes quedan como estaban. Mandar lo mismo dos veces es el mismo registro. estado mueve el ciclo de vida (al crear, si falta, arranca en el inicial). Los valores van con la forma de su tipo (ver definir_entidad). Queda anotado en la historia del registro con la persona que firma este token.

ArgumentoTipoQué es
entidad (requerido)stringLa clave de la entidad.
clave (requerido)stringLa clave natural del registro.
datos (requerido)objectLos campos, sólo los declarados por la entidad.
estadostringEl estado al que pasa. Opcional.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

importar_registros

alcance: escritura · idempotente

Crea o actualiza hasta 100 registros de una entidad en una llamada: para migrar un CRM, cargar la flota, sembrar una cola. Cada fila es { clave, datos, estado? } con las mismas reglas que guardar_registro. Se procesa fila por fila: las que fallan no frenan a las demás, y la respuesta dice cuáles entraron, cuáles se actualizaron y cuáles fallaron con su motivo. No es una transacción: lo que entró, entró.

ArgumentoTipoQué es
entidad (requerido)stringLa clave de la entidad.
filas (requerido)listaHasta 100. Cada una: { clave, datos, estado? }.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

Consolas

Las pantallas declaradas del equipo del cliente. Área de búsqueda: consolas.

catalogo_de_consola

alcance: lectura · sólo lee · idempotente

Qué se puede poner en la consola de un agente: sus entidades con campos y estados, y las herramientas que tiene HABILITADAS. Empezá siempre por acá: una consola que nombra algo que no está en este catálogo no se guarda.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_agentes.

biblioteca_de_consolas

alcance: lectura · sólo lee · idempotente

De dónde partir en vez de una hoja en blanco: las formas de supervisión que ya conocemos —bandeja, tablero, revisión, cierre del día, pedirle algo al agente, ficha— armadas contra las entidades y las herramientas habilitadas de ESE agente. Vuelven todas, también las que no aplican: cada una dice si aplica y, si no, qué le falta al catálogo (estados, entidades, herramientas). Nada de esto se guarda: para bajar una, arrancar_consola.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_agentes.

arrancar_consola

alcance: lectura · sólo lee · idempotente

Arma una plantilla de la biblioteca para este agente y la devuelve SIN guardarla, con los supuestos que tomó (qué entidad eligió, qué estados leyó como «pendiente» o «listo»). Editala y proponela con proponer_consola.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente.
plantilla (requerido)stringLa clave de la plantilla, de biblioteca_de_consolas.

listar_consolas

alcance: lectura · sólo lee · idempotente

Las consolas de la organización: su clave, de qué agente son, qué versión está publicada y si hay algo propuesto sin publicar.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

ver_consola

alcance: lectura · sólo lee · idempotente

El cuerpo de una consola tal como se commitea en el repo del cliente (.yorobot/consolas/<clave>.json). Con borrador: true devuelve lo propuesto y todavía no publicado.

ArgumentoTipoQué es
clave (requerido)stringLa clave de la consola, que es su URL.
borradorbooleanVer lo propuesto en vez de lo publicado.

proponer_consola

alcance: escritura · idempotente

Propone una consola SIN publicarla: queda como borrador con URL de preview y diff contra lo publicado. Los bloques son de once tipos y nada más (hasta 12 bloques por consola): · { tipo: "contador", titulo, entidad, filtro? } · { tipo: "tabla", titulo, entidad, columnas: [...], filtro? } — columnas: campos de la entidad, o clave/estado/actualizado/dueno · { tipo: "tablero", titulo, entidad, etiqueta?: campo } — una columna por estado · { tipo: "ficha", titulo, entidad, campos?: [...] } — el registro ELEGIDO (desde una lista, tabla o tablero de la misma consola) con sus campos; sin «campos», todos · { tipo: "lista", titulo, entidad, encabezado: campo|"clave", detalle?: [hasta 3 campos], filtro?, limite?: 5..100 (20) } — tarjetas de los últimos que se movieron · { tipo: "mapa", titulo, entidad, campo: campo GEO, etiqueta?: campo, filtro? } — cada registro con lat/lng como punto (hasta 500), en proporción y sin mapa de terceros · { tipo: "grafico", titulo, entidad, por: campo|"estado", suma?: campo numero|dinero, filtro? } — barras: cuántos por «por», o la suma de «suma» por «por» (hasta 24 barras) · { tipo: "lineadetiempo", titulo, entidad, campo: campo FECHA|"actualizado"|"creado", etiqueta?: campo, filtro?, limite?: 5..100 (20) } — los registros ordenados por ese momento · { tipo: "actividad", titulo, agente?: id, limite?: 5..100 (20) } — lo que el agente fue haciendo, hecho por hecho, del registro elegido si hay uno Los tipos de campo salen del catálogo real del tenant (listarentidades): un mapa sobre un campo que no es geo, una suma sobre un texto o una línea de tiempo sobre un número no validan. Si la entidad o el campo desaparecen después, el bloque se poda al leer y la pantalla dice por qué. Declarar un bloque NO habilita nada: quién ve esos registros y quién puede operarlos lo siguen decidiendo los roles y el puesto. · { tipo: "comparacion", titulo, entidad, campoSugerido, campoValidado } — cuánto se le corrige al agente: coincidencias y, si el campo validado declara opciones, cuántas veces una persona SUBIÓ y cuántas BAJÓ (la primera opción es el extremo alto). Lo que nadie validó todavía queda fuera del denominador. · { tipo: "acciones", titulo, acciones: [ { tipo: "moverestado", etiqueta, entidad, a: estado, desde?: estado, confirmar?: true, avisar?: "título de la tarea" } | { tipo: "pedirtarea", etiqueta, titulo } | { tipo: "llamarherramienta", etiqueta, herramienta } ] } o { tipo: "anotar", etiqueta, entidad, campos: [ { campo, opciones?: [...], deEntidad?: entidad, requerido?: true } ], firma?: campo, a?: estado, avisar?: título } ] o { tipo: "crear", etiqueta, entidad, clave: campo, campos: [ … ], firma?: campo, a?: estado } ] «crear» estrena un registro: es cómo una persona agrega una tarjeta al tablero sin pasar por un agente. «clave» nombra cuál de los campos del formulario identifica al registro (el título de la tarea, el mail), y ese campo va requerido. Si ya existe uno con esa clave no se pisa: se dice que ya está. «anotar» es el formulario: una persona escribe campos del registro. Hasta 4 campos; con «opciones» el valor sale de una lista cerrada (un color tipeado a mano llega en tres grafías y deja de ser contable). «deEntidad» completa el campo con los REGISTROS de otra entidad (el centro, la sucursal, la zona): la lista sale del padrón al abrir la pantalla y el servidor rechaza cualquier valor que no sea uno de ellos. Es lo que hace que repartir una cola no pueda inventar un destino, y no envejece cuando abre un centro nuevo. No se combina con «opciones»: dos listas para el mismo campo es una que miente. «firma» es el campo donde el SERVIDOR escribe quién apretó, tomado de la sesión: no se pide en el formulario y no puede estar además en «campos». Un campo así llenado a mano no dice quién decidió, dice qué se tipeó. «a» deja el registro en ese estado en la MISMA escritura que la anotación: dos escrituras dejarían un intervalo donde el registro ya está validado y todavía no dice qué se validó. «desde» en moverestado exige que el registro ESTÉ en ese estado: es cómo se ordena una cola de dos pasos. Sin «desde», el botón que deriva y avisa se puede apretar sobre un registro que nadie validó todavía, y lo único que lo evita es que la persona haya apretado los botones en el orden correcto. «confirmar» en moverestado pregunta antes de mover, y es lo que hace seguro el tablero: una tarjeta se arrastra a la columna de al lado sin querer, y hay estados de los que no se vuelve («ganado», «perdido»). Un tablero deja arrastrar SÓLO a las columnas que tienen su botón declarado acá: lo que no se puede apretar tampoco se puede soltar. «avisar» en moverestado y en anotar encola esa tarea DESPUÉS de escribir, con el registro ya actualizado: úsalo cuando decidir y comunicar sean el mismo acto y partirlo en dos botones deje a alguien esperando. Botones de canal, todos sobre un registro elegido: { tipo: "llamar", etiqueta, entidad, telefono: campo TELEFONO, motivo } | { tipo: "mensajear", etiqueta, entidad, telefono: campo TELEFONO, plantilla: plantilla aprobada por Meta, idioma?: "esAR", parametros?: [campos, hasta 6] } | { tipo: "escalar", etiqueta, entidad } | { tipo: "aprobar", etiqueta, entidad }. «llamar» exige el canal de voz PRENDIDO en producción y le pide la llamada al agente como tarea (presupuesto, guardarriel y bitácora de siempre). «mensajear» exige WhatsApp prendido y encola la plantilla con los parámetros tomados del registro, una vez por registro, plantilla y día. «escalar» exige que algún destinatario de Avisos reciba «consola.escalada»; la persona escribe el motivo y sale el aviso. «aprobar» lleva a la tarea que espera firma por ese registro: NO firma desde la consola. Si el canal está apagado el botón se poda al leer; una vista no prende canales (eso es Capacidades), y el teléfono sale del registro, nunca de quien aprieta. La consola entera se puede partir por un campo con «segmentar»: { campo, etiqueta? } al lado de «bloques». La pantalla muestra un selector con los valores que HAY —más «sin valor», que es su propia cola— y lo elegido filtra TODOS los bloques, contadores incluidos. Es para un mismo trabajo repartido por sucursal, centro o zona: siete consolas publicadas se corrigen de a una y quedan desalineadas seis. El campo tiene que existir en TODAS las entidades que la consola mira, o no valida: un bloque que no se puede segmentar mostraría todo mientras el encabezado anuncia uno solo. Segmentar es una forma de mirar y NO un permiso: quién puede operar sobre esos registros lo siguen decidiendo los roles. El filtro es una condición { campo, igual } o { campo, vacio: true } (el campo todavía no tiene valor), o varias que se cumplen TODAS: { y: [ {...}, {...} ] }, hasta 4. Sin «y» un bloque sólo puede pedir una cosa, y «rojos sin validar» termina contando también los ya validados. Si algo no valida, la respuesta trae TODOS los problemas: corregí y volvé a proponer.

ArgumentoTipoQué es
clave (requerido)stringMinúsculas y guiones, empieza con letra: es la URL («mesa-de-entradas»).
agente_idstringEl agente dueño. Obligatorio si la consola es nueva; de él salen las herramientas autorizadas.
titulo (requerido)stringEl encabezado que lee la persona que opera.
subtitulostringUna línea de contexto. Vacío si no aporta.
bloques (requerido)listaLa consola misma, en orden de arriba hacia abajo.
segmentarobjectOpcional: { campo, etiqueta? } para partir la consola entera por un campo (centro, sucursal, zona).
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

publicar_consola

alcance: escritura · idempotente

Publica el borrador: recién acá cambia la pantalla con la que trabaja el equipo del cliente. Se vuelve a validar contra lo que hay HOY, y queda en la bitácora con quién publicó.

ArgumentoTipoQué es
clave (requerido)stringLa clave de la consola.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

descartar_borrador

alcance: escritura · destructiva · idempotente

Tira lo propuesto. Lo publicado no se toca; una consola que nunca se publicó se borra entera.

ArgumentoTipoQué es
clave (requerido)stringLa clave de la consola.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

Cerebro y memoria

Conocimiento: documentos, fuentes vivas, memorias y skills. Área de búsqueda: conocimiento.

listar_memorias

alcance: lectura · sólo lee · idempotente

La memoria de la organización por estado: qué dice cada una, de qué agente es, de dónde salió, si la respalda una medición independiente, y sus usos/aciertos/fallos. Empezá por acá antes de proponer: una lección que ya está activa vuelve a entrar como duplicada.

ArgumentoTipoQué es
estadostringpropuesta \activa \suspendida \jubilada, o varias separadas por coma. Por defecto propuesta,activa.
agente_idstringSólo la memoria de ese agente. Vacío trae también la de la organización (el piso compartido).
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

proponer_memoria

alcance: escritura · idempotente

Propone una memoria para un agente. NACE PROPUESTA: no viaja a ninguna corrida hasta que alguien la acepte con decidir_memoria. El trigger es cuándo aplica y contents qué hacer: las dos las lee el modelo en la próxima corrida, así que van cortas y en imperativo. Se rechaza —con motivo— lo que la pantalla también rechaza: instrucciones dirigidas al modelo que vengan de un tercero, credenciales, Unicode invisible, y contenido clínico o identificatorio en un perfil. Los tipos episodio y perfil NO se cargan a mano por acá: un episodio sale del verificador de una corrida y un perfil exige sujeto para poder purgarse cuando esa persona pida que la olviden.

ArgumentoTipoQué es
agente_idstringDe qué agente es. Vacío = de la organización, el piso que comparten todos.
tipostringhecho (un dato del negocio), regla (una política de la casa) o leccion (lo que salió mal una vez). Por defecto leccion.
trigger (requerido)stringCuándo aplica, en una línea: «cuando el pedido no trae número de socio».
contents (requerido)stringQué hacer, en imperativo y corto. Es lo que va a leer el modelo.
proyecto_idstringOpcional: la limita a las tareas de ese proyecto.
evidencia_tarea_idstringLa tarea de la que sale, si sale de una. Es el link a la evidencia.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

medir_memoria

alcance: escritura

Manda a medir una memoria: la suite de casos congelados del agente DOS veces, con ella y sin ella, y el veredicto sale por caso. Sirve sobre una propuesta SIN aceptarla —es el punto: medir antes de decidir— y también sobre una activa, para poder jubilar la que no aporta. Arregló 3 y rompió 1 es REGRESIÓN y no un neto de +2: es lo que un promedio esconde. Encola las dos pasadas y vuelve; el veredicto lo escribe el último caso. Cada llamada corre la suite completa dos veces y eso se paga: mandá clave_de_pedido para que un reintento no la corra de nuevo.

ArgumentoTipoQué es
memoria_id (requerido)stringEl id de la memoria, de listar_memorias.
agente_idstringContra qué agente medir. Obligatorio para una memoria de la organización, que no tiene dueño.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

decidir_memoria

alcance: escritura · idempotente

Decide una propuesta: aceptar la pone a viajar en las próximas corridas de ese agente, descartar la jubila. Aceptar admite editar el texto en el mismo acto, y lo que se guarda es LO EDITADO: el filtro de contenido vuelve a correr sobre eso, y si la memoria salía de un documento se vuelve a comprobar el respaldo textual contra el fragmento citado. Es una decisión de gobierno y queda en la bitácora con quién la tomó. NO es una aprobación de tarea: eso sigue estando sólo en la pantalla.

ArgumentoTipoQué es
memoria_id (requerido)stringEl id de la propuesta, de listar_memorias.
decision (requerido)stringaceptar o descartar.
triggerstringSólo al aceptar: reemplaza el «cuándo aplica». Vacío deja el propuesto.
contentsstringSólo al aceptar: reemplaza el «qué hacer». Vacío deja el propuesto.
motivostringSólo al descartar: por qué no entra. Queda en la constancia.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_skills

alcance: lectura · sólo lee · idempotente

Las skills instaladas: cómo se llama cada una, cuándo la abre un agente, qué nivel de confianza tiene, su versión y su hash, y a cuántos agentes está puesta. Una skill puesta viaja en el prompt de cada corrida de ese agente. Con agente_id, dice además cuáles tiene puestas ESE agente.

ArgumentoTipoQué es
agente_idstringOpcional: el id de un agente, para saber cuáles tiene puestas.
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

cargar_skill

alcance: escritura · idempotente

Carga una skill desde su SKILL.md completo, con el frontmatter. El frontmatter necesita name y description. La description es lo que decide CUÁNDO el agente la abre, así que dice en qué pedidos aplica, no qué es. CARGAR NO LA ASIGNA: la skill queda en la organización y no viaja a ninguna corrida hasta asignar_skill. El nivel de confianza lo mide la plataforma del contenido, no de lo que el archivo declare: un SKILL.md que trae cosas para ejecutar queda en scripts_executables aunque diga otra cosa, y bajo contención esas quedan afuera.

ArgumentoTipoQué es
cuerpo (requerido)stringEl SKILL.md entero, con su frontmatter ---.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

asignar_skill

alcance: escritura · idempotente

Pone una skill en un agente, o se la saca con puesta: false. Puesta, viaja en el prompt de TODAS las corridas de ese agente — no es una biblioteca que consulta, es contexto que carga siempre. Bajo contención, cuando el agente lee texto que escribió un tercero, las que traen cosas para ejecutar quedan afuera aunque estén puestas.

ArgumentoTipoQué es
agente_id (requerido)stringEl id del agente, de listar_agentes.
skill_id (requerido)stringEl id de la skill, de listar_skills.
puestabooleantrue la pone, false la saca. Por defecto true.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_fuentes

alcance: lectura · sólo lee · idempotente

Los documentos del cerebro de la organización: título, cuándo usarlo, alcance, estado, la versión vigente, cuántos fragmentos tiene y cuántos quedaron marcados como sospechosos. Sólo las publicadas llegan a una corrida.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

ver_documento

alcance: lectura · sólo lee · idempotente

Un documento con todas sus versiones (número, formato, estado, hash) y qué agentes lo tienen habilitado. Con version_id devuelve además los fragmentos de esa versión con su orden y su hash: son las unidades que se citan, y el orden es lo que una cita nombra.

ArgumentoTipoQué es
documento_id (requerido)stringEl id del documento, de listar_fuentes.
version_idstringOpcional: además, los fragmentos de esa versión.
citasbooleanTraer también qué corridas lo citaron, con la versión que leyeron.

cargar_documento

alcance: escritura · idempotente

Carga un documento al cerebro: crea la fuente (o le agrega una versión, con documento_id) y la fragmenta. CARGAR NO PUBLICA: la versión queda en borrador y no llega a ninguna corrida hasta publicar_documento. El texto va en texto (Markdown o texto plano). Un PDF va en contenido_base64 con su nombre_archivo; si el PDF no tiene texto —un escaneo— se rechaza CON MOTIVO en vez de entrar vacío: no hay OCR. El resumen es lo único que viaja SIEMPRE —una línea por fuente en el índice de cada corrida—, así que es «cuándo usar este documento» y no un abstract. guardar_original deja además el archivo: va en true para protocolos y contratos de la organización, porque hace falta para auditar una cita, y en FALSE para cualquier documento con datos de personas.

ArgumentoTipoQué es
documento_idstringPara agregar una versión a un documento que ya existe. Vacío crea uno nuevo.
titulostringCómo se llama. Obligatorio si es nuevo.
resumenstringCuándo usarlo, en una línea. Obligatorio si es nuevo: es lo que el agente lee en el índice para decidir si lo abre.
alcancestringtenant (todos los agentes), proyecto (los de ese proyecto) o agente (sólo los que lo tengan habilitado). Por defecto tenant.
proyecto_idstringObligatorio si el alcance es proyecto.
guardar_originalbooleanGuardar el archivo además del texto. Por defecto false: el default seguro es el que no deja el original en la base.
textostringEl cuerpo, en Markdown o texto plano.
contenido_base64stringAlternativa a texto para un PDF: el archivo en base64.
nombre_archivostringEl nombre con extensión (protocolo.md, contrato.pdf). Con contenido_base64 es obligatorio: de la extensión sale cómo se extrae el texto.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_colecciones

alcance: lectura · sólo lee · idempotente

Las colecciones del cerebro («Contratos de proveedores», «Facturas 2026»): cada una con su plantilla de corte, su alcance y cuántos documentos tiene —publicados (los ven las corridas) y en borrador (todavía no)—. Para cargar a una, cargar_documentos con su nombre o id.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

crear_coleccion

alcance: escritura

Crea una colección: un conjunto de documentos que se carga por lote y se busca adentro («Contratos de proveedores»). Sus documentos heredan el alcance y la plantilla de corte. La plantilla decide dónde se parte cada documento en fragmentos citables: clausulas para contratos y reglamentos (corta donde empieza cada cláusula numerada: «7.2», «CLÁUSULA PRIMERA», «Artículo 5»), filas para planillas (grupos de filas con el encabezado adelante), parrafos para todo lo demás. El nombre no se repite en la organización.

ArgumentoTipoQué es
nombre (requerido)stringCómo se llama, hasta 80 caracteres.
descripcionstringQué hay adentro, en una línea: va en el «cuándo usarlo» de cada documento.
plantillastringparrafos (por defecto), clausulas o filas.
alcancestringtenant (todos los agentes, por defecto), proyecto o agente.
proyecto_idstringObligatorio si el alcance es proyecto.
agente_idstringObligatorio si el alcance es agente: el único agente que la lee.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

cargar_documentos

alcance: escritura · idempotente

Carga hasta 20 documentos por llamada, cada uno por su lado: la respuesta dice qué pasó con cada archivo —ingerida, duplicada (el mismo archivo ya estaba: dónde) o rechazada (con el motivo)—. Un rechazo no deja nada cargado. A diferencia de cargar_documento, PUBLICA por defecto lo que entra limpio (publicar: false para dejarlo en borrador). Lo que trae un fragmento que parece una instrucción al modelo queda en borrador igual, con el porqué. Cada documento va con nombre_archivo (de la extensión sale cómo se extrae: .md, .txt, .pdf con texto, .html) y contenido_base64, o texto para Markdown. El título es el nombre del archivo. Con coleccion, entran a esa colección y heredan su alcance y su plantilla de corte. El cuerpo de la llamada no puede pasar de 4 MB: para una carpeta grande, varias llamadas (o yorobot cerebro subir). Cuenta contra el techo de documentos del plan: lo que lo pasa se rechaza con ese motivo y lo anterior queda.

ArgumentoTipoQué es
coleccionstringLa colección, por nombre o por id. Vacío deja los documentos sueltos en el cerebro.
documentos (requerido)listaHasta 20.
publicarbooleanPor defecto true: lo que entra limpio lo ven las corridas enseguida.
guardar_originalbooleanGuardar el archivo además del texto (por defecto true, para auditar una cita). En false para documentos con datos de personas.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

configurar_extraccion

alcance: escritura · idempotente

Convierte una colección en una TABLA de Datos: un agente por documento (el Extractor de la biblioteca) lee ese documento y llena una fila, con la cita del fragmento de donde sacó cada campo. Lo que el documento no dice queda sin valor y con el porqué (no_pude): nunca inventado. Es la forma de comparar cientos de documentos: después, consultar_registros con filtros contesta «¿cuáles vencen antes de marzo y no se renuevan solos?» sin volver a leer ninguno. plantilla: contratos (partes, objeto, fechafirma, vigenciahasta, monto, moneda, renovacionautomatica, plazode_rescision, jurisdiccion, penalidades) o facturas (proveedor, numero, fecha, vencimiento, total, moneda, concepto). O tu esquema, con la pregunta que contesta cada campo. Encola una tarea por documento publicado, y desde ahí cada documento o versión nueva de la colección se extrae sola. Cambiar el esquema re-extrae todo; repetir con el mismo, nada. La respuesta dice cuántas tareas se crearon, en qué ambiente corren y el TOPE de plata (documentos × presupuesto por documento): decíselo a la persona antes de dar por hecho el gasto.

ArgumentoTipoQué es
coleccion (requerido)stringLa colección, por nombre o id.
plantillastringcontratos o facturas. Alternativa a esquema.
esquemaobject{ entidad, nombre, campos: [{ nombre, tipo, pregunta, opciones?, moneda? }] }. entidad en minúsculas («contratos_proveedores»); tipos: texto, numero, booleano, fecha, opcion, dinero, email, url, telefono; pregunta es lo que el agente le pregunta al documento («¿Hasta qué fecha rige, sin contar renovaciones?»). Hasta 20 campos.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

extraer_pendientes

alcance: escritura · idempotente

Encola lo que la extracción de una colección dejó sin tarea: la cuota de tareas automáticas llena, el tope de gasto, el Extractor apagado, o más de 1000 documentos de una vez. Con reintentar_fallidas, también los documentos cuya tarea terminó sin escribir la fila — no se reintentan solos porque un documento que el agente no puede leer fallaría cada vez, y cada vez se paga.

ArgumentoTipoQué es
coleccion (requerido)stringLa colección, por nombre o id.
reintentar_fallidasbooleanVolver a pedir también los que fallaron. Por defecto false.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

comparar_documentos

alcance: lectura · sólo lee · idempotente

Compara dos documentos del cerebro sección por sección —o dos versiones del mismo— y devuelve las diferencias ya calculadas: qué cláusulas cambiaron (lo que se sacó y lo que se puso), cuáles se renumeraron, cuáles están de un solo lado y cuáles son idénticas. Las cláusulas se alinean por número aunque uno escriba «SEGUNDA» y el otro «2», y la que cambió de número se encuentra por el texto. Cada diferencia trae la cita a los DOS documentos: al contarla, citá las dos. No leas los dos documentos para compararlos a ojo: esto ya lo hizo, y no se saltea la cláusula que se movió.

ArgumentoTipoQué es
a (requerido)stringEl id del primer documento.
b (requerido)stringEl id del segundo. Puede ser el mismo que a, con otra versión.
version_anumberLa versión de a. Por defecto, la publicada.
version_bnumberLa versión de b. Por defecto, la publicada.

publicar_documento

alcance: escritura · idempotente

Publica una versión: recién acá el documento empieza a ofrecerse en las corridas que vengan. La anterior queda archivada y las citas viejas siguen apuntando a la versión que el agente leyó.

ArgumentoTipoQué es
documento_id (requerido)stringEl id del documento.
version_id (requerido)stringLa versión a publicar, de ver_documento.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

despublicar_documento

alcance: escritura · destructiva · idempotente

Retira el documento de las corridas que vengan y SUSPENDE las memorias que se habían promovido de él: una regla destilada de un documento retirado seguiría afirmando lo mismo desde adentro del prompt. No borra el texto ni las citas; para eso está la purga, que es de la pantalla.

ArgumentoTipoQué es
documento_id (requerido)stringEl id del documento.
motivostringPor qué se retira. Queda en la bitácora de la fuente.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

alcance_de_documento

alcance: escritura · idempotente

Prende o apaga un documento para UN agente. Es lo que hace que el cerebro compartido no sea un cajón único: un documento de alcance agente sólo llega a los que están habilitados acá.

ArgumentoTipoQué es
documento_id (requerido)stringEl id del documento.
agente_id (requerido)stringEl id del agente.
habilitado (requerido)booleantrue lo habilita, false lo saca.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

medicion_del_cerebro

alcance: lectura · sólo lee · idempotente

La medición del cerebro documental, que es el gate para decidir si hacen falta embeddings — y hoy no hacen falta. Nada está etiquetado a mano: el positivo es una cita válida, así que volver a seleccionar con el mismo pedido mide el recall contra evidencia real. Separa las tres maneras de tener recall bajo: sin evidencia (0 de 0 no es 0%), desplazada (coincidía y le ganaron el lugar en el índice: eso se arregla con el tope, no con vectores) y no_coincide, que es la única que un vector store arregla.

Sin argumentos.

grafo_del_cerebro

alcance: lectura · sólo lee · idempotente

El cerebro de la organización como grafo: documentos, memorias, agentes y proyectos como nodos, y como relaciones lo que la plataforma registró — cita (una ejecución del agente citó el documento, con versión y fragmento; peso es cuántas veces), alcance (habilitado para el agente sin cita todavía), promovida (la memoria salió del documento), memoria (del agente, o la usó), proyecto y reemplaza. Sirve para contestar de dónde sale lo que un agente afirma, quién más usa un documento, y qué conocimiento publicado no está usando nadie (sin_uso). Es lo mismo que dibuja la pantalla Cerebro → Grafo.

ArgumentoTipoQué es
tiposlistaQué nodos incluir. Sin esto, todos.

listar_fuentes_vivas

alcance: lectura · sólo lee · idempotente

Las fuentes vivas del cerebro: qué conexión a HubSpot u Odoo hay, qué objetos trae, cuándo sincronizó por última vez, con qué resultado (nuevos, cambiados, iguales, rechazados), cuándo toca la próxima y si la última falló y por qué. También dice si falta la credencial (tiene_credencial): la conexión usa la misma llave que la herramienta del agente, la que se carga con cargar_credencial o en Conexiones.

ArgumentoTipoQué es
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

conectar_fuente_viva

alcance: escritura

Conecta HubSpot u Odoo como fuente del cerebro. Se elige OBJETO POR OBJETO (objetos): no se trae el CRM o el ERP entero. catalogo_de_fuentes_vivas lista los objetos de cada proveedor y cuáles traen datos de personas. Lo que trae entra por la misma ingestión que un archivo: escaneo, hash, versión sólo si cambió, fragmentos y citas. Por defecto queda EN BORRADOR; publicar: true publica solo cada documento que trae. La primera sincronización la hace el worker de la organización en su próxima vuelta; después, cada cada_horas. La credencial tiene que estar cargada con cargar_credencial o en Conexiones (hubspot_token u odoo_api_key); esta llamada no la pide ni la ve.

ArgumentoTipoQué es
proveedor (requerido)hubspot · odoohubspot u odoo.
nombrestringCómo llamar a la conexión. Por defecto, el nombre del proveedor.
urlstringSólo Odoo: la URL https del servidor, p. ej. https://miempresa.odoo.com.
objetos (requerido)listaQué traer, por clave del catálogo: articulos, tickets, negocios, empresas, notas (HubSpot); articulos, productos, tickets, notas (Odoo).
limitenumberTope de registros por objeto y sincronización, de 1 a 2000. Por defecto 200.
cada_horasnumberCada cuántas horas sincronizar, de 1 a 720. Por defecto 24.
alcancestringtenant, proyecto o agente. Por defecto tenant.
proyecto_idstringObligatorio si el alcance es proyecto.
publicarbooleanPublicar solo lo que trae. Por defecto false: queda en borrador.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

catalogo_de_fuentes_vivas

alcance: lectura · sólo lee · idempotente

Los proveedores que el cerebro puede conectar (HubSpot, Odoo) y, para cada uno, los objetos que se pueden elegir, qué traen y cuáles tienen datos de personas.

Sin argumentos.

configurar_fuente_viva

alcance: escritura · idempotente

Cambia objetos, tope, frecuencia, alcance, publicación automática o pausa (activa: false) de una conexión. Lo ya traído no se borra: los documentos siguen con sus versiones y citas.

ArgumentoTipoQué es
fuente_viva_id (requerido)stringEl id, de listar_fuentes_vivas.
nombrestringNuevo nombre.
urlstringSólo Odoo: nueva URL https.
objetoslistaNuevos objetos a traer.
limitenumberNuevo tope de registros por objeto y sincronización, de 1 a 2000.
cada_horasnumberCada cuántas horas sincronizar, de 1 a 720.
alcancestringtenant, proyecto o agente.
proyecto_idstringSi el alcance es proyecto.
publicarbooleantrue publica solo lo que trae; false lo deja en borrador.
activabooleanfalse pausa la conexión: deja de sincronizar hasta reanudarla.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

sincronizar_fuente_viva

alcance: escritura · idempotente

Marca la conexión para que el worker la sincronice en su próxima vuelta, sin esperar el plazo. No trae nada desde acá: el resultado se ve después con listar_fuentes_vivas.

ArgumentoTipoQué es
fuente_viva_id (requerido)stringEl id de la conexión.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

desconectar_fuente_viva

alcance: escritura

Borra la conexión. Los documentos que trajo QUEDAN, con sus versiones y citas, como documentos sueltos; para que se vayan hay que purgarlos o esperar la retención. La credencial no se toca.

ArgumentoTipoQué es
fuente_viva_id (requerido)stringEl id de la conexión.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

buscar_en_cerebro

alcance: lectura · sólo lee · idempotente

Busca en el TEXTO de todos los documentos publicados del Cerebro de la organización —contratos, protocolos, manuales— y devuelve los pasajes que coinciden, cada uno con su cita [cerebro/…#n], el documento, la versión vigente y la sección («Cláusula 7.2 · p. 3»). Buscá con las palabras del documento; si lo que vuelve no alcanza, buscá de nuevo con otras. Dice cuántos pasajes coincidieron en total y si la lista está recortada. Una búsqueda por texto no entiende negaciones: «no se renueva» también coincide con «renovación», así que leé el pasaje antes de afirmar.

ArgumentoTipoQué es
consulta (requerido)stringQué buscar, con las palabras que usaría el documento.
coleccionstringSólo en esta colección (nombre o id).
documento_idstringSólo adentro de este documento.
limitenumberCuántos pasajes, hasta 30. Por defecto 10.

Consumo y límites

El plan y la membresía, gasto, topes (también el de cada agente), cuotas, el registro de pedidos, retención y la cartera partner. Área de búsqueda: consumo.

fijar_cuota_mensual

alcance: escritura · idempotente

Fija el tope mensual de gasto de modelo de la organización, en USD: el número contra el que la cola frena toda tarea nueva. Lo fija un técnico o un admin. Para sacarlo hace falta sin_tope: true con todas las letras (sólo tiene sentido si la organización trae su propia llave de modelo). El tope se puede bajar, pero no subir por encima del que trae el plan (ni sacar, si el plan trae uno): eso lo hace un cambio de plan o YoRobot, y el error lo dice con el número. La respuesta dice el tope de antes, el de ahora y el que el plan traería por defecto, para que se vea de qué te alejás.

ArgumentoTipoQué es
tope_usdnumberEl tope en USD por mes, cero o más.
sin_topebooleantrue para sacar el tope. Incompatible con tope_usd.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

fijar_tope_diario

alcance: escritura · idempotente

Fija el tope DIARIO de gasto de modelo de la organización, en USD, aparte del mensual: el mensual ve el accidente cuando ya se comió el mes; éste frena la cola el mismo día (un webhook que rebota, una automatización descontrolada). Cuenta todos los ambientes juntos, en el huso de la organización. Va en dólares y no en tokens porque el costo depende del modelo y de entrada/salida, y la factura se lee en dólares. Lo fija un técnico o un admin. sin_tope: true lo saca.

ArgumentoTipoQué es
tope_usdnumberEl tope en USD por día, mayor que cero.
sin_topebooleantrue para sacar el tope diario. Incompatible con tope_usd.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

ver_cuotas

alcance: lectura · sólo lee · idempotente

Todos los límites de consumo de la organización con lo consumido hasta ahora: el tope mensual y el diario de gasto de modelo (USD), el tope mensual de prueba/preproducción, y los techos por ventana (cuántas tareas o ejecuciones entran por hora o por día, por tipo). Cada techo dice cuánto va usado, cuánto queda y a qué hora se libera. frenado: true cuando algún tope de gasto ya está lleno y la cola no despacha.

Sin argumentos.

ver_plan

alcance: lectura · sólo lee · idempotente

El plan de la organización y lo que ese plan frena: agentes propios contra el techo (las plantillas de YoRobot no cuentan), si puede crear otro, los ambientes (si llega a producción), quién ejecuta las tareas (el pool de YoRobot o un worker dedicado), el tope de modelo del mes y los techos por ventana que trae el plan. Lo gastado contra cada tope está en ver_cuotas. El plan lo cambia YoRobot; la organización puede bajar sus límites, no subirlos.

Sin argumentos.

ver_membresia

alcance: lectura · sólo lee · idempotente

La membresía de la organización: el plan (plan y plan_texto, la palabra que se ve en el portal), su estado y si hay algo que pagar (hay_que_pagar, pagar_en). Mientras YoRobot no cobre por la web es siempre sin_facturacion con pagar_en: null: no hay link de pago que dar, y el plan lo cambia YoRobot. Lo mismo que GET /api/v1/membresia.

Sin argumentos.

fijar_tope_de_agente

alcance: escritura · idempotente

Fija el tope de gasto del MES de UN agente, en USD: cuando su gasto del mes llega ahí, sus tareas nuevas frenan igual que con el tope de la organización, y los demás agentes siguen. No puede ser mayor que el tope mensual de la organización. Ponerle uno o bajarlo lo hace cualquiera que opere el agente; subirlo o sacarlo (sin_tope: true), un técnico o un admin. El gasto del mes cuenta como el de la organización (mes calendario UTC). La respuesta trae el gasto del mes, el tope, porciento y bloqueado. Lo mismo que PUT /api/v1/agentes/{id}/tope; queda en la auditoría a tu nombre.

ArgumentoTipoQué es
agente_id (requerido)stringEl agente, de listar_agentes.
tope_mes_usdnumberEl tope en USD por mes, mayor que cero y no mayor que el tope mensual de la organización.
sin_topebooleantrue para sacarle el tope propio (manda sólo el de la organización). Incompatible con tope_mes_usd.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

listar_pedidos

alcance: lectura · sólo lee · idempotente

El registro de los pedidos que la organización le hizo a la API y al MCP en los últimos 30 días, del más nuevo al más viejo: cuándo, por dónde (api o mcp), el método y la ruta (o la herramienta), el status, cuánto tardó, con qué token, el ambiente y —si falló— el motivo que leyó el cliente. Cada respuesta de la API sale con X-Request-Id: con request_id se busca ese pedido. solo_errores: true trae los 4xx/5xx y los problemas del MCP. Nunca trae cuerpos ni argumentos: no se guardan.

ArgumentoTipoQué es
solo_erroresbooleantrue para ver sólo los que fallaron.
request_idstringEl X-Request-Id de una respuesta, para encontrar ese pedido.
canalstringapi o mcp. Sin esto, los dos.
limitenumberCuántas traer. Por defecto 25, máximo 100.
desdenumberDesde qué posición seguir. La respuesta trae siguiente_desde cuando queda más.
buscastringFiltra por nombre o clave, sin distinguir mayúsculas. Vacío trae todo.

fijar_cuota_por_ventana

alcance: escritura · idempotente

Pone un techo de CANTIDAD de trabajo por ventana calendario: cuántas tareas o ejecuciones de un tipo entran por hora o por día, en el huso de la organización. No es dinero: para eso están fijar_cuota_mensual y fijar_tope_diario. Los tipos cuentan por separado a propósito (un cron descontrolado no come la cuota de las personas). Lo fija un técnico o un admin. Volver a llamar con el mismo tipo y ventana reemplaza el límite; sacar: true lo borra. Un techo que trae el plan se puede bajar, pero no subir por encima del plan ni sacar: eso lo hace un cambio de plan o YoRobot.

ArgumentoTipoQué es
tipo (requerido)stringQué se cuenta: tareas_humanas, tareas_automaticas, corridas, tareas_de_canal, tareas_de_api o inferencias.
ventana (requerido)stringhora o dia, calendario.
limiteintegerCuántas entran en la ventana: entero mayor que cero.
sacarbooleantrue para borrar el techo de ese tipo y ventana. Incompatible con limite.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

consumo_por_esfuerzo

alcance: lectura · sólo lee · idempotente

Por agente, las tareas cerradas del mes clasificadas por lo que costó ejecutarlas (liviana / media / pesada), los casos ponderados que resultan, la mediana y el p90, cuántas quedaron fuera de serie, y cuánto se llevó aparte la verificación. Más las diez tareas más caras con su link. Es la base de la tarifa: el caso ponderado es la unidad que sirve para todas las actividades, y la verificación va separada porque es un dial del agente. Los umbrales están en la respuesta; no se cambian desde acá.

ArgumentoTipoQué es
messtringMes a mirar, AAAA-MM. Si falta, el mes en curso.

mi_cartera

alcance: lectura · sólo lee · idempotente

Para una organización partner: sus clientes, y por cada uno lo mismo que ve el cliente en su Inicio —agentes, discrepancias, tareas esperando aprobación, frenadas, gasto contra el tope—. Sólo números por cliente, ninguna fila de adentro. Vacío si la organización no tiene cartera. Para instalar un paquete en varios clientes de una vez: instalarenclientes.

Sin argumentos.

instalar_en_clientes

alcance: escritura · idempotente

Importa el mismo paquete —o componente de la biblioteca— en cada cliente indicado de la cartera, SÓLO a prueba (dev) en cada uno, con las mismas reglas que importaragente. Devuelve el resultado por cliente; un cliente que falla no frena a los demás. Cada instalación queda en la bitácora del cliente a nombre del partner. Producción se gana en cada cliente por separado: ensayaragente y promoverencliente.

ArgumentoTipoQué es
clientes (requerido)listaLos ids de organización de los clientes (de mi_cartera).
paqueteobjectEl paquete entero yorobot/agente@1. O en su lugar componente.
componentestringEn vez de paquete: la clave de un componente de la biblioteca (listar_componentes).
nombrestringOpcional, con componente: el nombre que va a tener el agente en cada cliente.
sin_faltantesbooleantrue: instalar aunque a un cliente le falten herramientas, y reportarlas.
notastringPor qué se instala. Opcional; queda en la bitácora de cada cliente.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

promover_en_cliente

alcance: escritura · idempotente

Lo mismo que promover_agente, pero adentro de un cliente de la cartera: sube la versión desplegada en desde («dev» o «staging») al ambiente siguiente. Exige que el ensayo del cliente esté en verde, igual que si lo hiciera el cliente. Queda en la bitácora del cliente a nombre del partner.

ArgumentoTipoQué es
cliente (requerido)stringEl id de organización del cliente (de mi_cartera).
agente_id (requerido)stringEl agente, adentro del cliente.
desde (requerido)string«dev» o «staging».
notastringOpcional; queda en la auditoría.
clave_de_pedidostringTu clave de idempotencia, opcional pero recomendada: si el pedido se reintenta con la MISMA clave, se devuelve el resultado del primero en vez de hacerlo dos veces. La misma clave con otros argumentos es un error, no un resultado viejo.

retencion

alcance: lectura · sólo lee · idempotente

Los plazos vigentes en días —ejecuciones, conversaciones, padrón, memoria, cerebro, bitácora— y cuándo se cambiaron. 0 es «no se purga por plazo». Cambiarlos es una decisión de cumplimiento y se hace en Ajustes → Retención, no desde acá.

Sin argumentos.

actividad_por_dia

alcance: lectura · sólo lee · idempotente

Lo mismo que las tiras de Consumo: los últimos dias (14 por defecto, hasta 90) día por día, en UTC como está guardado: corridas, costo de modelo y la verificación con su denominador (medidas, verificadas en limpio, discrepancias y la tasa sobre las medidas; sin medidas la tasa es null, no 0). Los días sin trabajo van en cero y dicen sin_trabajo: true. Más el total del período y, con 14 días o más, comparacion: los últimos 7 días contra los 7 anteriores, que es la respuesta a «¿la semana vino mejor o peor?».

ArgumentoTipoQué es
diasnumberCuántos días, de 1 a 90. Por defecto 14, como la pantalla.

Probalo acá

Las herramientas de lectura corren con tu sesión, contra tu organización, y sólo leen. Las que escriben se prueban desde tu editor con un token de Accesos.

Busca en el TEXTO de todos los documentos publicados del Cerebro de la organización —contratos, protocolos, manuales— y devuelve los pasajes que coinciden, cada uno con su cita `[cerebro/…#n]`, el documento, la versión vigente y la sección («Cláusula 7.2 · p. 3»). Buscá con las palabras del documento; si lo que vuelve no alcanza, buscá de nuevo con otras. Dice cuántos pasajes coincidieron en total y si la lista está recortada. Una búsqueda por texto no entiende negaciones: «no se renueva» también coincide con «renovación», así que leé el pasaje antes de afirmar.

Lo mismo desde tu terminal:

curl -X POST https://yorobot.ai/api/mcp \
  -H "Authorization: Bearer $YOROBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"buscar_en_cerebro","arguments":{}}}'