> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Gerenciar documentos

Gerencie sua base de conhecimento pelo [painel da base de conhecimento](https://elevenlabs.io/app/agents/knowledge-base), pela CLI ou pela API. Para saber o que é uma base de conhecimento e como os agentes a utilizam, consulte [Base de conhecimento](/docs/pt/eleven-agents/customization/knowledge-base).

![Interface principal da base de conhecimento mostrando uma lista de
documentos](/docs/_fern-img/0887213c4d8099240b7e5a8fec86fc75f4763e8fd80a6f7a6de33545c45f37a2.webp)

## Adicionar documentos

Os documentos podem ser criados a partir de arquivos, páginas da web ou texto simples. Depois de criados, vincule-os a um agente para disponibilizar o conteúdo nas conversas.

#### Painel

No [painel da base de conhecimento](https://elevenlabs.io/app/agents/knowledge-base), ou diretamente na configuração de um agente, clique em **Adicionar documento** e escolha uma fonte.

#### Arquivo

Envie um documento nos formatos PDF, TXT, DOCX, HTML, EPUB ou Markdown, com até 20 MB por arquivo.

![Interface de envio de arquivo mostrando os formatos compatíveis e o limite de 20 MB](/docs/_fern-img/b428874877d6aa2b24167c0293709e6a52a096a13b02244c0a5463139d3988e4.webp)

#### URL

Importe uma página da web colando a URL. Para ingerir um site inteiro, use a opção de rastreamento — você pode rastrear todo o site seguindo links a partir da URL inicial ou importar páginas do sitemap do site. Se uma página não for importada, confirme se seu site permite o [agente de usuário do rastreador](#crawler-user-agent).

![Interface de importação de URL em que os usuários podem colar um link de documentação](/docs/_fern-img/8523ea5c5ae0418007eb7042d4af3e792a111ca41b74a090357df34cd5b4a369.webp)

> **Warning**
>
> Verifique se você tem permissão para usar o conteúdo das URLs fornecidas.

#### Texto

Insira o texto manualmente e dê um nome a ele.

![Interface de entrada de texto em que os usuários podem nomear e adicionar conteúdo personalizado](/docs/_fern-img/4e44e310335dcea24b4832d38813992f1bdc55ef85b4e54353963dc47e9baa0a.webp)

#### CLI

A CLI não envia documentos da base de conhecimento diretamente. Crie-os pelo painel ou pela API e vincule os IDs de documento resultantes à configuração do seu agente.

#### Baixar a configuração do agente

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### Editar \`agent_configs/\<agent-name>.json\`

Defina `conversation_config.agent.prompt.knowledge_base`:

```json
{
  "conversation_config": {
    "agent": {
      "prompt": {
        "knowledge_base": [
          {
            "type": "file",
            "name": "Unladen Swallow Facts",
            "id": "i2YYI6huwBmcgYydAXARmQJc3pmX",
            "usage_mode": "auto"
          }
        ]
      }
    }
  }
}
```

#### Enviar suas alterações

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### API

Crie cada documento e vincule os IDs retornados à configuração do agente.

```python
import os

from dotenv import load_dotenv
from elevenlabs import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

# Create a document from text
text_doc = elevenlabs.conversational_ai.knowledge_base.documents.create_from_text(
    text="The airspeed velocity of an unladen swallow (European) is 24 miles per hour, or roughly 11 meters per second.",
    name="Unladen Swallow facts",
)

# Create a document from a URL
url_doc = elevenlabs.conversational_ai.knowledge_base.documents.create_from_url(
    url="https://en.wikipedia.org/wiki/Unladen_swallow",
    name="Unladen Swallow Wikipedia page",
)

# Create a document from a file
file_doc = elevenlabs.conversational_ai.knowledge_base.documents.create_from_file(
    file=open("/path/to/unladen-swallow-facts.txt", "rb"),
    name="Unladen Swallow Facts",
)

# Attach the documents to an agent
elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "agent": {
            "prompt": {
                "knowledge_base": [
                    {"type": "text", "name": text_doc.name, "id": text_doc.id},
                    {"type": "url", "name": url_doc.name, "id": url_doc.id},
                    {"type": "file", "name": file_doc.name, "id": file_doc.id},
                ]
            }
        }
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import fs from "node:fs";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();

// Create a document from text
const textDoc = await elevenlabs.conversationalAi.knowledgeBase.documents.createFromText({
  name: "Unladen Swallow Facts",
  text: "The airspeed velocity of an unladen swallow (European) is 24 miles per hour, or roughly 11 meters per second.",
});

// Create a document from a URL
const urlDoc = await elevenlabs.conversationalAi.knowledgeBase.documents.createFromUrl({
  name: "Unladen Swallow Wikipedia page",
  url: "https://en.wikipedia.org/wiki/Unladen_swallow",
});

// Create a document from a file
const fileBuffer = fs.readFileSync("/path/to/unladen-swallow-facts.txt");
const file = new File([fileBuffer], "unladen-swallow-facts.txt", { type: "text/plain" });
const fileDoc = await elevenlabs.conversationalAi.knowledgeBase.documents.createFromFile({
  name: "Unladen Swallow Facts",
  file,
});

// Attach the documents to an agent
await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    agent: {
      prompt: {
        knowledgeBase: [
          { type: "text", name: textDoc.name, id: textDoc.id },
          { type: "url", name: urlDoc.name, id: urlDoc.id },
          { type: "file", name: fileDoc.name, id: fileDoc.id },
        ],
      },
    },
  },
});
```

Para rastrear um site inteiro em uma pasta de documentos, em vez de adicionar uma única página, inicie um trabalho de rastreamento. O rastreamento é executado de forma assíncrona — use o ID do trabalho retornado para verificar seu status ou cancelá-lo.

```python
crawl = elevenlabs.conversational_ai.knowledge_base.crawl_jobs.create(
    url="https://elevenlabs.io/docs",
    max_depth=3,
    max_pages=1000,
)
```

```typescript
const crawl = await elevenlabs.conversationalAi.knowledgeBase.crawlJobs.create({
  url: "https://elevenlabs.io/docs",
  maxDepth: 3,
  maxPages: 1000,
});
```

### Agente de usuário do rastreador

As importações de URL e os trabalhos de rastreamento buscam páginas com o agente de usuário `ElevenlabsBot/1.0`.

> **Warning**
>
> Se seu site estiver protegido por uma CDN, WAF ou regra de proteção contra bots, permita esse agente de usuário para que o rastreador possa ler suas páginas. Quando uma solicitação é bloqueada, o documento é criado, mas nenhum conteúdo pode ser extraído dele.

O rastreador também respeita o `robots.txt`. Páginas não permitidas para `ElevenlabsBot` ou para todos os agentes de usuário são ignoradas. Portanto, verifique suas regras se uma página que você espera que seja indexada estiver ausente. Para permitir explicitamente o rastreador:

**`robots.txt`**

```txt robots.txt
User-agent: ElevenlabsBot
Allow: /
```

## Adicionar documentos existentes a um agente

Os documentos podem ser reutilizados entre agentes, portanto, o conhecimento compartilhado só precisa ser mantido uma vez.

1. Acesse a [configuração](https://elevenlabs.io/app/agents/agents) do agente.
2. Encontre a seção da base de conhecimento e clique em **Adicionar documento**.
3. Selecione um documento existente da sua base de conhecimento ou envie um novo.

![Interface para adicionar documentos a um
agente](/docs/_fern-img/8e8a6a2df244ed20d1ab889c8ae5dda76aefed0d15f3dd2fe09c35b281c63673.webp)

> **Tip**
>
> Reutilizar documentos entre agentes mantém o conhecimento consistente e evita envios duplicados.

## Editar documentos

Você pode editar o conteúdo de um documento diretamente, em vez de excluí-lo e enviá-lo novamente. A edição de um documento regenera automaticamente seus blocos de pesquisa de conteúdo e embeddings de RAG, mantendo a pesquisa e a recuperação do agente sincronizadas.

* **Documentos de texto e arquivo**: edite o conteúdo diretamente e salve.
* **Documentos de arquivo**: como alternativa, substitua o arquivo original por uma nova versão.
* **Documentos de URL**: edite o conteúdo quando a sincronização automática estiver desativada. Quando ela estiver ativada, o ciclo de sincronização gerencia o documento e as edições manuais são bloqueadas.

![Editando o conteúdo de um documento diretamente na base de
conhecimento](/docs/_fern-img/4ea01bb2c13162f31f7610b049ae0db542e279a26da38f4c79f17fb89a8524f5.webp)

```python
# Update a document's name or content
elevenlabs.conversational_ai.knowledge_base.documents.update(
    documentation_id="i2YYI6huwBmcgYydAXARmQJc3pmX",
    name="Unladen Swallow Facts",
    content="The airspeed velocity of an unladen swallow (European) is 24 miles per hour.",
)

# Replace the underlying file of a file document

elevenlabs.conversational_ai.knowledge_base.document.update_file(
documentation_id="i2YYI6huwBmcgYydAXARmQJc3pmX",
file=open("/path/to/unladen-swallow-facts-v2.txt", "rb"),
)

```

```typescript
// Update a document's name or content
await elevenlabs.conversationalAi.knowledgeBase.documents.update("i2YYI6huwBmcgYydAXARmQJc3pmX", {
  name: "Unladen Swallow Facts",
  content: "The airspeed velocity of an unladen swallow (European) is 24 miles per hour.",
});

// Replace the underlying file of a file document
const fileBuffer = fs.readFileSync("/path/to/unladen-swallow-facts-v2.txt");
const updatedFile = new File([fileBuffer], "unladen-swallow-facts-v2.txt", { type: "text/plain" });
await elevenlabs.conversationalAi.knowledgeBase.document.updateFile("i2YYI6huwBmcgYydAXARmQJc3pmX", {
  file: updatedFile,
});
```

## Manter o conteúdo de URL atualizado

Documentos criados a partir de uma URL podem ser atualizados para buscar novamente o conteúdo mais recente da fonte. A atualização reindexa o documento para que agentes com RAG usem o conteúdo atualizado.

```python
elevenlabs.conversational_ai.knowledge_base.document.refresh(
    documentation_id="i2YYI6huwBmcgYydAXARmQJc3pmX",
)
```

```typescript
await elevenlabs.conversationalAi.knowledgeBase.document.refresh("i2YYI6huwBmcgYydAXARmQJc3pmX");
```

No painel, você também pode ativar a sincronização automática para atualizar documentos de URL automaticamente em uma programação, mantendo o conteúdo atualizado sem intervenções manuais.

## Organizar com pastas

As pastas agrupam documentos relacionados para facilitar o gerenciamento e a vinculação em massa. Crie uma pasta e mova documentos para ela pelo painel ou pela API.

Uma pasta vinculada a um agente disponibiliza todos os seus documentos por meio de RAG. Portanto, o agente precisa ter RAG ativado para usar pastas.

![Criando uma pasta e movendo documentos para
ela](/docs/_fern-img/8267c0d4a36282c1fcaaacf0a665e5caf8c4cf6f2908451fc5a3b1cf6a8dd2e0.webp)

```python
# Create a folder
folder = elevenlabs.conversational_ai.knowledge_base.documents.create_folder(
    name="Product documentation",
)

# Move a document into the folder

elevenlabs.conversational_ai.knowledge_base.documents.move(
document_id="i2YYI6huwBmcgYydAXARmQJc3pmX",
move_to=folder.id,
)

```

```typescript
// Create a folder
const folder = await elevenlabs.conversationalAi.knowledgeBase.documents.createFolder({
  name: "Product documentation",
});

// Move a document into the folder
await elevenlabs.conversationalAi.knowledgeBase.documents.move("i2YYI6huwBmcgYydAXARmQJc3pmX", {
  moveTo: folder.id,
});
```

## Dependências e exclusão

Cada documento tem uma aba **Agentes dependentes** que lista os agentes que dependem dele no momento.

![Visualização dos detalhes do documento mostrando a aba de
agentes dependentes](/docs/_fern-img/20ecce9f1db77d27bdf760b4a90c9bd2baacb612b48cf660e0f395c82aa3a725.webp)

Um documento não pode ser excluído enquanto um agente depender dele. Primeiro, remova o documento desses agentes ou use a exclusão forçada para desvinculá-lo de todos os dependentes de uma vez.