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— porintencionen castellano («conectar WhatsApp», «cuánto gasté») y/o porarea. 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 conclave_de_pedido(dentro deargumentos) 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_argumentoargumento_invalidono_existeestado_invalidosin_alcancedemasiados_pedidosclave_reusadaen_cursorequiere_personaherramienta_desconocidano_validafalla
Í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.
| Argumento | Tipo | Qué es |
|---|---|---|
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
vista (requerido) | tareas · gasto · aprobaciones | De dónde se cuenta: tareas, gasto (las ejecuciones) o aprobaciones. |
medida | tareas · frenadas · costo · ejecuciones · aprobadas · rechazadas | Qué se cuenta. tareas: tareas o frenadas. gasto: costo o ejecuciones. aprobaciones: aprobadas o rechazadas. Sin ella, la primera de la vista. |
por | agente · columna · dia · semana | Cómo se agrupa: agente, columna (sólo tareas), dia o semana. Sin él, el total. |
periodo | hoy · ayer · esta_semana · semana_pasada · este_mes · mes_pasado · ultimos_7_dias · ultimos_30_dias · este_trimestre · este_anio · todo | Qué período. Por defecto este_mes. |
agente_id | string | Só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.
| Argumento | Tipo | Qué es |
|---|---|---|
intencion | string | Qué querés hacer, en castellano y con tus palabras. Se busca por palabras en nombre, descripción y área. |
area | empezar · agentes · evaluaciones · equipos · copilotos · trabajo · conexiones · canales · automatizaciones · webhooks · datos · consolas · conocimiento · consumo | Limita 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. |
limite | number | Cuá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.
| Argumento | Tipo | Qué es |
|---|---|---|
nombre (requerido) | string | El nombre exacto de la herramienta, como lo devuelve buscar_herramientas. |
argumentos | object | Los 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.
| Argumento | Tipo | Qué es |
|---|---|---|
nombre (requerido) | string | El nombre exacto de la herramienta, como lo devuelve buscar_herramientas. |
argumentos | object | Los 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.
| Argumento | Tipo | Qué es |
|---|---|---|
nombre (requerido) | string | Cómo se lo va a llamar en la pantalla. Corto y humano. |
clave | string | Clave 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) | string | Escrita EN SEGUNDA PERSONA, dirigida al agente: qué hace, en qué orden, cuándo frena y pide aprobación, y qué no debe hacer nunca. |
conocimiento | string | Lo que necesita saber del negocio. Vacío si no aplica. |
como_se_verifica | string | Qué 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_relectura | boolean | true 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_loop | siempre · excepciones · solo_irreversible | Cuá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. |
verificacion | completa · relectura · muestreo · ninguna | Qué 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_muestreo | integer | Sólo con verificacion=muestreo: porcentaje de tareas que se releen (1–99). Default 20. |
herramientas | lista | Nombres 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_desconocidas | boolean | true para crearlo igual, sin las herramientas que no existan. La respuesta las lista en ignoradas_porque_no_existen. Por defecto false. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
mensaje (requerido) | string | Lo que le decís al Constructor, en lenguaje natural. Hasta 4000 caracteres. |
sesion | string | La sesion que devolvió el turno anterior. Sin ella, arranca una charla nueva. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es | |
|---|---|---|---|
agente_id (requerido) | string | El id que devolvió crearagente o listaragentes. | |
nombre | string | Sólo si querés renombrarlo. | |
instruccion | string | Reemplaza la instrucción entera, en segunda persona. No se concatena a la anterior. | |
conocimiento | string | Reemplaza el conocimiento entero. | |
como_se_verifica | string | Reemplaza 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_relectura | boolean | true para guardar igual un criterio que ninguna lectura de la caja puede releer. Por defecto false. | |
modo | libre · con_controles · regulado | Los 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_loop | siempre · excepciones · solo_irreversible | Cuá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. | |
verificacion | completa · relectura · muestreo · ninguna | Qué 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_muestreo | integer | Sólo con verificacion=muestreo: porcentaje de tareas que se releen (1–99). Default 20. | |
herramientas | lista | Reemplaza 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_desconocidas | boolean | true 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. | |
activo | boolean | false 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. | |
nivel | shadow · assisted · delegated · gated_auto | Nivel 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_usd | number | null | Monto 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_usd | number | Presupuesto duro de modelo por tarea, en USD (mayor que cero). Subirlo exige técnico o admin. | |
reparte_trabajo | boolean | true 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_max | number | Cuá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_max | number | Cuántas tareas hijas puede crear de una vez (1 a 20, por defecto 8). Subirlo exige técnico o admin. | |
desplegar_hasta | staging · prod | Ademá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. | |
nota | string | Sólo con desplegar_hasta: por qué se promueve. Queda en el historial de despliegues. | |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El agente, de listar_agentes. |
hasta | staging · prod | Hasta dónde subir: «staging» (preproducción) o «prod». Recorre los escalones que falten. |
desde | string | Opcional (compatibilidad): «dev» o «staging». Sin hasta, sube UN escalón desde ahí, como antes. |
nota | string | Por qué se promueve. Opcional; queda en el historial de despliegues. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
estado | pendiente · aprobada · rechazada · cancelada | Sólo las de este estado. Por defecto, todas. |
agente_id | string | Sólo las de este agente. |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
promocion_id (requerido) | string | El pedido, de listar_promociones o de promover_agente. |
nota | string | Qué se miró para firmar. Opcional; queda en el historial. |
clave_de_pedido | string | Tu 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ó.
| Argumento | Tipo | Qué es |
|---|---|---|
promocion_id (requerido) | string | El pedido, de listar_promociones. |
motivo (requerido) | string | Por qué no sale. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El agente, de listar_agentes. |
ambiente (requerido) | dev · staging · prod | Dónde volver. |
version (requerido) | number | A qué versión volver, de metricas_por_version o historial_del_agente. |
motivo (requerido) | string | Por qué se vuelve. Obligatorio; queda en el historial de despliegues. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El 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.
| Argumento | Tipo | Qué es | |
|---|---|---|---|
modo | libre · con_controles · regulado | El modo de control de la organización. Libre es el de nacimiento: los controles se prenden. | |
aplicar_a_actuales | boolean | Con modo: true para ponerles sus diales también a los agentes que ya existen. Por defecto false: sólo los nuevos. | |
cuatro_ojos | boolean | Si la promoción a producción exige dos personas. | |
ventana | object | null | {dias, desde, hasta} o null para quitarla. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
paquete | object | El paquete entero, el JSON de exportar_agente o del archivo del repo. O en su lugar componente. |
componente | string | En 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. |
nombre | string | Opcional, con componente: el nombre que va a tener el agente. |
agente_id | string | Opcional: a qué agente existente aplicarle el paquete. Sin esto se crea uno nuevo. |
clave | string | Clave 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_faltantes | boolean | true: importar aunque falten herramientas, y reportarlas. Por defecto falla. |
nota | string | Por qué se importa (el commit, el PR). Opcional; queda en la auditoría. |
clave_de_pedido | string | Tu 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).
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
clave (requerido) | string | La 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
trabajo (requerido) | string | La clave del trabajo, de listar_trabajos. |
preguntar_todo | boolean | true: 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. |
meta | number | Opcional: 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El agente, de listar_agentes. |
lote | number | Cuántos casos correr, de los habilitados y del más viejo al más nuevo (1 a 100). |
casos | lista | Sólo estos casos, por id de listar_casos. Los deshabilitados se saltean. |
ambiente | dev · staging · prod | Dónde corre. Por defecto prod, como el ensayo de siempre; para iterar la instrucción conviene dev. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
clase | agente · conexion · fuente | Qué se traspasa. Por defecto agente. |
objeto_id (requerido) | string | El id del agente (listaragentes), la conexión (listarherramientas) o la fuente (listar_fuentes). |
a_usuario (requerido) | string | El id de la persona que recibe, de listar_equipo o quien_soy. |
motivo (requerido) | string | Por qué; queda en el historial. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente, de listar_agentes. |
confirmar (requerido) | string | El nombre del agente, tal cual lo devuelve listar_agentes. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
de_usuario (requerido) | string | Quién entrega. |
a_usuario (requerido) | string | Quién recibe: admin, técnico o desarrollador con asiento vigente. |
motivo (requerido) | string | Por qué; queda en el historial. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
clase | agente · conexion · fuente | Sólo los traspasos de esa clase de objeto. |
objeto_id | string | Sólo los traspasos de ese objeto. |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
orden | verificadas · discrepancias · costo_por_tarea · crecimiento | Por qué ordenar: verificadas, discrepancias, costoportarea o crecimiento. Por defecto verificadas, como la pantalla. |
dias | number | Cuá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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente, de agentes. |
dias | number | Ventana 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.
| Argumento | Tipo | Qué es | ||||
|---|---|---|---|---|---|---|
agente_id (requerido) | string | El id del agente. | ||||
corte | string | todas \ | abiertas \ | espera \ | discrepancia \ | cerradas. Por defecto todas. |
limite | number | Cuá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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente. |
horas | number | Ventana 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El agente, de listar_agentes. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El agente, de listar_agentes. |
titulo (requerido) | string | Qué prueba este caso, en una línea. |
entrada (requerido) | object | Los datos con los que entra el agente: lo mismo que pediría pedir_tarea. |
esperado | lista | Aserciones 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_esperadas | lista | Herramientas que el agente tiene que usar. |
herramientas_prohibidas | lista | Herramientas que no puede tocar. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El agente, de listar_agentes. |
solo_habilitados | boolean | Sólo los que entrarían en un ensayo. |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
caso_id (requerido) | string | El caso, de listar_casos. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
caso_id (requerido) | string | El caso, de listar_casos. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente, de listar_agentes. |
entrada | object | Los datos que el agente declara en su formulario. |
titulo | string | Qué se prueba, en una línea. Opcional. |
ambiente | dev · staging | Dónde corre. Por defecto dev. |
presupuesto_usd | number | Tope de esta corrida en dólares. Sólo puede ser menor que el del agente. |
max_turnos | number | Máximo de turnos del modelo. Sólo puede ser menor que el del agente; techo 50. |
espera_s | number | Cuánto esperar el cierre, en segundos (5 a 120). Por defecto 60. |
en_seco | boolean | Corrida 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
proyecto_id | string | El id del proyecto. O repo. |
repo | string | El repositorio del proyecto, owner/nombre. O proyecto_id. |
nivel (requerido) | shadow · assisted · delegated · gated_auto | El nivel nuevo. |
motivo | string | Opcional: por qué, para la auditoría. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es | |
|---|---|---|---|
clave (requerido) | string | Clave estable del equipo, única en la organización («redes»). | |
nombre (requerido) | string | Cómo se lo va a llamar en la pantalla. | |
lider_agente_id (requerido) | string | El agente que recibe el pedido y reparte. | |
presupuesto_arbol_usd | number | null | Techo 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_max | number | Niveles de reparto (1 a 10, por defecto 2). | |
hijas_max | number | Hijas por reparto (1 a 20, por defecto 6). | |
activo | boolean | false apaga el equipo: no se le pueden pedir tareas nuevas. | |
miembros | lista | Los 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
equipo (requerido) | string | La 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.
| Argumento | Tipo | Qué es |
|---|---|---|
equipo (requerido) | string | La 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.
| Argumento | Tipo | Qué es |
|---|---|---|
paquete (requerido) | object | El paquete, como lo devuelve exportar_equipo o como está en el bloque equipo: de yorobot.yaml. |
sin_faltantes | boolean | true 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | La tarea que se reparte. Es la que va a esperar a las hijas. |
hijas (requerido) | lista | Las 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | La tarea desde la que se pide. Queda como origen del pedido. |
agente_id (requerido) | string | El agente al que se le pide. |
titulo (requerido) | string | De qué se trata, en una línea. |
descripcion (requerido) | string | El pedido completo, autocontenido. Mínimo 30 caracteres. |
bloquea | boolean | Si quien pide no puede seguir sin la respuesta. Por defecto no. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | Cualquier 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | La 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.
| Argumento | Tipo | Qué es |
|---|---|---|
semanal | boolean | false para no programar la vuelta de los lunes. Por defecto, true. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
pregunta (requerido) | string | Qué querés que busque afuera, en una o dos oraciones («qué están haciendo los competidores de VelaFi en cobranzas»). |
clave_de_pedido | string | Tu 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).
| Argumento | Tipo | Qué es |
|---|---|---|
persona | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
persona | string | El correo de otra persona (sólo admin o técnico). Vacío: el tuyo. |
canal | string | portal, app, email, whatsapp, slack, telegram o teams. app avisa al teléfono donde activaste los avisos de la app (app.yorobot.ai → Yo). |
direccion | string | Tu dirección en ese canal. No va con portal ni email (el correo es el de tu usuario). |
hora | string | La hora del briefing, HH:MM en 24 horas. |
zona | string | Tu zona horaria IANA. |
idioma | string | es, en, pt… |
pais | string | Código de dos letras: AR, CL, MX… |
intereses | object | { "temas": ["caja", "competencia"], "evitar": ["fútbol"], "longitud": "corta" }. |
silencio_desde | string | Desde qué hora no te interrumpe tu copiloto (HH:MM, en tu zona). Va con silencio_hasta; los dos en null lo sacan. |
silencio_hasta | string | Hasta qué hora (HH:MM). Puede cruzar la medianoche: 22:00 a 07:00. |
avisos_por_dia | number | Cuántos avisos por día acepta (0 a 20; por defecto 3). Lo que sobra te llega en el briefing. |
vincular | boolean | Devolver el código para vincular el canal. Sólo para tu propio perfil. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
persona (requerido) | string | El correo de la persona. |
agente_id | string | El agente, de listar_agentes. Vacío para sacárselo. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
objetivo_id | string | El 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.
| Argumento | Tipo | Qué es | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
titulo (requerido) | string | El número en tus palabras: «Pipeline calificado de Chile en Q4». | |||||||||||
porque | string | Por qué ese número, en una línea. | |||||||||||
metrica (requerido) | object | Contra 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) | number | La meta, en la unidad de la métrica. | |||||||||||
linea_base | number | Desde dónde se cuenta el avance. Sin ella, la primera medición. | |||||||||||
fecha_meta | string | Para cuándo (AAAA-MM-DD). | |||||||||||
cadencia | diaria · semanal | Cada cuánto lo mide el sistema (por defecto diaria). | |||||||||||
entradas | lista | Hasta 3 métricas que lo mueven: [{ "nombre", "metrica" }]. | |||||||||||
contrametricas | lista | Hasta 2 que no pueden empeorar: [{ "nombre", "metrica", "umbral" }]. | |||||||||||
limites | string | Lo que el copiloto no puede hacer para llegar («no ofrecer descuento arriba de 10 %»). | |||||||||||
agente_id | string | El agente que lo persigue. Sin él, tu copiloto. | |||||||||||
padre_id | string | El objetivo de arriba del que cuelga (opcional), de listar_objetivos. | |||||||||||
guardar | boolean | true lo guarda; sin él es la vista previa (mide y no guarda). | |||||||||||
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
objetivo_id | string | El id, de listar_objetivos. Sin él, tu North Star. |
valor | number | Sólo para uno de carga manual: el número de hoy. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
objetivo_id | string | El id, de listar_objetivos. Sin él, tu North Star. |
pausar | boolean | true (por defecto) lo pausa; false lo reanuda. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
objetivo_id | string | Tu North Star, de listar_objetivos. Sin él, el tuyo. |
despertadores | lista | Hasta 6; reemplaza los que había. [] los saca. |
escalon | investigar · borrador · piloto | Qué hace cuando se despierta. |
clave_de_pedido | string | Tu 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).
| Argumento | Tipo | Qué es |
|---|---|---|
fecha | string | AAAA-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).
| Argumento | Tipo | Qué es |
|---|---|---|
prendido | boolean | false la apaga; true la prende. |
hora | string | HH:MM, en tu zona (por defecto 02:00). |
tope_usd | number | Lo que puede gastar una noche (por defecto US$ 0,50). |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
estado | propuesta · activa · todas | Cuáles (por defecto todas). |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
memoria_id (requerido) | string | El id del aprendizaje. |
contenido | string | Cómo querés que lo recuerde, si no tal cual. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
memoria_id (requerido) | string | El id del aprendizaje. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id | string | El id del agente, de listar_agentes. Uno de los dos: agente_id o equipo. |
equipo | string | La 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) | string | Qué se le pide, en una línea. |
entrada | object | Los datos que el agente declara en su formulario. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es | |
|---|---|---|---|
agente_id (requerido) | string | El id del agente, de listar_agentes. | |
pregunta | string | Lo que se le pregunta, en lenguaje natural. | |
historia | lista | Turnos anteriores de esta conversación, si los hay, en orden: {de: "persona" \ | "agente", texto}. La pregunta va aparte. |
solo_lectura | boolean | Para un agente que también escribe: contestar sólo con sus lecturas. Lo que escribe no se ejecuta nunca por acá. | |
sujeto | string | De parte de quién se pregunta (la empresa, el cliente). El tope diario se cuenta contra esto; si falta, contra el agente. | |
espera_s | number | Cuánto esperar la respuesta, en segundos (5 a 60). Por defecto 45. | |
consulta_id | string | Para 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente, de listar_hilos o listar_agentes. |
antes | string | Para la página anterior: el cuando (ISO) del primer item que ya tenés. |
limite | number | Cuá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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente, de listar_hilos o listar_agentes. |
texto (requerido) | string | Lo que le escribís, en lenguaje natural. Hasta 4000 caracteres. |
como_tarea | boolean | Mandarlo directo como tarea, sin charla: lo que escribís es el pedido. |
clave_de_pedido | string | Tu 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).
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El agente, de listar_hilos o listar_agentes: el archivo queda en tu conversación con él. |
titulo (requerido) | string | El título del documento. |
bloques (requerido) | lista | Hasta 3 bloques de datos, como los del chat. |
texto | string | Un párrafo que va arriba de los bloques. Opcional. |
incluir_contenido | boolean | Devolver también el PDF en base64 (hasta 2 MB). |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
recordatorio_id (requerido) | string | El id, de listar_recordatorios. |
pausar | boolean | true (por defecto) lo pausa; false lo reanuda. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
recordatorio_id (requerido) | string | El id, de listar_recordatorios. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id | string | El agente. Obligatorio si no se da equipo_id ni registro_id. |
equipo_id | string | Un 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_id | string | Un registro de Datos: sólo lo que los agentes hicieron sobre él. Si se da, agente_id se ignora. |
clase | string | Sólo hechos de esta clase (una o varias separadas por coma): tarea, modelo, herramienta, freno, verificacion, espera, mensaje, llamada, registro, cierre. |
herramienta | string | Sólo hechos de esta herramienta. |
solo_errores | boolean | Sólo lo que salió mal o se frenó. |
tarea_id | string | Sólo lo de esta tarea. |
busca | string | Una palabra del título o el detalle. |
limite | number | Cuántos traer por página (1 a 100). Por defecto 50. |
desde | number | Desde 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id | string | Sólo las de este agente. |
estado | string | Sólo las que están en este estado: new, dispatched, running, verified, inreview, approved, merged, needshuman, rejected o rehearsed. |
columna | pendiente · trabajando · te_espera · frenada · hecho | Sólo las de esta columna. |
ambiente | dev · staging · prod | Sólo las de este ambiente. |
abiertas | boolean | Sólo las que todavía se mueven. |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | El id de la tarea a repetir. |
clave_de_pedido | string | Tu 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á.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | La tarea que espera la respuesta. |
respuesta (requerido) | string | La respuesta, en una línea (hasta 1.000 caracteres). |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | La tarea que esperaba la herramienta o que no terminó. |
clave_de_pedido | string | Tu 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).
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | La tarea retenida. |
resultado (requerido) | no_salio · salio · a_medias | Qué pasó con lo pedido. |
evidencia (requerido) | string | Qué se miró y qué se vio («revisé enviados y el mail no está»). Al menos 20 caracteres. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id | string | La tarea, de aprobaciones_pendientes. |
promocion_id | string | O la promoción, de listar_promociones. |
tarea_ids | lista | O 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. |
nota | string | Opcional: qué se miró, para que la persona lo lea en el enlace (sólo de a una). |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id | string | La tarea, de aprobaciones_pendientes. |
promocion_id | string | O la promoción, de listar_promociones. |
motivo (requerido) | string | Por qué no sale. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
dias | number | Ventana 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | El 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ó.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | El id de la tarea. |
limite | number | Cuá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.
| Argumento | Tipo | Qué es |
|---|---|---|
tarea_id (requerido) | string | El 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) };
| Argumento | Tipo | Qué es |
|---|---|---|
nombre (requerido) | string | En minúsculas y guión bajo, como una herramienta: calcular_envio. |
descripcion (requerido) | string | Qué hace y qué devuelve: es lo que lee el agente para decidir cuándo llamarla. |
parametros | lista | Los argumentos que manda el agente, como en crear_herramienta: { nombre, tipo, requerido, descripcion }. Llegan juntos en entrada. |
codigo (requerido) | string | El cuerpo de la función: recibe entrada y hace return del resultado. Hasta 20.000 caracteres. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
nombre (requerido) | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
nombre (requerido) | string | Cómo la llama el agente. Minúsculas y guiones bajos: es el nombre MCP. Ej: consultar_movimientos. |
descripcion (requerido) | string | Para qué sirve, dicho PARA EL MODELO: es lo que decide si la usa bien y cuándo. |
metodo | string | GET, POST, PUT, PATCH o DELETE. Por defecto GET. |
url (requerido) | string | URL 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. |
cabeceras | object | Cabeceras 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. |
parametros | lista | Qué 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"] } }. |
reemplazar | boolean | true 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) | string | read = sólo lee. write = cambia algo reparable. destructive = irreversible, y entonces pide firma humana SIEMPRE. Ante la duda, el más alto. |
lectura_por_post | boolean | true 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. |
secreto | string | Nombre (kind) de la credencial del sobre que usa. Vacío si no necesita ninguna. |
en_cuarentena | boolean | true 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_pedido | string | Tu 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).
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
nombre (requerido) | string | Nombre del servidor en la organización (p. ej. «hubspot»). Único; repetirlo actualiza. |
url (requerido) | string | La URL del endpoint MCP (https://…/mcp). |
credencial | string | Opcional: el nombre de la credencial cargada con cargar_credencial que este servidor usa. |
cabecera | string | Opcional: la cabecera donde va la credencial. Por defecto Authorization. |
formato | string | Opcional: cómo se escribe la cabecera; {secreto} se reemplaza en el puente. Por defecto Bearer {secreto}. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
modo (requerido) | previsualizar · confirmar | Primero previsualizar; confirmar con lo que eligió la persona. |
tipo (requerido) | supabase · openapi · mcp | Qué se conecta. |
nombre (requerido) | string | Cómo se llama la conexión (p. ej. «Reservas»). Es el prefijo de las herramientas. |
url (requerido) | string | supabase: la del proyecto (https://<ref>.supabase.co); openapi: la del documento; mcp: la del endpoint. |
llave_de_lectura | string | supabase: la llave secreta, SÓLO para leer el esquema; no se guarda. openapi: si el documento pide una. |
llave_publica | string | supabase, opcional: la publicable (sbpublishable… o anon), que va en apikey. |
credencial | string | confirmar: con qué se autentican las herramientas (supabase: el JWT del rol mínimo). Sellada; no vuelve. |
cabecera | string | mcp, opcional: en qué cabecera va la credencial. Por defecto Authorization: Bearer. |
operaciones | lista | confirmar: las elegidas, por id o nombre de la previsualización, con su riesgo. |
agentes | lista | confirmar, opcional: agente_id donde habilitarlas. |
probar | boolean | confirmar: false para no probar una lectura al terminar. |
cargar_en_el_portal | boolean | true: 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
aplicacion (requerido) | che-tienda | Qué aplicación: che-tienda. |
tienda | string | Opcional: 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
vinculo_id (requerido) | string | El vinculo_id de listaraplicacionesconectadas. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
herramienta (requerido) | string | El nombre o el id, de listar_herramientas o de conectar_base. |
argumentos | object | Los argumentos de la lectura (p. ej. { "limit": "3" }). Vacío si no lleva. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
servidor_id (requerido) | string | El servidor, de listarservidoresmcp. |
clave_de_pedido | string | Tu 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).
| Argumento | Tipo | Qué es |
|---|---|---|
servidor_id | string | El servidor, de listarservidoresmcp: se mira su último descubrimiento. |
encargo_id | string | O 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.
| Argumento | Tipo | Qué es |
|---|---|---|
servidor_id (requerido) | string | El servidor, de listarservidoresmcp (conectado sin credencial). |
scope | string | Opcional: los permisos a pedir, separados por espacio. Por defecto los que anuncia el autorizador. |
client_id | string | Opcional: si el autorizador no registra clientes solo, el client_id de una app ya creada. |
client_secret | string | Opcional, junto con client_id: el secreto de esa app. Se sella; no se devuelve ni se registra. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
servidor_id (requerido) | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
servidor_id (requerido) | string | El servidor, de listarservidoresmcp. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
detalle | boolean | true 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. |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
herramienta (requerido) | string | El nombre de la conexión (de listar_herramientas) o su id. |
motivo | string | Opcional: por qué se habilita. Queda en la bitácora junto al motivo de la cuarentena. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
rol | string | orquestador (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. |
modelo | string | El 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente, de listar_agentes. |
herramienta_id (requerido) | string | El id de la herramienta, de listar_herramientas. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente, de listar_agentes. |
herramienta_id (requerido) | string | El id de la herramienta, de listar_herramientas. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
nombre (requerido) | string | El 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) | string | La credencial en claro. Viaja una vez, se sella y no vuelve a salir. |
ambiente | string | prod (por defecto), staging o dev: para qué ambiente vale esta llave. |
forzar | boolean | true 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
nombre (requerido) | string | El nombre MCP de la herramienta a editar (el de listar_herramientas). |
descripcion | string | Nueva descripción para el modelo. |
metodo | string | GET, POST, PUT, PATCH o DELETE. |
url | string | Nueva URL completa; puede llevar {param}. |
cabeceras | object | Cabeceras completas (reemplaza el mapa). Las sensibles citan el secreto entre llaves, nunca el valor. |
parametros | lista | Lista completa de parámetros, con el mismo formato que crear_herramienta. |
riesgo | string | read, write o destructive. |
secreto | string | Nombre de la credencial que usa. Cadena vacía para que no use ninguna. |
reemplazar | boolean | true para aceptar que parametros/cabeceras le saquen algo a lo que hay. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
herramienta_id (requerido) | string | La conexión, de listar_herramientas. |
ambiente (requerido) | dev · staging | Dónde vale la simulación. |
respuesta (requerido) | string | Lo que el agente va a recibir cuando la llame, tal cual (texto o JSON como texto). Máximo 20.000 caracteres. |
clave_de_pedido | string | Tu 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).
| Argumento | Tipo | Qué es |
|---|---|---|
herramienta_id (requerido) | string | La conexión, de listar_herramientas. |
ambiente (requerido) | dev · staging | De qué ambiente sacarla. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
herramienta_id (requerido) | string | La conexión, de listar_herramientas. |
ambiente (requerido) | dev · staging · prod | Para qué ambiente falta. |
motivo (requerido) | string | Para qué la necesitás; lo lee quien la carga. |
clave_de_pedido | string | Tu 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. |
crear_link_de_credencial
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á.
| Argumento | Tipo | Qué es |
|---|---|---|
credencial (requerido) | string | El nombre de la credencial que cita la conexión (erp_token, hubspot_token…). |
ambiente | dev · staging · prod | Para qué ambiente. Por defecto prod. |
para | string | A quién se lo mandás, en palabras: sale en el aviso y en la bitácora. |
horas | number | En cuántas horas vence, de 1 a 168. Por defecto 72. |
reemplaza | boolean | true para que pise una credencial ya cargada con ese nombre en ese ambiente. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
estado | pendiente · cumplido · rechazado · todos | Por defecto pendiente. |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
pedido_id (requerido) | string | El pedido, de listar_pedidos_de_conexion. |
motivo (requerido) | string | Por qué no; lo lee quien pidió. |
clave_de_pedido | string | Tu 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).
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente, de listar_agentes. |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente, de listar_agentes. |
ambiente | string | dev (por defecto), staging o prod: qué versión del agente atiende ese canal. |
nombre | string | Cómo lo llama la organización: «Chat de la web», «Soporte». Opcional. |
dominios | lista | Orí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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente, de listar_agentes. |
tipo (requerido) | string | slack o telegram. |
token (requerido) | string | Con qué sale la respuesta: el bot token. |
secreto | string | Sólo Slack: el Signing Secret, con que se comprueba el webhook. Telegram no lo lleva: lo generamos. |
nombre | string | Cómo lo llama la organización. Opcional. |
ambiente | string | dev (por defecto), staging o prod. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente que va a contestar, de listar_agentes. |
ambiente | string | prod (por defecto: es el número de los clientes de verdad, y contesta la versión publicada), staging o dev. |
clave_de_pedido | string | Tu 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`.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente que va a contestar, de listar_agentes. |
ambiente | string | prod (por defecto: es la cuenta de los clientes de verdad, y contesta la versión publicada), staging o dev. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
canal_id (requerido) | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
canal_id (requerido) | string | El id del canal, de listar_canales. |
nombre | string | El nombre nuevo, o vacío para sacarlo. |
dominios | lista | La lista completa de orígenes permitidos (reemplaza la anterior). Sólo canales de chat. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
canal_id (requerido) | string | El id del canal, de listar_canales. |
mensaje | string | Qué decirle. Por defecto le pide que se presente. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
canal_id (requerido) | string | El id del canal, de listar_canales o abrir_canal. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
canal_id (requerido) | string | El id del canal, de listar_canales. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id | string | Sólo las de este agente. Opcional. |
canal_id | string | Sólo las de este canal, de listar_canales. Opcional. |
estado | string | abierta o cerrada. Sin esto, todas. |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
conversacion_id (requerido) | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
conversacion_id (requerido) | string | El id, de listar_conversaciones. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tipo (requerido) | string | email, whatsapp, slack o teams. |
nombre (requerido) | string | Quién es: «Jefa de guardia», «#aprobaciones». |
direccion (requerido) | string | Correo, número de WhatsApp, URL del incoming webhook de Slack o URL del webhook de Workflows de Teams. |
eventos | lista | Qué avisar: tarea.necesita_firma (por defecto), tarea.terminada, discrepancia.detectada, tarea.firmada, tarea.rechazada. |
agente_id | string | Opcional: sólo lo que le pase a ese agente. |
plantilla | string | Sólo WhatsApp: el nombre de la plantilla aprobada. |
idioma | string | Sólo WhatsApp: el idioma de la plantilla, es_AR por defecto. |
canal | string | Sólo Slack y Teams: cómo se llama el canal, para mostrarlo. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
destinatario_id (requerido) | string | El id, de listar_destinatarios. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
destinatario_id (requerido) | string | El id, de listar_destinatarios. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
destinatario_id (requerido) | string | El id, de listar_destinatarios. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
destinatario_id (requerido) | string | El id, de listar_destinatarios. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
nombre (requerido) | string | Cómo se llama la automatización en la pantalla. Corto y humano. |
clave | string | Clave 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_id | string | El agente que atiende cada disparo: el id que devolvió crearagente o listaragentes. Uno de los dos: agente_id o equipo. |
equipo | string | La 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) | string | El título de la tarea que crea cada disparo. Fijo: el payload del disparo viaja aparte, como entrada de la tarea. |
descripcion | string | Qué tiene que hacer la tarea, si el título solo no alcanza. Opcional. |
entrada | object | Datos fijos que acompañan cada disparo. El payload del webhook se suma solo: esto es para lo que no cambia. |
concurrencia | string | Qué 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. |
caja | string | Con 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
rutina_id (requerido) | string | El id que devolvió crearrutina o listarrutinas. |
nombre | string | Nuevo nombre visible. Opcional. |
titulo | string | Nuevo título de la tarea que crea cada disparo. Opcional. |
descripcion | string | Nueva descripción. Opcional; vacío la borra. |
entrada | object | Nueva entrada fija; reemplaza la anterior entera. Opcional. |
concurrencia | string | coalesceifactive, skipifactive o always_enqueue. Opcional. |
caja | string | Id o nombre exacto de una caja de listar_cajas; la palabra «completa» vuelve a la caja completa del agente. Opcional. Alias: perfil. |
disparador_id | string | Sólo para cambiar el cron: el id del disparador de reloj, de listar_rutinas. |
cron | string | Sólo con disparador_id: los cinco campos nuevos (min hora día mes díasemana). |
zona | string | Sólo con disparador_id: zona horaria IANA nueva. Opcional; sin ella se conserva la que tiene. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
rutina_id (requerido) | string | El id que devolvió crearrutina o listarrutinas. |
tipo (requerido) | string | reloj, webhook, api u odoo. |
cron | string | Sólo para reloj: cinco campos (min hora día mes díasemana), evaluados en zona. |
zona | string | Sólo para reloj: zona horaria IANA. Por defecto UTC. |
modo | string | Só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_seg | number | Sólo para webhook: ventana anti-replay en segundos, entre 30 y 3600. Por defecto 300. |
modelo | string | Sólo para odoo: el modelo que se mira, p. ej. account.move. |
dominio | lista | Sólo para odoo: tripletas de Odoo; "{{hoy}}" es la fecha del día. Factura vencida: [["movetype","=","outinvoice"],["paymentstate","in",["notpaid","partial"]],["invoicedatedue","<","{{hoy}}"]]. |
cada_min | number | Sólo para odoo: cada cuántos minutos mira, mínimo 5. Por defecto 15. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
rutina_id (requerido) | string | El id que devolvió crearrutina o listarrutinas. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
rutina_id (requerido) | string | El id que devolvió crearrutina o listarrutinas. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
rutina_id (requerido) | string | El id que devolvió crearrutina o listarrutinas. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
version | string | El sha, de 7 a 40 hex. Opcional: sin él, la versión que corre el portal. |
worker_id | string | Sólo este worker (id de listar_workers). Opcional: sin él, todos los de la organización. |
nota | string | Por qué se despliega. Opcional; queda en la actividad. |
clave_de_pedido | string | Tu 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á.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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á.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
rutina_id (requerido) | string | El id de la rutina, de listar_rutinas. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
webhook_id (requerido) | string | El id del webhook (listar_webhooks). |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
entrega_id (requerido) | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
entrega_id (requerido) | string | El id de la entrega (listarentregasde_webhook). |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
webhook_id (requerido) | string | El id del webhook (listar_webhooks). |
evento | string | Qué evento simular. Por defecto tarea.terminada. Cualquiera de los eventos de aviso (ver /docs o listar_webhooks). |
clave_de_pedido | string | Tu 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).
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
clave (requerido) | string | La clave de la entidad («lead», «repartidor»). Minúsculas, números y guión bajo. |
nombre | string | Cómo se lee en la pantalla («Lead», «Repartidor»). Si falta, se usa la clave. |
campos (requerido) | lista | Los campos, en orden. Entre 1 y 40. |
estados | lista | El ciclo de vida, en orden; el primero es el inicial. Hasta 20. Omitilo si la entidad no tiene ciclo. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
entidad (requerido) | string | La clave de la entidad, de listar_entidades. |
estado | string | Sólo los que están en este estado. |
busca | string | Una parte de la clave natural (un mail, un número de pedido). |
campo | string | Un campo de la entidad para filtrar por igualdad. Va con valor. |
valor | object | El valor exacto de campo (texto, número o booleano). |
filtros | lista | Hasta 6, y se cumplen todos: [{"campo": "vigenciahasta", "op": "<", "valor": "2027-03-01"}, {"campo": "renovacionautomatica", "op": "=", "valor": false}]. |
limite | number | Cuántos traer por página (1 a 200). Por defecto 50. |
desde | number | Desde 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.
| Argumento | Tipo | Qué es |
|---|---|---|
registro_id | string | El id del registro, de consultar_registros. |
entidad | string | La clave de la entidad, si se busca por clave natural. |
clave | string | La 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.
| Argumento | Tipo | Qué es |
|---|---|---|
entidad (requerido) | string | La clave de la entidad. |
clave (requerido) | string | La clave natural del registro. |
datos (requerido) | object | Los campos, sólo los declarados por la entidad. |
estado | string | El estado al que pasa. Opcional. |
clave_de_pedido | string | Tu 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ó.
| Argumento | Tipo | Qué es |
|---|---|---|
entidad (requerido) | string | La clave de la entidad. |
filas (requerido) | lista | Hasta 100. Cada una: { clave, datos, estado? }. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente. |
plantilla (requerido) | string | La 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
clave (requerido) | string | La clave de la consola, que es su URL. |
borrador | boolean | Ver 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.
| Argumento | Tipo | Qué es |
|---|---|---|
clave (requerido) | string | Minúsculas y guiones, empieza con letra: es la URL («mesa-de-entradas»). |
agente_id | string | El agente dueño. Obligatorio si la consola es nueva; de él salen las herramientas autorizadas. |
titulo (requerido) | string | El encabezado que lee la persona que opera. |
subtitulo | string | Una línea de contexto. Vacío si no aporta. |
bloques (requerido) | lista | La consola misma, en orden de arriba hacia abajo. |
segmentar | object | Opcional: { campo, etiqueta? } para partir la consola entera por un campo (centro, sucursal, zona). |
clave_de_pedido | string | Tu 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ó.
| Argumento | Tipo | Qué es |
|---|---|---|
clave (requerido) | string | La clave de la consola. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
clave (requerido) | string | La clave de la consola. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es | |||
|---|---|---|---|---|---|
estado | string | propuesta \ | activa \ | suspendida \ | jubilada, o varias separadas por coma. Por defecto propuesta,activa. |
agente_id | string | Sólo la memoria de ese agente. Vacío trae también la de la organización (el piso compartido). | |||
limite | number | Cuántas traer. Por defecto 25, máximo 100. | |||
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. | |||
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id | string | De qué agente es. Vacío = de la organización, el piso que comparten todos. |
tipo | string | hecho (un dato del negocio), regla (una política de la casa) o leccion (lo que salió mal una vez). Por defecto leccion. |
trigger (requerido) | string | Cuándo aplica, en una línea: «cuando el pedido no trae número de socio». |
contents (requerido) | string | Qué hacer, en imperativo y corto. Es lo que va a leer el modelo. |
proyecto_id | string | Opcional: la limita a las tareas de ese proyecto. |
evidencia_tarea_id | string | La tarea de la que sale, si sale de una. Es el link a la evidencia. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
memoria_id (requerido) | string | El id de la memoria, de listar_memorias. |
agente_id | string | Contra qué agente medir. Obligatorio para una memoria de la organización, que no tiene dueño. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
memoria_id (requerido) | string | El id de la propuesta, de listar_memorias. |
decision (requerido) | string | aceptar o descartar. |
trigger | string | Sólo al aceptar: reemplaza el «cuándo aplica». Vacío deja el propuesto. |
contents | string | Sólo al aceptar: reemplaza el «qué hacer». Vacío deja el propuesto. |
motivo | string | Sólo al descartar: por qué no entra. Queda en la constancia. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id | string | Opcional: el id de un agente, para saber cuáles tiene puestas. |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
cuerpo (requerido) | string | El SKILL.md entero, con su frontmatter ---. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El id del agente, de listar_agentes. |
skill_id (requerido) | string | El id de la skill, de listar_skills. |
puesta | boolean | true la pone, false la saca. Por defecto true. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
documento_id (requerido) | string | El id del documento, de listar_fuentes. |
version_id | string | Opcional: además, los fragmentos de esa versión. |
citas | boolean | Traer 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.
| Argumento | Tipo | Qué es |
|---|---|---|
documento_id | string | Para agregar una versión a un documento que ya existe. Vacío crea uno nuevo. |
titulo | string | Cómo se llama. Obligatorio si es nuevo. |
resumen | string | Cuándo usarlo, en una línea. Obligatorio si es nuevo: es lo que el agente lee en el índice para decidir si lo abre. |
alcance | string | tenant (todos los agentes), proyecto (los de ese proyecto) o agente (sólo los que lo tengan habilitado). Por defecto tenant. |
proyecto_id | string | Obligatorio si el alcance es proyecto. |
guardar_original | boolean | Guardar el archivo además del texto. Por defecto false: el default seguro es el que no deja el original en la base. |
texto | string | El cuerpo, en Markdown o texto plano. |
contenido_base64 | string | Alternativa a texto para un PDF: el archivo en base64. |
nombre_archivo | string | El 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
nombre (requerido) | string | Cómo se llama, hasta 80 caracteres. |
descripcion | string | Qué hay adentro, en una línea: va en el «cuándo usarlo» de cada documento. |
plantilla | string | parrafos (por defecto), clausulas o filas. |
alcance | string | tenant (todos los agentes, por defecto), proyecto o agente. |
proyecto_id | string | Obligatorio si el alcance es proyecto. |
agente_id | string | Obligatorio si el alcance es agente: el único agente que la lee. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
coleccion | string | La colección, por nombre o por id. Vacío deja los documentos sueltos en el cerebro. |
documentos (requerido) | lista | Hasta 20. |
publicar | boolean | Por defecto true: lo que entra limpio lo ven las corridas enseguida. |
guardar_original | boolean | Guardar el archivo además del texto (por defecto true, para auditar una cita). En false para documentos con datos de personas. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
coleccion (requerido) | string | La colección, por nombre o id. |
plantilla | string | contratos o facturas. Alternativa a esquema. |
esquema | object | { 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_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
coleccion (requerido) | string | La colección, por nombre o id. |
reintentar_fallidas | boolean | Volver a pedir también los que fallaron. Por defecto false. |
clave_de_pedido | string | Tu 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ó.
| Argumento | Tipo | Qué es |
|---|---|---|
a (requerido) | string | El id del primer documento. |
b (requerido) | string | El id del segundo. Puede ser el mismo que a, con otra versión. |
version_a | number | La versión de a. Por defecto, la publicada. |
version_b | number | La 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ó.
| Argumento | Tipo | Qué es |
|---|---|---|
documento_id (requerido) | string | El id del documento. |
version_id (requerido) | string | La versión a publicar, de ver_documento. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
documento_id (requerido) | string | El id del documento. |
motivo | string | Por qué se retira. Queda en la bitácora de la fuente. |
clave_de_pedido | string | Tu 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á.
| Argumento | Tipo | Qué es |
|---|---|---|
documento_id (requerido) | string | El id del documento. |
agente_id (requerido) | string | El id del agente. |
habilitado (requerido) | boolean | true lo habilita, false lo saca. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tipos | lista | Qué 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.
| Argumento | Tipo | Qué es |
|---|---|---|
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
proveedor (requerido) | hubspot · odoo | hubspot u odoo. |
nombre | string | Cómo llamar a la conexión. Por defecto, el nombre del proveedor. |
url | string | Sólo Odoo: la URL https del servidor, p. ej. https://miempresa.odoo.com. |
objetos (requerido) | lista | Qué traer, por clave del catálogo: articulos, tickets, negocios, empresas, notas (HubSpot); articulos, productos, tickets, notas (Odoo). |
limite | number | Tope de registros por objeto y sincronización, de 1 a 2000. Por defecto 200. |
cada_horas | number | Cada cuántas horas sincronizar, de 1 a 720. Por defecto 24. |
alcance | string | tenant, proyecto o agente. Por defecto tenant. |
proyecto_id | string | Obligatorio si el alcance es proyecto. |
publicar | boolean | Publicar solo lo que trae. Por defecto false: queda en borrador. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
fuente_viva_id (requerido) | string | El id, de listar_fuentes_vivas. |
nombre | string | Nuevo nombre. |
url | string | Sólo Odoo: nueva URL https. |
objetos | lista | Nuevos objetos a traer. |
limite | number | Nuevo tope de registros por objeto y sincronización, de 1 a 2000. |
cada_horas | number | Cada cuántas horas sincronizar, de 1 a 720. |
alcance | string | tenant, proyecto o agente. |
proyecto_id | string | Si el alcance es proyecto. |
publicar | boolean | true publica solo lo que trae; false lo deja en borrador. |
activa | boolean | false pausa la conexión: deja de sincronizar hasta reanudarla. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
fuente_viva_id (requerido) | string | El id de la conexión. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
fuente_viva_id (requerido) | string | El id de la conexión. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
consulta (requerido) | string | Qué buscar, con las palabras que usaría el documento. |
coleccion | string | Sólo en esta colección (nombre o id). |
documento_id | string | Sólo adentro de este documento. |
limite | number | Cuá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.
| Argumento | Tipo | Qué es |
|---|---|---|
tope_usd | number | El tope en USD por mes, cero o más. |
sin_tope | boolean | true para sacar el tope. Incompatible con tope_usd. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tope_usd | number | El tope en USD por día, mayor que cero. |
sin_tope | boolean | true para sacar el tope diario. Incompatible con tope_usd. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
agente_id (requerido) | string | El agente, de listar_agentes. |
tope_mes_usd | number | El tope en USD por mes, mayor que cero y no mayor que el tope mensual de la organización. |
sin_tope | boolean | true para sacarle el tope propio (manda sólo el de la organización). Incompatible con tope_mes_usd. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
solo_errores | boolean | true para ver sólo los que fallaron. |
request_id | string | El X-Request-Id de una respuesta, para encontrar ese pedido. |
canal | string | api o mcp. Sin esto, los dos. |
limite | number | Cuántas traer. Por defecto 25, máximo 100. |
desde | number | Desde qué posición seguir. La respuesta trae siguiente_desde cuando queda más. |
busca | string | Filtra 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.
| Argumento | Tipo | Qué es |
|---|---|---|
tipo (requerido) | string | Qué se cuenta: tareas_humanas, tareas_automaticas, corridas, tareas_de_canal, tareas_de_api o inferencias. |
ventana (requerido) | string | hora o dia, calendario. |
limite | integer | Cuántas entran en la ventana: entero mayor que cero. |
sacar | boolean | true para borrar el techo de ese tipo y ventana. Incompatible con limite. |
clave_de_pedido | string | Tu 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á.
| Argumento | Tipo | Qué es |
|---|---|---|
mes | string | Mes 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.
| Argumento | Tipo | Qué es |
|---|---|---|
clientes (requerido) | lista | Los ids de organización de los clientes (de mi_cartera). |
paquete | object | El paquete entero yorobot/agente@1. O en su lugar componente. |
componente | string | En vez de paquete: la clave de un componente de la biblioteca (listar_componentes). |
nombre | string | Opcional, con componente: el nombre que va a tener el agente en cada cliente. |
sin_faltantes | boolean | true: instalar aunque a un cliente le falten herramientas, y reportarlas. |
nota | string | Por qué se instala. Opcional; queda en la bitácora de cada cliente. |
clave_de_pedido | string | Tu 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.
| Argumento | Tipo | Qué es |
|---|---|---|
cliente (requerido) | string | El id de organización del cliente (de mi_cartera). |
agente_id (requerido) | string | El agente, adentro del cliente. |
desde (requerido) | string | «dev» o «staging». |
nota | string | Opcional; queda en la auditoría. |
clave_de_pedido | string | Tu 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?».
| Argumento | Tipo | Qué es |
|---|---|---|
dias | number | Cuántos días, de 1 a 90. Por defecto 14, como la pantalla. |