AI Agent

AI Agent convierte una conversación en ediciones propuestas en toda tu documentación. Pide un cambio y leerá tu contenido, determinará todo lo que el cambio afecta y dejará las ediciones preparadas para que las revises.

Una sola solicitud puede cambiar muchas páginas a la vez. También funciona con referencias de API y con publicaciones del changelog, no solo con páginas.

Nada de lo que hace AI Agent se escribe por sí solo en tu documentación. Cada cambio queda preparado, lo revisas línea por línea y nada llega a tus lectores hasta que lo guardas.

Quién puede usar AI Agent

AI Agent necesita un plan que incluya funciones de IA, y un administrador tiene que activarlo:

• Abre Project Settings → AI → AI Agents & MCP.

• En la pestaña Editor, en Writing, activa AI in the editor.

• Haz clic en Save changes en el menú superior.

AI in the editor es el interruptor general de toda la IA que trabaja en tu documentación, por lo que también activa AI Writing Tools y el agente que corrige y edita tu especificación OpenAPI. Desactivado significa que no hay IA en el editor.

Los escritores y roles superiores pueden usarlo. Guardar y publicar en un solo paso, eliminar cualquier cosa y cambiar el icono de la barra lateral de una página requieren el rol de publicador, así que un escritor puede editar algo que no puede eliminar.

Los revisores obtienen una vista de solo lectura. Pueden abrir la ventana, leer las ejecuciones de pull requests y revisar una propuesta línea por línea, pero no pueden pedir nada, aceptar ni rechazar una sección, ni guardar. Consulta qué pueden leer los revisores.

Cualquiera puede abrir la ventana, sea cual sea su plan. Si el proyecto no tiene funciones de IA, o un administrador ha desactivado el agente, verás una ejecución de ejemplo que muestra lo que hace en lugar de la real, y un botón See plans.

Las ejecuciones se miden. Cada mensaje que envías consume créditos de IA del saldo mensual del proyecto, que se muestra como una etiqueta en la barra superior de la ventana.

Abrir AI Agent

Selecciona AI Agent en la barra superior del editor. Se abre como una ventana casi a pantalla completa con el encabezado AI Editor, con la conversación a la izquierda y los paneles de revisión a la derecha.

Cerrar la ventana no detiene una ejecución. El agente sigue trabajando mientras consultas las páginas que está cambiando, y el botón de la barra superior sigue parpadeando hasta que termina. Para finalizar una ejecución antes, usa Stop.

Al reabrirla vuelves a la conversación que dejaste, con los cambios preparados y todo, incluido un turno que sigue en ejecución. Una conversación que aún está trabajando aparece marcada como Running en la lista de conversaciones anteriores.

Solo empiezas una conversación nueva cuando la última está realmente terminada: todo guardado o descartado, nada en ejecución, nada a medio escribir y una hora desde la última vez que la tocaste. Entonces el botón abre una conversación nueva y archiva la anterior entre las conversaciones anteriores.

Pedir un cambio

El agente trabaja en toda la versión de la documentación en la que estás, incluidos borradores y páginas sin publicar. Pide con tus propias palabras y describe el resultado que quieres en lugar de los pasos para lograrlo.

Una conversación nueva ofrece algunos ejemplos para empezar. Selecciona uno para rellenar el cuadro de mensaje con él y luego envíalo tal cual o edítalo antes.

Ejemplos

Arreglar lo que está roto

• Fix all the broken links in this version. Revisa todas las páginas de una sola pasada en lugar de una por una, redirige los enlaces que puede resolver e informa de dos páginas que comparten un slug para que tú las renombres, en lugar de renombrar una por su cuenta.

• Rename the legacy_token parameter to api_token everywhere it appears. Páginas, referencias de API y publicaciones del changelog en la misma ejecución, para que la especificación no conserve el nombre antiguo cuando el texto ya ha cambiado.

• Find the reader searches that returned nothing, and fix the pages that should have answered. Lee por sí mismo las analíticas de búsqueda y luego separa los términos que requieren escribir una página de aquellos en los que la página existe con una redacción que ningún lector adivina.

Mantener la documentación al nivel del producto

Estos requieren un repositorio de código conectado:

• Check the last commits and update the docs. Lee los commits, determina cuáles cambian algo que un lector notaría y edita solo las páginas desactualizadas. Las refactorizaciones, las actualizaciones de dependencias y las herramientas internas se dejan como están.

• Find stale pages and check whether they need updating. Compara lo que afirman las páginas con el código fuente y, cuando no coinciden, indica cuál cree que está desactualizado y nombra el archivo que leyó.

