Construir y poblar una base de conocimientos

Principio — fundamentar, luego verificar. Una base de conocimientos es una fuente de cumplimiento obligatorio, no una sugerencia. Delimite su cobertura en instructions y confirme siempre que una pregunta real se recupere antes de confiar en ella; una búsqueda vacía significa que el agente responderá "no cubierto". Más información en Principios de diseño.

Una base de conocimientos montada se recupera automáticamente en cada turno — el modelo no decide si buscar; la relevancia se determina por la distancia vectorial. Esto es deliberado: una base de conocimientos es una fuente de cumplimiento obligatorio, no una herramienta opcional.

1. Crearla

create_knowledge_base(
  name="Company policy",
  description="Mortgage policy and rates, effective 2026 — not car or personal loans",  # routes questions here
  instructions="Authoritative current mortgage policy; overrides any industry norm. "
               "Covers home mortgages only; for car or personal loans, say so and hand off.",  # for the model
)

El nombre se normaliza a un slug seguro para URL al crearlo — "Company policy" se devuelve como company-policy. Utilice ese nombre devuelto para todo lo posterior: add_knowledge_text(kb_name=…), search_knowledge_base(kb_name=…), y para asociarla a un agente. Escribir el nombre original con espacios más tarde simplemente devuelve un 404.

2. Escribir description — es lo que enruta las preguntas a esta base

description no es un pie de foto. Antes de cada respuesta, la plataforma lee la descripción de cada base adjunta y decide cuál de ellas necesita esta pregunta — y, si ninguna la necesita, no realiza ninguna búsqueda. Un agente con tres bases realizaría de otro modo tres búsquedas vectoriales y volcaría tres conjuntos de extractos en el prompt en cada turno, incluso cuando el visitante dijo "hola".

Por lo tanto, una base cuya descripción sea vaga o esté en blanco se buscará cuando no debería, y —peor aún— se omitirá cuando debería haberse buscado. Ningún fallo se anuncia: el primero se manifiesta como una respuesta lenta con citas irrelevantes, el segundo como "No tengo nada sobre eso".

Escriba una línea, con las palabras que usaría un visitante, nombrando el tema:

✅ "Country-by-country medical device registration requirements"
✅ "Regulatory change news by country and authority, 2022–2026 — what changed and when"
✅ "Selpercatinib — for lung and thyroid cancer"
 
❌ "Knowledge base"                ← routes nothing
❌ "Imported from the website"     ← says where it came from, not what is in it
❌ "Sandbox test, safe to delete"  ← says why it exists, not what is in it

Lo que importa es ser distinguible de sus otras bases, no ser largo. Un inquilino con nueve bases — ocho fármacos y un perfil de empresa, una línea cada uno, ninguna más larga de una docena de palabras — enruta correctamente 10 de 10 preguntas, porque "for lung and thyroid cancer" y "for IgA nephropathy" no pueden confundirse. Medido, no asumido.

Añada un límite solo donde dos bases se solapen. Si sus páginas de producto y su archivo de noticias tratan ambos sobre el mismo tema, diga cuál es cuál — "…— not pricing or company information" es lo que impide que el archivo responda a una pregunta sobre precios. Donde las bases ya son obviamente distintas, una cláusula de límite no aporta nada.

Esta línea es también lo que muestra la lista de la consola, pero esa es la función secundaria.

3. Escribir instructions desde el uso esperado — al crearlo, no "después"

instructions no afecta a la recuperación; la recuperación es búsqueda vectorial más max_distance. Se inyecta junto a los extractos de esta KB en el momento de la respuesta, por lo que gobierna cómo el modelo utiliza lo que recuperó. Dejándola en blanco, la KB sigue recuperando, pero las respuestas pierden todas las reglas específicas de la KB: autoridad, límites, convenciones de citación. Estar en blanco es aceptable solo para material de referencia genérico sin reglas especiales.

Derívela de cómo se utilizará la KB realmente — una línea por pregunta:

Ejemplos de instrucciones de base de conocimientos, por tipo de KB:

# Website-content KB (products, services, team, blog)
instructions="Company website content: products, services, team and blog posts. Authoritative
for what we offer and who we are. Marketing copy is not a contractual promise — for prices,
terms or eligibility prefer the policy KB; if only this KB answers, attribute it to the website."
 
# Policy / regulation KB
instructions="Current company policy, effective 2026; overrides industry norms and prior
knowledge. Covers home mortgages only — for car or personal loans, say so and hand off.
Any quoted rate or fee must state its effective date."
 
# Product-docs KB
instructions="Official product documentation for the current release. State the version when a
feature is version-dependent. If the docs don't cover something, say so — never fill the gap
from general knowledge."

4. Añadir contenido

add_knowledge_text(kb_name="Company policy", title="2026 late-fee rule",
                   content="From 1 July 2026 the daily late fee is 0.019% …")

Los archivos binarios (pdf/docx) y carpetas completas (comprimidos) pasan por add_knowledge_file — los subdirectorios se recorren y cada md/txt/pdf/html/docx se importa bajo su ruta dentro del archivo.

4b. Escribir la oración que desea que se encuentre

