---
title: "Conocimiento"
description: "Los documentos que consultan los agentes de Raíz antes de responder. Agrega textos, archivos y sitios web, sigue su indexación, búscalos y dáselos a los agentes."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

| `kind` | Qué es | Qué envías |
| --- | --- | --- |
| `text` | Texto plano o Markdown, escrito en la misma solicitud. | `text`, hasta 1.000.000 de caracteres. |
| `file` | Un archivo PDF, Word, Excel, HTML, CSV, de texto plano o Markdown. | `file`: su `name`, su `mediaType`, que debe coincidir con su contenido, y sus bytes en base64 como `data`, hasta 8 MiB decodificado. |
| `website` | Una captura de páginas web. | `sourceUrl`, una página HTTPS desde la cual empezar, y límites de `crawl` opcionales. |

## Agregar un documento

[`raiz.knowledge.create`](/api/raiz/knowledge/create/) recibe un `title`, el `kind` y su contenido, y opcionalmente una `description`:

```bash
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`:

```bash
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](/developers/raiz/data/#tareas) `knowledge_crawl`.

## Indexación

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

| `indexStatus` | Significado |
| --- | --- |
| `pending` | Esperando a que se rastree o se indexe. |
| `indexing` | En curso. |
| `ready` | Se puede buscar. |
| `failed` | `indexErrorCode` dice por qué. Los documentos fallidos se reintentan automáticamente. |

[`raiz.knowledge.get`](/api/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`](/api/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`](/api/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:

```bash
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`](/api/raiz/agents/create/) o [`raiz.agents.update`](/api/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.

> **¿Conocimiento o una novedad?**
>
> El material de referencia extenso va en Conocimiento. Para una situación puntual que dura un tiempo, como un día cerrado o un servicio que no está disponible, publica una [novedad](/developers/raiz/campaigns/#novedades).

## Cambiar o pausar un documento

[`raiz.knowledge.update`](/api/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.

Source: https://docs.getarbol.com/developers/raiz/knowledge/index.mdx