• Write a changelog post covering what shipped in v3. Primero lee tus publicaciones recientes y sigue su estilo, y limita la publicación a lo que un cliente ahora puede hacer.

Remodelar lo que ya existe

• Rewrite all the pages under Installation and restructure them. Varias reescrituras, una página separada de una de ellas y el orden en que se colocan, todo en una sola propuesta.

• Add a "Rate limits" section to every endpoint page that does not have one.

• Turn the last three sections of this page into a page of their own, and put it directly after this one.

La barra lateral

• Add icons to all pages. Elige un icono para cada página a partir de su título y deja las páginas que ya tienen uno. Esto requiere el rol de publicador.

• Add a "Guides" category above the tutorials. Puede añadir categorías, enlaces, etiquetas y separadores. Agrupar páginas existentes bajo una categoría nueva requiere dos pasos: guarda primero la categoría, ya que no se puede mover nada a un elemento que por ahora solo existe como propuesta.

Una edición no es la única respuesta aceptable. Si le pides redactar una versión que resulta ser solo refactorizaciones y cambios en pruebas, te dice que no hay nada que un lector notaría en lugar de redactarla de todos modos.

El agente siempre sabe qué página tienes abierta detrás de la ventana, así que "arregla los enlaces rotos de esta página" o "mejora esto" funcionan sin que nombres nada. Te sigue mientras te mueves: lo que cuenta como "esta página" es la que esté abierta cuando envías el mensaje, no cuando abriste la ventana. Una referencia de API funciona igual. Saber dónde estás no limita al agente a esa página, así que una solicitud más amplia sigue funcionando.

Señalar algo con @

Escribe @ en el cuadro de mensaje para señalar al agente algo concreto. Mencionar es más fuerte que tener una página abierta: le indica al agente que lea esa página antes de responder. Puedes elegir:

• this page: la página abierta detrás de la ventana.

• Cualquier página de la versión.

• Una referencia de API.

• Un archivo de un repositorio de código, si hay uno conectado.

Al borrar la etiqueta de tu mensaje se elimina también la mención.

Qué puede leer el agente

Además de tus páginas, AI Agent puede consultar las analíticas de búsqueda para encontrar los términos que los lectores buscaron sin hallar nada, leer los comentarios que los lectores dejaron en tus páginas, tanto valoraciones como comentarios escritos, comprobar todos los enlaces de una versión a la vez y listar las páginas que enlazan a una página antes de cambiarla.

Detener una ejecución

Stop ocupa el lugar de la flecha de envío mientras se ejecuta un turno.

Todo lo que la ejecución había preparado hasta ese momento se conserva para que lo revises, y aun así consume los créditos de IA que usó hasta ese punto.

Revisar lo que preparó

Los cambios propuestos se reúnen en la lista Changes, agrupados en Documentation, API references y Changelog. Cada fila muestra lo que añadiría y eliminaría.

Tienes dos niveles de control:

• Un cambio completo: la casilla decide si un cambio se incluye en el siguiente guardado. Desmarca lo que no quieras. Seleccionar Drop this change lo elimina por completo de la lista.

• Parte de un cambio: abre un cambio para verlo línea por línea y usa Accept o Reject en cada sección editada. Una sección rechazada se marca como Won't be saved, y el resto del cambio se sigue aplicando.

Las filas pueden llevar una etiqueta que explica su estado:

Cuando estés conforme, usa la barra inferior:

• Save to draft coloca los cambios seleccionados en el modo borrador, donde puedes seguir editando antes de publicar.

• Save and publish los escribe y publica en un solo paso. Esto requiere el rol de publicador.

• Discard all descarta los cambios preparados.

Guardar no termina la conversación. Los cambios guardados permanecen en la lista y puedes seguir pidiendo más.

Conversaciones

Cada conversación conserva su propio hilo y sus propios cambios preparados.

• Selecciona para iniciar una nueva conversación. La actual se cierra, no se elimina.

• Selecciona para reabrir una conversación anterior. Abrir una conserva la otra, y no se pierde nada de lo preparado en ningún caso.

La misma lista tiene una sección Pull requests, con las ejecuciones iniciadas desde un pull request de un repositorio de código conectado. Puedes leerlas y responderlas, pero permanecen con el pull request en lugar de convertirse en una de tus propias conversaciones.

Qué pueden leer los revisores

Los revisores ven la sección Pull requests y nada más en esa lista. Las conversaciones de otras personas siguen siendo privadas, y la lista propia de un revisor está vacía hasta que el agente propone algo para un pull request.