La recuperación coincide con el significado, y un valor por sí solo tiene casi ninguna carga. Esta es la única acción de mayor impacto que controla, y es fácil de equivocarse porque no hay errores — la búsqueda sigue devolviendo algo, simplemente no lo correcto.

Un catálogo de clientes real tenía esta línea en 1.480 de 1.500 registros:

Reading level: 1 · Age: 5 · Words: 1951

Y "which books suit a child just starting to read on their own" devolvió un libro sobre prodigios musicales. El hecho estaba en el texto y seguía siendo inaccesible: 1 no se parece a beginner reader de la misma manera que una palabra se parece a otra.

Añadir una oración junto al valor lo solucionó — medido en ese mismo registro:

Reading level: 1 · Age: 5
Suitable for around age 5, for children just starting to read on their own.

(Menor es más cercano. En este modelo dos pasajes no relacionados se sitúan alrededor de 0.61, por lo que la última fila pasa de "apenas mejor que el azar" a una coincidencia genuina — y la ganancia se mantiene a través de los idiomas).

La regla: si una pregunta se respondería mediante una propiedad en lugar del texto — precio, fecha, nivel, disponibilidad, stock — dígalo en palabras también. Los valores estructurados son para filtrar; la recuperación encuentra lo que está escrito.

Lo que no vale la pena su tiempo

Las exportaciones a menudo se repiten a sí mismas — un summary y una description con prosa idéntica. Parece un desperdicio, y la intuición de que "consume" el vector es incorrecta: lo medimos y eliminar la duplicación cambió la recuperación en +0.002 de distancia en 60 registros — es decir, nada en absoluto. Una incrustación (embedding) es una dirección, no un presupuesto; decir lo mismo dos veces apunta principalmente en la misma dirección dos veces.

Déjelo. Gaste el esfuerzo en la oración anterior.

4c. Si los documentos comparten una cabecera, construya el índice estructurado

La búsqueda vectorial no puede contar, filtrar por número ni agrupar. "How many do you have", "which are under 200 words", "how many per category" no se responden mal — son estructuralmente irresolubles, y el agente se negará a responder o informará sobre los pocos registros que haya recuperado por casualidad.

build_knowledge_index(name="books", roles=["identity", "link", "image"])

Solo vale la pena llamarla cuando los documentos comparten una cabecera legible por máquina — una tabla de metadatos, YAML front matter, líneas Field: value. Las exportaciones de productos, catálogos, folletos y listados de cursos suelen calificar; la prosa no, y la llamada se niega en lugar de construir una tabla cuyos valores sean todos diferentes. Una negación es el resultado correcto, no un error que deba sortearse.

roles nombra los campos que deben extraerse exactamente y nunca parafraseados:

Pregunte al usuario cuáles son estos campos; no los infiera. Cuál de tres URL es la que enviar a un cliente es un hecho empresarial que los datos no indican. Si un rol declarado no se encuentra, vuelve en roles.unresolved con nombres de campo candidatos — presente esos al usuario en lugar de elegir uno.

Lea dropped, e informe al usuario

{"built": true, "documents": 4523,
 "columns": ["title", "age", "word_count", "genre", "read_url", "cover_url"],
 "dropped": [["isbn", "not_found", "no anchor 'ISBN: ' in the sample"]]}

Una columna descartada es invisible en todas partes: las respuestas posteriores simplemente la sortean, por lo que este informe es el único lugar donde se menciona. Lo mismo para get_knowledge_index, cuyas advertencias suelen revelar problemas de datos que el cliente no conocía — en un catálogo real, una décima parte de los registros tenía un recuento de páginas de 0, lo cual no es un libro corto sino un valor faltante registrado como cero, y habría arrastrado hacia abajo cada promedio construido sobre él.

Informe de ello en los propios términos del cliente. Nada más en la plataforma lo hará.

Cambiarlo más tarde

patch_knowledge_index(name="books", request="also track the author", apply=false)

Ejecute con apply=false primero, muestre al usuario qué cambiaría, agrupe varias ediciones y luego aplique una vez. Aplicar vuelve a leer los campos desde el texto almacenado; no vuelve a incrustar nada, por lo que es barato.

Pedir algo que los documentos no contienen devuelve una entrada refused con una razón — pase eso al usuario literalmente en lugar de inventar una solución alternativa.

5. ★ Verificar la recuperación — no omitir ★

search_knowledge_base(kb_name="Company policy", query="how is the late fee calculated")
#   hits  → the agent can answer this
#   empty → the agent will treat it as "not covered" and say so

6. Montarla

update_agent(name="Support", add_knowledge_bases=["company-policy"])   # incremental — keeps existing mounts

No escriba "always cite the passage" en instructions — ese comportamiento está integrado. Escriba solo lo que sea específico de esta biblioteca: orden de autoridad, límites de cobertura, uso especial (p. ej., "quoting a rate must state its effective date").

Informe — no se detenga en "importado". Diga al usuario cuántos fragmentos se registraron y proporcione el enlace clicable para abrir la base de conocimientos y su knowledge starmap (una vista 3D de lo que se ingirió): https://console.agent4.io/#/knowledge-bases/Company%20policy — luego confirme que está adjunta al agente.