tools/list sobre una conexión en vivo es siempre la respuesta autoritativa; esta página documenta el mismo conjunto en una forma que una persona puede leer.
El modelo detrás de los nombres: un espacio de trabajo contiene agentes (los cerebros: conocimiento, imágenes, identidad) y proyectos (los sitios: la dirección pública, la marca, las páginas). Una página vive dentro de un proyecto y nombra al agente que responde en ella. Varias páginas pueden compartir un agente; ese es el punto: un cerebro, varias campañas. La site key del widget también pertenece al agente: incrustar es la superficie de código del cerebro, y no necesita ni proyecto ni página publicada.
Agentes
list_agents
Cada agente del espacio de trabajo con su nombre, su identidad y su política de contenido. Empieza aquí: los ids que devuelve son los que toman create_page y las herramientas de conocimiento.
Sin argumentos. Solo lectura. Permiso: landings:read.
get_agent
Un agente completo: identidad (por quién habla), política de contenido, marcas de tiempo.
Solo lectura. Permiso:
landings:read.
create_agent
Crea un cerebro. Hazlo antes de crear páginas para una audiencia nueva, pero prefiere reutilizar un agente en varias páginas antes que un agente por página: cada agente es un corpus de conocimiento independiente con sus propios vectores y su propio espacio en el plan.
Permiso:
landings:write.
update_agent
Edita el nombre, la identidad o la política de contenido de un agente. Parcial: un campo ausente se deja intacto. Editar la identidad cambia cada página en la que responde este agente.
El campo chrome retirado se rechaza indicando la solución: la barra de navegación y el pie de página pertenecen ahora a la marca del proyecto (set_chrome).
Permiso:
landings:write.
delete_agent
Permiso:
landings:write.
Site keys
create_site_key
Emite la clave pública del widget (wdy_site_…) para un agente: la credencial que el SDK de embed incluye dentro del HTML de un cliente. Identifica al agente y no autoriza nada (la infraestructura anti-abuso y la lista de orígenes permitidos protegen el endpoint público), así que es seguro pegarla en una página. Esta es la única respuesta que lleva la clave completa; los listados muestran un prefijo. El embed no necesita ni proyecto ni página publicada.
Permiso:
landings:write.
list_site_keys
Cada site key de widget en vivo del espacio de trabajo: qué agente incrusta, su prefijo visible (wdy_site_…, nunca la clave completa) y los orígenes que pueden enmarcarla. Úsala para encontrar la clave a rotar, o para comprobar qué orígenes aceptará un embed antes de que un cliente pegue el snippet.
Sin argumentos. Solo lectura. Permiso: landings:read.
rotate_site_key
Emite una clave completa nueva para una site key existente y responde con ella; este es el otro único lugar donde aparece una clave completa. La clave anterior sigue funcionando por 24 horas para que los loaders ya incrustados en las páginas de los clientes no se rompan; vuelve a desplegar el snippet dentro de esa ventana. La rotación conserva el agente y los orígenes permitidos tal como están.
Permiso:
landings:write.
revoke_site_key
Mata una site key de inmediato: el embed que la usa deja de responder en el siguiente turno, sin ventana de gracia (a diferencia de la rotación). La fila se conserva para la traza de auditoría. Úsala cuando una clave se filtró o cuando un embed debe salir de la página de un cliente para siempre; para reemplazar una clave sin corte, usa la rotación.
Permiso:
landings:write.
Proyectos
list_projects
Cada sitio del espacio de trabajo, con su id, su name y su slug, la dirección pública <slug>.wondeya.app que comparte cada página publicada del sitio. Los ids que devuelve son los que toman create_page y list_pages como projectId. La marca, la apariencia y los dominios también pertenecen al proyecto.
Sin argumentos. Solo lectura. Permiso: landings:read o projects:read; cualquiera lo habilita.
create_project
Crea un sitio nuevo: una dirección pública propia, sus propias páginas, su propia marca y sus propios dominios. slug es opcional: omitido, se deriva del nombre, y de cualquier forma una colisión se rechaza con un vecino disponible en errors[], nunca se repara en silencio. Los planes limitan cuántos sitios contiene un espacio de trabajo: por encima del tope esto responde el mismo 402 wondeya.billing.limit_reached que la consola convierte en una vía de actualización de plan. El sitio nace vacío; dale una página con create_page.
Permiso:
projects:write.
update_project
Edita la etiqueta del sitio (lo que muestra la consola) y su infraestructura de SEO: la política de robots.txt, los ids de analítica de terceros y URLs extra del sitemap. SEO describe cómo aparece cada ajuste en el sitio. La dirección pública nunca se mueve aquí: eso es set_project_address, un acto distinto con consecuencias distintas.
Permiso:
projects:write.
regenerate_llms_txt
Reconstruye ahora el llms.txt en inglés del sitio a partir de su información y sus rutas publicadas reales, y lo almacena, servido en <domain>/llms.txt. Los enlaces están fundamentados en rutas reales, así que nunca inventa una página. Tolerante a fallos: sin proveedor de modelo, o ante un rechazo, se conserva el archivo anterior. Devuelve el proyecto actualizado.
Permiso:
projects:write.
set_project_address
Mueve el sitio a una nueva dirección pública. El nombre anterior se convierte en un redirect que redirige con 308 cada ruta a la nueva dirección y sigue reservado (para todos, este sitio incluido) hasta que su dueño lo libere con release_project_address. Idempotente sobre el slug actual; las colisiones se rechazan exactamente igual que create_project.
Permiso:
projects:write.
list_project_domains
Cada nombre en el que responde el sitio: su subdominio, cualquier redirect que dejó atrás un cambio de dirección (con el hostId que toma release_project_address), y sus dominios propios con su desafío de verificación y el estado del certificado.
Solo lectura. Permiso:
landings:read o projects:read.
release_project_address
Elimina un nombre del sitio: el desconectar de la pantalla Dominios. En una fila redirect detiene el 308 y libera el nombre para que cualquiera, incluidos desconocidos, lo reclame; en un dominio propio active desconecta un nombre que está sirviendo actualmente. Destructiva, y deliberadamente bajo el permiso de dominios: eliminar un nombre en vivo es el permiso de esa superficie.
Permiso:
domains:write.
delete_project
Borra el sitio, entero y de verdad: cada página se va con sus filas de host, y la dirección se libera. El agente, su conocimiento, sus imágenes y sus site keys de widget sobreviven; nunca fueron parte del sitio. Borrar el único proyecto está permitido («empezar mi sitio de nuevo»). Responde cuántas páginas se fueron. Destructiva.
Permiso:
projects:write.
Páginas
list_pages
Cada página del espacio de trabajo (o de un sitio, cuando se pasa projectId), de la más nueva a la más antigua, con su estado (draft o published), su path bajo el host del sitio, sus idiomas, el projectId del sitio en el que vive y el agentId del cerebro que responde en ella. Los ids que devuelve son los que toman todas las demás herramientas de página.
Solo lectura. Permiso:
landings:read.
get_page
Una página completa. Úsala para confirmar el resultado de una escritura, por ejemplo que status realmente pasó a published, o que el editorial se lee como fue enviado.
Solo lectura. Permiso:
landings:read.
create_page
Crea una página dentro de un sitio. Nace como borrador y no responde a nadie: crearla no pone nada en línea. Una página agent (la predeterminada) es conversacional: lo que dice en el chat viene de su agente, así que crea el agente primero (o reutiliza uno). Una página document (una política de privacidad, términos) renderiza un body markdown subido, sin agente y sin editorial.
Permiso:
landings:write.
update_page
Edita la configuración de una página (nombre, dirección, qué agente responde en ella, su idioma fuente), su editorial o body, sus metadatos SEO y sus indicaciones de sitemap. Parcial: un campo ausente se deja intacto. Los tipos protegen sus campos: una página agent rechaza body, y una página document rechaza editorial y agentId.
Por quién habla el agente no está aquí; eso es
update_agent, para que editarlo cambie cada página que sirve el agente. Publicar tampoco está aquí. Permiso: landings:write.
publish_page
El único acto que abre una página al mundo: después de él, la página es accesible en su dirección pública y su agente responde a los visitantes. Comprueba primero que el conocimiento esté en ready, porque una página publicada sin nada que decir no responde nada. Una página fuera de / no puede publicarse mientras nada sirva la página principal.
Permiso:
landings:write.
unpublish_page
Saca una página de la superficie pública en la siguiente solicitud. Esta es la herramienta a la que recurrir cuando un agente dice algo incorrecto en nombre del negocio. No se borra nada, y puede volver a publicarse. La página principal no puede retirarse mientras otras páginas del sitio estén publicadas.
Permiso:
landings:write.
delete_page
Permiso:
landings:write.
translate_page
Programa una traducción de los campos editoriales de una página y su portada a todos los idiomas de su sitio que el dueño no haya escrito a mano. (Los textos de presentación del agente no son un campo de la página; se componen y se traducen en el agente, en los idiomas que el propio agente habla.) Solo se toca lo que falta o lo que fue escrito por máquina y quedó desactualizado: un idioma que escribió un humano nunca se sobrescribe, aun cuando la fuente cambió. Responde en cuanto el trabajo se programa, no cuando termina; el texto traducido llega a la página segundos después y el sitio servido se revalida solo. Rellena huecos en vez de sobrescribir, así que es seguro volver a llamarla, al costo de un puñado de llamadas al modelo por cada idioma que falte.
Permiso:
landings:write.
Conocimiento
list_knowledge_sources
Todo lo que el espacio de trabajo le ha enseñado a sus agentes (documentos subidos, URLs rastreadas y afirmaciones curadas), con el status de ingesta de cada fuente, cuántos pasajes produjo, y cualquier error. Sondea esto después de agregar conocimiento: una fuente solo afecta las respuestas una vez que su estado es ready.
Solo lectura. Permiso:
knowledge:read.
upload_knowledge_text
Ingesta un documento escrito como texto o Markdown, como una lista de precios, un FAQ, una descripción de servicio o una política. Se conservan los encabezados, así que ## Pricing se vuelve una sección que la recuperación puede citar.
Responde de inmediato con la fuente en
pending; el parseo, la fragmentación y la indexación ocurren en una cola. Permiso: knowledge:write.
add_knowledge_url
Apunta la base de conocimiento a una página pública. Solo http/https; las direcciones privadas, de loopback y link-local se rechazan, y cada salto de redirección se vuelve a verificar.
Responde con la fuente en
pending; la página se obtiene en una cola, nunca en esta llamada. Permiso: knowledge:write.
upsert_knowledge_claim
Una afirmación es una declaración corta que el negocio aprobó, escrita a mano en ambos idiomas para que nunca se traduzca automáticamente frente a un visitante: una garantía, un precio, un horario de apertura. Prefiérela sobre un documento cuando la redacción exacta importa.
Guardar la reindexa, así que la próxima conversación ya la ve. Permiso:
knowledge:write.
delete_knowledge_source
Responde con lo que se eliminó. Permiso:
knowledge:write.
list_knowledge_topics
La taxonomía de temas gestionada de un agente: cada tema con su slug estable, su título, la description en inglés que orienta de qué temas se nutre una respuesta, si lo escribió el enriquecimiento (auto) o lo editó una persona (manual), y cuánto material hay debajo de él. Un conteo alto de fragmentos es la señal de que un tema creció demasiado amplio como para resumirse bien. Lee esto antes de editar, fusionar o borrar: los slugs que devuelve son los que toman esas herramientas.
Solo lectura. Permiso:
knowledge:read.
update_knowledge_topic
Renombra un tema o reescribe la description en inglés que orienta la selección de temas al momento de responder. Editar cualquiera de los dos campos marca el tema como manual, y el enriquecimiento nunca vuelve a sobrescribirlo. El slug nunca cambia; consolidar dos slugs es una fusión, no un renombrado.
Permiso:
knowledge:write.
merge_knowledge_topics
Pliega un tema dentro de otro: cada fuente y fragmento etiquetado como fromSlug se reetiqueta como intoSlug, luego fromSlug se borra. Es la forma de corregir un enriquecimiento casi duplicado acuñado junto a un tema existente (por ejemplo prices junto a pricing). Ambos slugs deben existir y ser distintos.
El material se reetiqueta, nunca se pierde, pero la herramienta se marca como destructiva (los clientes piden confirmación) porque borrar
fromSlug no tiene deshacer. Permiso: knowledge:write.
delete_knowledge_topic
Elimina un tema de la taxonomía: la fila se borra y el slug se quita de cada fuente y fragmento. El material se conserva (un pasaje que queda sin temas simplemente se vuelve universal, coincidiendo con toda pregunta), así que esto nunca hace que un agente olvide un documento; solo elimina una forma de enrutar hacia él. Para borrar el material en sí, usa delete_knowledge_source.
Responde con cuánto material perdió la etiqueta. Marcada como destructiva (los clientes piden confirmación): quitar el
slug no tiene deshacer, aunque el material se conserve. Permiso: knowledge:write.
probe_retrieval
Ejecuta exactamente la recuperación que ejecuta una conversación real (el mapa de temas determinista más la búsqueda vectorial, fusionados) y responde con los pasajes que el agente habría tenido, sin llamar al modelo. Así se depura una base de conocimiento: haz la pregunta que haría un visitante y observa si vuelve el pasaje correcto. Resultados vacíos significan que el agente todavía no puede responder esa pregunta.
Solo lectura y sin modelo, así que es barato llamarlo a menudo. Permiso:
knowledge:read.
Imágenes
list_assets
Las imágenes que un agente puede mostrar, con la key estable que emite, qué muestra cada una (la descripción que el planificador lee para elegirla), su texto alternativo y su orientación. Una imagen con una descripción vacía nunca será elegida.
Cada
url del resultado está firmada y expira; nunca guardes una. Solo lectura. Permiso: assets:read.
upload_asset
Registra una imagen que un agente puede mostrar. PNG, JPEG, WebP, GIF o AVIF, hasta 8 MiB: los bytes deciden el formato, no el nombre del archivo. El archivo viaja codificado en base64, y el límite aplica a los bytes decodificados. Al subirla, la imagen se describe automáticamente con visión (qué muestra, en inglés, para el planificador).
Permiso:
assets:write.
Marca
get_brand
La marca del proyecto: el logo, su variante oscura, el símbolo, y los archivos de icono que lleva cada página pública (favicon SVG/ICO, el icono apple-touch y los dos iconos PWA). Cada slot indica si fue subido por el dueño o generado a partir de un maestro, y las hints dicen qué vale la pena subir a mano. El resultado también incluye la barra de navegación y el pie de página del sitio: los que escribe set_chrome.
Cada
url del resultado está firmada y expira; nunca guardes una. Solo lectura. Permiso: brand:read.
upload_brand_asset
Almacena un archivo de marca y regenera todo lo que deriva de él. Empieza con logo: a partir de un SVG o un PNG transparente grande se generan los favicons, el icono apple-touch y los iconos PWA; agrega mark (el símbolo solo) si existe, los iconos se leen mejor recortados de él. Los bytes deciden el formato. El SVG debe estar limpio: script, manejadores de eventos o referencias externas se rechazan indicando cada razón.
Un archivo subido nunca es tocado por la regeneración; uno generado se vuelve a derivar cada vez que cambia el maestro. Permiso:
brand:write.
set_chrome
La barra de navegación y el pie de página que comparten todas las páginas del sitio: hasta 6 enlaces de navegación, hasta 4 grupos de pie de página de hasta 8 enlaces cada uno, hasta 8 enlaces sociales, y el nombre legal que muestra la línea de copyright. Los enlaces se validan del lado del servidor; el modelo nunca emite HTML libre ni URLs en una página.
Permiso:
brand:write.
translate_chrome
Programa una traducción de la barra de navegación y el pie de página del sitio (etiquetas de navegación, títulos y etiquetas del pie, el nombre del copyright) a todos los idiomas del sitio cuyos textos el dueño no escribió. La procedencia es por idioma para todo el conjunto: un idioma editado a mano se omite por completo, aun cuando la fuente cambió. Responde en cuanto el trabajo se programa; cada página del sitio se revalida cuando la traducción llega. Una llamada al modelo por cada idioma que falte.
Permiso:
brand:write.
Tema
get_theme
La apariencia del sitio, más el catálogo de valores que pueden escribirse: las tipografías disponibles, los redondeos de esquina permitidos y los valores por defecto. Lee esto antes de set_theme: los colores deben ser hex de 6 dígitos, y las tipografías y los redondeos son claves de esta lista.
El argumento agentId retirado se rechaza con una explicación: los agentes no tienen apariencia; el aspecto pertenece a la marca del proyecto, una por sitio.
Solo lectura. Permiso:
landings:read.
set_theme
Reestiliza el sitio. tokens es un parche parcial que se fusiona sobre el tema vigente, así que enviar solo colors.primary cambia un color y deja el resto. Todas las páginas del sitio cambian juntas; no hay anulaciones por página ni por agente.
Los colores son
#rrggbb y nada más; las tipografías y los redondeos son claves del catálogo; cualquier otra cosa se rechaza con wondeya.theme.invalid. El argumento agentId retirado se rechaza, nunca se reinterpreta. Permiso: landings:write.
Uso
get_usage
Cuánto del producto está usando realmente el espacio de trabajo: cuántas páginas existen y cuántas están publicadas, cuántas fuentes de conocimiento hay por estado de ingesta con los pasajes y tokens que produjeron, y cuántas imágenes están almacenadas y cuántos bytes ocupan.
Sin argumentos. Solo lectura. Permiso: analytics:read.
Útil para responder «qué tan grande es este espacio de trabajo» y para detectar conocimiento atascado en failed o pending.
Un orden de trabajo
Para un agente que construye un sitio desde cero, este orden evita los errores que las herramientas no pueden prevenir por sí solas:list_agents, y luegocreate_agentsi la lista está vacía: un espacio de trabajo nace sin agentes y sin proyectos. Reutiliza un cerebro existente antes que crear uno por página.update_agent: dile por quién habla, y qué acciones y enlaces puede ofrecer.upload_knowledge_text,add_knowledge_url,upsert_knowledge_claim: enséñale.list_knowledge_sources: sondea hasta que las fuentes estén enready.upload_asset: dale algo que mostrar.probe_retrieval: pregunta lo que preguntaría un visitante, y comprueba que vuelve el pasaje correcto.create_site_key: solo si el agente también correrá dentro de un sitio que el negocio ya posee. El widget no necesita página ni publicación; registra los orígenes exactos que pueden enmarcarlo.list_projects, ycreate_projectcuando aún no exista ninguno: el sitio y su dirección pública.create_page: un borrador dentro del sitio; nada es público todavía.update_page: escribe el editorial con el que abre la página.get_theme, y luegoset_theme: reestiliza el sitio con valores del catálogo.publish_page: solo ahora hay algo público.