> ## Documentation Index
> Fetch the complete documentation index at: https://wondeya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Herramientas
> Cada herramienta que expone el servidor MCP de wondeya, qué recibe y qué cuesta
Estas son las herramientas que puede llamar un agente conectado al servidor MCP de wondeya. Cada una ejecuta el mismo comando o consulta que ejecuta la API de la consola, dentro del espacio de trabajo al que está vinculada la conexión, y cada una verifica su permiso en cada llamada.
`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.
| Argumento | |
| - | - |
| `agentId` | Obligatorio. |
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.
| Argumento | |
| - | - |
| `name` | Obligatorio, 1 a 80 caracteres. |
| `identity` | Opcional: `businessName`, `description`, `tone`, hasta 8 `actions` y hasta 16 `links`. Por quién habla el agente; esto es lo que evita que responda como un asistente genérico. |
| `content` | Opcional: `useWorkspaceKnowledge` y `useWorkspaceAssets`, que controlan si también responde desde el pool de todo el espacio de trabajo. |
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`).
| Argumento | |
| - | - |
| `agentId` | Obligatorio. |
| `name`, `identity`, `content` | Opcional. |
Permiso: `landings:write`.
### `delete_agent`
**Destructiva, sin deshacer.** Elimina de forma permanente el agente y todo lo que cuelga de él, en cascada: sus fuentes de conocimiento y sus pasajes indexados, sus imágenes, **y sus site keys de widget**, así que cada embed de este agente deja de resolver. Se rechaza mientras alguna página todavía apunte al agente; reapunta o borra las páginas primero. El conocimiento y las imágenes adjuntos a todo el espacio de trabajo sobreviven. Confirma con una persona antes de llamarla.
| Argumento | |
| - | - |
| `agentId` | Obligatorio. |
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.
| Argumento | |
| - | - |
| `agentId` | Obligatorio. El agente que esta clave incrusta, de `list_agents`. |
| `allowedOrigins` | Obligatorio, hasta 20. Los orígenes exactos que pueden enmarcar el widget (`https://acme.com`): esquema y host, sin ruta, sin comodines; `http:` solo en loopback. Una **lista vacía** significa que el embed se niega a ser enmarcado en cualquier parte hasta que se agreguen orígenes. Un origen que nunca podría funcionar se rechaza indicando su nombre. |
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.
| Argumento | |
| - | - |
| `siteKeyId` | Obligatorio. De `list_site_keys`. |
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.
| Argumento | |
| - | - |
| `siteKeyId` | Obligatorio. De `list_site_keys`. |
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 `.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`.
| Argumento | |
| - | - |
| `name` | Obligatorio. La etiqueta del sitio en la consola. No la dirección. |
| `slug` | Opcional. La dirección pública: minúsculas, dígitos, guiones interiores simples, máximo 40. |
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](/docs/es/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.
| Argumento | |
| - | - |
| `projectId` | Obligatorio. De `list_projects`. |
| `name` | Opcional, 1 a 80 caracteres. |
| `robots` | Opcional: `indexable`, `aiSearch` (permite que los asistentes de IA respondan usando el sitio), `aiTraining` (permite que las empresas de IA entrenen con él), rutas extra en `disallow` (cada una empezando con `/`), y `raw`, un cuerpo de robots completo que reemplaza los interruptores. La línea Sitemap es siempre la canónica, nunca editable. |
| `analytics` | Opcional: `clarityId`, `gtmId`, `metaPixelId`. Una cadena vacía limpia uno. |
| `sitemap` | Opcional: `extraUrls`, rutas del mismo sitio cada una con un `priority` opcional (0 a 1) y `changefreq`. Una lista presente reemplaza toda la lista almacenada. |
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 `/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.
| Argumento | |
| - | - |
| `projectId` | Obligatorio. De `list_projects`. |
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`.
| Argumento | |
| - | - |
| `projectId` | Obligatorio. |
| `slug` | Obligatorio. La nueva dirección. |
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.
| Argumento | |
| - | - |
| `projectId` | Obligatorio. |
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.
| Argumento | |
| - | - |
| `projectId` | Obligatorio. |
| `hostId` | Obligatorio. De `list_project_domains`. |
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.**
| Argumento | |
| - | - |
| `projectId` | Obligatorio. |
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.
| Argumento | |
| - | - |
| `projectId` | Opcional. Acota la lista a un solo sitio. |
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.
| Argumento | |
| - | - |
| `pageId` | Obligatorio. |
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.
| Argumento | |
| - | - |
| `projectId` | Opcional mientras el espacio de trabajo tenga exactamente un proyecto; con varios es obligatorio. |
| `name` | Obligatorio, 1 a 80 caracteres. Interno, se muestra en la consola. |
| `kind` | Opcional, `agent` (predeterminado) o `document`. |
| `agentId` | Opcional mientras el espacio de trabajo tenga exactamente un agente; con varios es obligatorio. Una página `document` no tiene ninguno. |
| `body` | Solo páginas `document`. Markdown por idioma, hasta 100 000 caracteres cada uno; obligatorio en el idioma fuente. Los demás idiomas son del dueño, nunca se traducen automáticamente. |
| `path` | Opcional. La dirección bajo el host del sitio; `/` es la página principal y exactamente una página la tiene. Por defecto es `/` cuando nada sirve todavía la página principal, y de lo contrario una ruta derivada del nombre, deduplicada. |
| `defaultLocale` | Opcional, `es` o `en`. El idioma en que está escrita la página; por defecto es el idioma fuente del sitio. Qué idiomas *sirve* el sitio es una configuración del proyecto, no de la página, y todo lo que dejes sin traducir se completa automáticamente después de cada guardado. |
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`.
| Argumento | |
| - | - |
| `pageId` | Obligatorio. |
| `name`, `path`, `agentId`, `defaultLocale` | Opcional. |
| `editorial` | Opcional, solo páginas `agent`: `badge` (≤60), `title` (≤120), `titleAccent` (una subcadena literal del título, pintada con el color de acento), `description` (≤280). Esto es lo que la página muestra sobre el chat. Cada campo es un objeto por idioma, `` `{ es, en }` ``: un idioma ausente deja intacto su texto almacenado, una cadena vacía quita ese idioma, y lo que no escribes se traduce automáticamente después del guardado. |
| `seo` | Opcional, ambos tipos: `title` (≤60) y `description` (≤160), el texto del resultado de búsqueda y de la tarjeta social, distinto del titular editorial. Objetos por idioma; un campo vacío hereda la página principal del sitio **en vivo**, así que editar la página principal actualiza cada página que la hereda. La imagen social (OG) se sube a través de la consola, no aquí. [SEO](/docs/es/seo) explica el modelo. |
| `sitemap` | Opcional: `priority` (0 a 1) y `changefreq`, indicaciones cosméticas (`null` limpia una), y `sitemapExclude`, el indicador que efectivamente elimina la página del sitemap. |
| `body` | Opcional, solo páginas `document`. Markdown por idioma; una cadena vacía quita un idioma, y el idioma fuente no puede vaciarse. |
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.
| Argumento | |
| - | - |
| `pageId` | Obligatorio. |
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.
| Argumento | |
| - | - |
| `pageId` | Obligatorio. |
Permiso: `landings:write`.
### `delete_page`
**Destructiva, sin deshacer.** Elimina de forma permanente la **página**: la página misma y su registro de host. Su conocimiento, sus imágenes y sus site keys de widget **no** se borran; pertenecen al agente, que puede seguir respondiendo en otras páginas y a través de sus embeds. Usa `delete_agent` para eliminar un cerebro, su corpus y sus site keys. Confirma con una persona antes de llamarla.
| Argumento | |
| - | - |
| `pageId` | Obligatorio. |
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.
| Argumento | |
| - | - |
| `pageId` | Obligatorio. De `list_pages`. |
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`.
| Argumento | |
| - | - |
| `agentId` | Opcional. El id de un agente acota la lista a ese agente; `null` la acota al pool de todo el espacio de trabajo; omite para todo. |
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.
| Argumento | |
| - | - |
| `title` | Obligatorio, hasta 120 caracteres. Qué es el documento. |
| `text` | Obligatorio, hasta 200 000 caracteres. Texto plano o Markdown, escrito en el idioma en que responden las páginas. |
| `topics` | Etiquetas opcionales, hasta 12. |
| `agentId` | Opcional. Omite o `null` para adjuntarlo a todo el espacio de trabajo. |
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.
| Argumento | |
| - | - |
| `url` | Obligatorio, absoluta, hasta 2048 caracteres. |
| `syncTtlMinutes` | Opcional, mínimo 5. Cuánto tiempo antes de volver a obtener la página. |
| `topics` | Etiquetas opcionales. |
| `agentId` | Opcional. |
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.
| Argumento | |
| - | - |
| `sourceId` | Opcional. Omite para crear; pasa el id de una afirmación para reemplazarla. |
| `title` | Obligatorio, hasta 120 caracteres. |
| `claim` | Obligatorio: el texto aprobado en `es` y en `en`, hasta 2000 caracteres cada uno. |
| `topics` | Etiquetas opcionales. |
| `agentId` | Opcional. |
Guardar la reindexa, así que la próxima conversación ya la ve. Permiso: `knowledge:write`.
### `delete_knowledge_source`
**Destructiva, sin deshacer.** Elimina de forma permanente la fuente, sus pasajes indexados y sus vectores, y el archivo almacenado detrás de ella. El agente deja de poder responder a partir de ella en la próxima conversación.
| Argumento | |
| - | - |
| `sourceId` | Obligatorio. |
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.
| Argumento | |
| - | - |
| `agentId` | Opcional. Filtra a un agente (más el pool del espacio de trabajo que lee), pasa `null` para solo el pool, u omite para todo. |
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.
| Argumento | |
| - | - |
| `slug` | Obligatorio. El tema a editar, tal como lo devuelve `list_knowledge_topics`. |
| `title` | Opcional, hasta 120 caracteres. Omite para dejarlo sin cambios. |
| `description` | Opcional, hasta 200 caracteres. Omite para dejarla sin cambios. |
| `agentId` | Opcional. `null` (u omitir) apunta al pool del espacio de trabajo. |
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.
| Argumento | |
| - | - |
| `fromSlug` | Obligatorio. El tema absorbido y luego borrado. |
| `intoSlug` | Obligatorio. El tema superviviente al que se mueven sus etiquetas. |
| `agentId` | Opcional. `null` (u omitir) apunta al pool del espacio de trabajo. |
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`.
| Argumento | |
| - | - |
| `slug` | Obligatorio. El tema a eliminar, tal como lo devuelve `list_knowledge_topics`. |
| `agentId` | Opcional. `null` (u omitir) apunta al pool del espacio de trabajo. |
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.
| Argumento | |
| - | - |
| `query` | Obligatorio, hasta 500 caracteres. Redactada como lo preguntaría un visitante. |
| `topics` | Opcional, hasta 12. Déjalo vacío para probar solo la mitad vectorial. |
| `locale` | Opcional, `es` o `en`. |
| `agentId` | Opcional. Omite para buscar en el pool del espacio de trabajo. |
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.
| Argumento | |
| - | - |
| `agentId` | Opcional. El id de un agente acota la lista; `null` la acota al pool de todo el espacio de trabajo. |
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).
| Argumento | |
| - | - |
| `fileName` | Obligatorio. Se usa como etiqueta y para derivar la `key`, nunca como ruta. |
| `data` | Obligatorio. El archivo, codificado en base64, en crudo, sin el prefijo `data:image/png;base64,`. |
| `key` | Opcional. Id estable en kebab-case que el agente emite, hasta 48 caracteres. Por defecto, un slug del nombre del archivo. |
| `topics` | Opcional, hasta 8 etiquetas. Hazlas coincidir con las usadas en el conocimiento. |
| `agentId` | Opcional. `null` u omitido la adjunta a todo el espacio de trabajo. |
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`.
| Argumento | |
| - | - |
| `projectId` | Opcional. El sitio, de `list_projects`. Omitido, responde el único proyecto del espacio de trabajo; con varios sitios es obligatorio. |
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.
| Argumento | |
| - | - |
| `slot` | Obligatorio. Uno de `logo`, `logoDark`, `mark`, `faviconSvg`, `faviconIco`, `appleTouch`, `icon192`, `icon512`. |
| `data` | Obligatorio. El archivo, codificado en base64, en crudo, sin el prefijo `data:`. |
| `fileName` | Opcional. Solo para mensajes de error, nunca una ruta. |
| `projectId` | Opcional. El sitio, de `list_projects`. Omitido, responde el único proyecto del espacio de trabajo; con varios sitios es obligatorio. |
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.
| Argumento | |
| - | - |
| `chrome` | Obligatorio: `navLinks`, `footerGroups`, `socials`, `legalName`. Se fusiona por lista: una lista que envías reemplaza esa lista, una lista que omites se deja intacta. Cada texto (etiquetas de enlaces, títulos de grupos, el nombre legal) es o bien una cadena simple en el idioma fuente del sitio o un objeto por idioma, `` `{ es, en }` ``; un idioma que omites se traduce automáticamente después del guardado. Los *destinos* de los enlaces se comparten entre idiomas; solo el texto es por idioma. Un enlace de navegación admite un `variant` opcional: `link` es texto, `primary` y `secondary` son botones (solo barra de navegación). |
| `projectId` | Opcional. El sitio, de `list_projects`. Omitido, responde el único proyecto del espacio de trabajo; con varios sitios es obligatorio. |
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.
| Argumento | |
| - | - |
| `projectId` | Opcional. El sitio, de `list_projects`. Omitido, responde el único proyecto del espacio de trabajo; con varios sitios es obligatorio. |
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.
| Argumento | |
| - | - |
| `projectId` | Opcional. El sitio, de `list_projects`. Omitido, responde el único proyecto del espacio de trabajo. Un id ajeno o desconocido resuelve los valores por defecto de wondeya con `customized: false`. |
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.
| Argumento | |
| - | - |
| `tokens` | Obligatorio. Un parche parcial de `colors`, `typography` y `radius`; `null` en lugar de un parche limpia la personalización y devuelve el sitio a los valores por defecto de wondeya. |
| `projectId` | Opcional. El sitio, de `list_projects`. Omitido, responde el único proyecto del espacio de trabajo; con varios sitios es obligatorio. |
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:
1. `list_agents`, y luego `create_agent` si 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.
2. `update_agent`: dile por quién habla, y qué acciones y enlaces puede ofrecer.
3. `upload_knowledge_text`, `add_knowledge_url`, `upsert_knowledge_claim`: enséñale.
4. `list_knowledge_sources`: sondea hasta que las fuentes estén en `ready`.
5. `upload_asset`: dale algo que mostrar.
6. `probe_retrieval`: pregunta lo que preguntaría un visitante, y comprueba que vuelve el pasaje correcto.
7. `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.
8. `list_projects`, y `create_project` cuando aún no exista ninguno: el sitio y su dirección pública.
9. `create_page`: un borrador dentro del sitio; nada es público todavía.
10. `update_page`: escribe el editorial con el que abre la página.
11. `get_theme`, y luego `set_theme`: reestiliza el sitio con valores del catálogo.
12. `publish_page`: solo ahora hay algo público.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.