Un revisor puede abrir una ejecución y leer cada cambio propuesto línea por línea. No puede enviar un mensaje, aceptar ni rechazar una sección, descartar un cambio ni guardar. Una nota sobre el cuadro de mensaje lo indica.

Esto hace que el enlace de revisión en un pull request sea útil para un grupo más amplio: cualquiera del proyecto desde el rol de revisor hacia arriba puede seguirlo y leer la propuesta, aunque actuar sobre ella sigue requiriendo un escritor.

Mantener una conversación ágil

Un indicador en la parte superior de la conversación muestra su nivel de ocupación como porcentaje. Pasado el 75 %, el agente sugiere iniciar una nueva conversación, y pasado el 90 % te pide confirmación antes de enviar. Iniciar una nueva conversación nunca pierde lo que ya está preparado.

El botón Context junto al cuadro de mensaje muestra de qué parte el agente está trabajando:

También te avisa cuando un repositorio conectado no se puede leer o no se ha leído desde hace un tiempo.

Reglas recordadas

Dile al agente algo que debe hacer siempre o nunca, como usar siempre ortografía británica, no escribir nunca una página a partir de un directorio concreto o qué sección dejar en paz, y registra la regla para el proyecto. La conversación muestra lo que anotó, marcado como Remembered for this project.

Una regla recordada se aplica a todos los que trabajan en el proyecto, en cada ejecución, incluidas las que inicia un pull request.

Pide al agente que elimine una regla y lo hará. También puedes seleccionar Forget en la fila que la registró, y los administradores pueden ver todas las reglas juntas, y eliminar cualquiera, en Project Settings → AI → AI Agents & MCP → pestaña Editor, en la tarjeta Remembered rules. Olvidar es definitivo, así que volver a registrarla es la única forma de recuperarla.

Un proyecto admite hasta 25 reglas de 120 caracteres cada una.

Elegir el modelo

Los administradores pueden elegir el modelo que usa cada ejecución del agente en el proyecto, incluidas las comprobaciones de pull requests de Self-Updating Docs. Abre Project Settings → AI → AI Agents & MCP → pestaña Editor y usa Agent model en la tarjeta Model.

Cada modelo se valora sobre tres en Cost, Speed y Judgement, y muestra quién lo fabrica y el país de origen, de modo que puedas descartar un modelo por su procedencia si lo necesitas. Auto sigue nuestra recomendación actual y cambia con ella.

El modelo que usa una ejecución se muestra en la parte superior del AI Editor, junto a tu saldo de AI credits. Los administradores pueden seleccionarlo para abrir el ajuste.

Lo que AI Agent no puede hacer

• No puede crear una referencia de API. Eso implica subir una definición por tu cuenta.

• No puede eliminar una página que tiene páginas anidadas, la única página que queda en una sección de documentación ni la última sección de una versión.

• No puede mover una página a otra sección de documentación, ni renombrar o reordenar las propias secciones.

• Puede añadir una categoría, un enlace, una etiqueta o un separador a la barra lateral, pero no puede renombrarlos, moverlos ni eliminarlos una vez añadidos.

• No puede vaciar una página por completo. Vaciar una página no es lo mismo que eliminarla, así que el agente se niega y te indica que la elimines correctamente.

• No puede generar imágenes.

• No puede modificar tu código. Los repositorios conectados son de solo lectura.

Si una solicitud requiere alguna de estas acciones, el agente lo indica y hace la parte que sí puede en lugar de aproximar el resto.

AI Agent y AI Writing Tools

AI Writing Tools funcionan en línea sobre el texto que has resaltado y aplican sus cambios de inmediato. AI Agent trabaja a partir de una conversación, puede modificar muchas páginas, referencias de API y publicaciones del changelog a la vez, y deja todo preparado para su revisión primero.

Registro de actividad

La aplicación de cambios se registra en el registro de actividad como published AI changes o saved AI changes as drafts, una vez por guardado y no una vez por página. El cambio del modelo del agente también se registra.

Qué datos se envían

Las páginas, referencias de API y publicaciones del changelog que el agente lee y edita se envían al modelo que hayas elegido, junto con tu conversación.

Las ejecuciones del agente se atienden a través de OpenRouter, y solo se usan proveedores con retención de datos cero. Tu contenido nunca se conserva ni se usa para entrenar un modelo. Consulta Cómo se tratan tus datos para ver en qué se diferencia de nuestras otras funciones de IA.