Conocimiento

Conocimiento es lo que leen tus agentes para responder: tus servicios y precios, las direcciones y los horarios de tus sedes, cómo prepararse para un procedimiento, tus políticas. Agregas cada fuente una vez como documento, Raíz lo indexa, y cada agente al que se lo das puede buscar el pasaje correcto cuando responde. Cuando la fuente cambia, actualizas el documento y Raíz lo vuelve a indexar.

Tipos de documento

Agregar un documento

raiz.knowledge.create recibe un title, el kind y su contenido, y opcionalmente una description:

curl https://api.getarbol.com/v1/raiz/knowledge \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "kind": "text",
    "title": "Horario de atención",
    "text": "Example Clinic atiende de lunes a viernes de 7:00 a 18:00, y los sábados de 8:00 a 12:00."
  }'

Para un archivo, codifícalo en base64 y arma el cuerpo con jq:

jq -n --rawfile data <(base64 < prices-2026.pdf | tr -d '\n') \
  '{kind: "file", title: "Prices 2026", file: {name: "Prices 2026.pdf", mediaType: "application/pdf", data: $data}}' \
| curl https://api.getarbol.com/v1/raiz/knowledge \
    --request POST \
    --header "Authorization: Bearer $ARBOL_API_KEY" \
    --header "Content-Type: application/json" \
    --data @-

Un archivo que no es base64 válido, que es demasiado grande o que no coincide con su mediaType responde 422 KNOWLEDGE_FILE_INVALID.

Para un sitio web, crawl fija maxPages (de 1 a 50) y maxDepth (de 0 a 5, donde 0 importa solo esa página); por defecto, 20 páginas con profundidad 2. Solo se siguen páginas del mismo origen que estén bajo la ruta de la URL inicial, y se respeta robots.txt. El origen del sitio debe estar aprobado para el rastreo, o la llamada responde 422 WEBSITE_NOT_APPROVED. El rastreo corre como una tarea knowledge_crawl.

Indexación

Un documento nuevo o cambiado se indexa solo, y su indexStatus dice en qué punto está:

raiz.knowledge.get lee un documento y su estado de indexación; expand=content agrega su texto tal como se indexó, en Markdown, hasta 200.000 caracteres (truncated dice si había más). Úsalo para ver lo que realmente dice un documento. raiz.knowledge.list lista los documentos, del más reciente al más antiguo, por kind, status, indexStatus y q (títulos y nombres de archivo).

Buscar

raiz.knowledge.search encuentra los pasajes que mejor responden una query de 2 a 500 caracteres, del mejor al peor. Cada resultado tiene el text del pasaje, el title y el knowledgeDocumentId de su documento, y un score: cuanto más alto, más cercano. agentId busca exactamente lo que ese agente puede encontrar, y knowledgeDocumentIds limita la búsqueda a esos documentos. Los documentos en pausa y los que aún no están indexados nunca se buscan.

La búsqueda lee pero se envía con POST, así que limit (8 por defecto, hasta 20) y cursor van en el cuerpo:

curl https://api.getarbol.com/v1/raiz/knowledge/search \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "query": "horario de atención del sábado", "agentId": "agt_01jd8x5k2m7q9r3t6v8w0y4z1b" }'

Usarlo en los agentes

Un agente consulta los documentos de sus knowledgeDocumentIds, hasta 100, que se fijan con raiz.agents.create o raiz.agents.update; una actualización envía la lista nueva completa. Un id que no existe en tu organización responde 422 KNOWLEDGE_DOCUMENT_UNAVAILABLE. Un agente de texto busca en sus documentos cuando los necesita; con settings.automaticKnowledge activado, también busca pasajes relevantes antes de responder un mensaje con contenido sustancial. Para ver qué agentes usan un documento, lee los knowledgeDocumentIds de cada agente.

Cambiar o pausar un documento

raiz.knowledge.update cambia un documento; los campos que omites se quedan. Un text o un file nuevo reemplaza el contenido y lo vuelve a indexar, y una sourceUrl o un crawl nuevo toma una nueva captura del sitio web. Un cambio que no corresponde al tipo del documento responde 422 KNOWLEDGE_KIND_MISMATCH. "status": "paused" oculta el documento a todos los agentes sin eliminarlo y conserva su índice. Envía la version que leíste como expectedVersion para no sobrescribir el cambio de otra persona.