Enseñar el negocio a la IA sin escribirlo dos veces

Base de conocimiento documenta cómo subir un archivo o redactar una fuente a mano para que el agente la cite. Esta receta resuelve algo distinto. Qué hacer cuando ese contenido ya existe en otro lugar del workspace, y cómo confirmar que el agente de verdad lo usa.

Antes de empezar

• help_centers:write para crear y publicar artículos.
• ai_agents:write para asignar knowledge_tags al agente.
• Un centro de ayuda existente, o crea uno con POST /help-centers (Publicar tu centro de ayuda).

1. Redactar donde el cliente ya lo va a leer

Si el contenido ya se está escribiendo para el portal de autoservicio, ese es el lugar. No hace falta subirlo también como archivo:

curl -X POST https://api.vitrinadev.com/api/v1/help-centers/b0630282-68e1-4219-ae91-c3f3e9ae6cce/articles \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "horario-de-atencion",
    "translation": {
      "locale": "es",
      "title": "Horario de atención",
      "body_markdown": "Atendemos de lunes a viernes, de 9:00 a 19:00. Los sábados atendemos de 10:00 a 14:00."
    }
  }'

El artículo nace internal. Nadie de afuera lo ve, y tampoco el agente, hasta que se publica.

2. Publicar, y ver nacer la fuente de conocimiento

curl -X POST https://api.vitrinadev.com/api/v1/help-centers/b0630282-68e1-4219-ae91-c3f3e9ae6cce/articles/0bee0c9b-d029-449a-a9e1-d82eefbfdc9c/publish \
  -H "Authorization: Bearer $VITRINA_KEY"

{ "data": { "status": "published", "published_at": "2026-09-23T11:46:48.556Z" } }

GET /kb/sources/{id} confirma que la sincronización ya arrancó, sin ningún otro llamado de por medio:

curl https://api.vitrinadev.com/api/v1/kb/sources/01a0ce16-fe8b-7690-aa19-b188b500db0c \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": {
    "status": "pending",
    "tags": ["kb_help_center", "kb_help_center_receta-c-ayuda", "kb_es"],
    "help_center_article_id": "0bee0c9b-d029-449a-a9e1-d82eefbfdc9c",
    "help_center_locale": "es",
    "created_at": "2026-09-23T11:46:48.585939+00:00"
  }
}

created_at cae al mismo segundo que el publish de arriba. Esa fuente no la creó ninguna llamada tuya. Nace sola cuando el artículo pasa a publicado, con tags armados a partir del centro y el idioma. status: "pending" es normal por un momento, mientras el artículo se procesa.

Cuando el artículo se vuelve a editar publicado, cada guardado de una traducción re-sincroniza esa misma fuente. Para forzar una nueva sincronización a mano, usa resync-kb:

curl -X POST https://api.vitrinadev.com/api/v1/help-centers/b0630282-68e1-4219-ae91-c3f3e9ae6cce/articles/0bee0c9b-d029-449a-a9e1-d82eefbfdc9c/resync-kb \
  -H "Authorization: Bearer $VITRINA_KEY"

{ "data": { "synced": ["es"], "failed": [] } }

3. Conectar la fuente a un agente

Un agente no busca en toda la biblioteca del workspace. Cita solo lo que coincide con sus knowledge_tags, y las fuentes que vienen de un centro de ayuda usan el tag kb_help_center_<slug> visto arriba:

curl -X PUT https://api.vitrinadev.com/api/v1/ai-agents/c7a013c7-87e8-4892-9703-ec24c476600b/draft \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "knowledge_tags": ["kb_help_center_receta-c-ayuda"] }'

{ "data": { "draft_knowledge_tags": ["kb_help_center_receta-c-ayuda"], "draft_updated_at": "2026-09-23T11:48:35.568Z" } }

Queda guardado en el borrador. Configurar el agente que conversa explica el ciclo de publicación completo.

4. Cuando el contenido nace fuera de Vitrina

Un archivo subido a mano, o generado desde una URL existente, sigue el otro camino. Base de conocimiento lo documenta: POST /kb-files, POST /kb-files/generate-from-url, y el rastreo por lote (crawl/start → crawl/{jobId}/generate). Esa familia produce un kb_file. Se adjunta a un agente con POST /ai-agents/{id}/knowledge, no con knowledge_tags.

La regla para elegir entre los dos caminos es simple. Si el texto ya vive en el centro de ayuda, o va a vivir ahí, publicarlo alcanza. Si vive en un PDF, una planilla o una página externa que nadie va a convertir en artículo, sube el archivo.

Cuando falla

Un artículo despublicado (archive) desaparece de la búsqueda del agente en la misma operación. No hace falta borrar la fuente ni tocar el agente. status: "pending" que no avanza a synced después de un rato no suele ser un error del artículo. resync-kb reintenta la sincronización.

En la aplicación: el selector de knowledge_tags del agente está en Configuración → Agentes de IA. El editor de artículos existe y funciona, pero hoy no tiene entrada en el menú: es beta y se llega por URL, en /help-centers/articles. Guía completa en Manual de plataforma → Enseñarle el negocio a la IA una sola vez.

Una vez que el agente cita lo correcto, Publicar una versión nueva de la IA solo si pasa el examen lo lleva a producción.