# Archivos del agente

> Gestiona los archivos de la base de conocimiento de un agente.

Fuente: https://developers.plazbot.com/cli/agent/files/

### Base de conocimiento

Gestiona los archivos (PDF, DOC, DOCX) que el agente usa como base de conocimiento: listar, agregar desde una URL pública, revisar el estado de procesamiento y eliminar.

```bash
plazbot agent files <list|add|status|delete> [args] [options]
```

## files list

Lista los archivos de la base de conocimiento de un agente.

```bash
plazbot agent files list <agentId> [options]
```

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| `agentId` | (posicional) | Sí | ID del agente. |
| JSON | `--json` | No | Imprime los archivos como un arreglo JSON (`fileId`, `name`, `tags`). Por defecto: `false`. |

### Ejemplos

```bash
# Listar los archivos de un agente
plazbot agent files list age_AbcDef123

# Obtener los archivos en JSON
plazbot agent files list age_AbcDef123 --json
```

### Resultado

```text
Files - Sales Plazbot
────────────────────────────────────────
┌───────────────┬─────────┬──────────────────┐
│ ID            │ Name    │ Tags             │
├───────────────┼─────────┼──────────────────┤
│ fil_AbcDef123 │ manual  │ docs, onboarding │
├───────────────┼─────────┼──────────────────┤
│ fil_XyzUvw456 │ precios │ sales, 2026      │
└───────────────┴─────────┴──────────────────┘
```

Sin archivos: `No files in the knowledge base.` y la sugerencia `Add one with: plazbot agent files add age_AbcDef123 -u <url>`.

### Salida JSON

```json
[
{ "fileId": "fil_AbcDef123", "name": "manual", "tags": ["docs", "onboarding"] }
]
```

## files add

Agrega un archivo remoto a la base de conocimiento. La URL debe ser pública. El procesamiento es asíncrono: revisa el estado con `files status`.

```bash
plazbot agent files add <agentId> -u <url> [options]
```

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| `agentId` | (posicional) | Sí | ID del agente. |
| URL | `-u, --url <url>` | Sí | URL pública http(s) del archivo (PDF, DOC, DOCX). |
| Referencia | `-r, --reference <name>` | No | Nombre de referencia en la base de conocimiento. Por defecto: el nombre del archivo sin extensión. |
| Etiquetas | `-t, --tags <tags>` | No | Etiquetas separadas por comas, por ejemplo `docs,onboarding`. Por defecto: ninguna. |
| JSON | `--json` | No | Imprime el resultado como JSON (`{"fileId","agentId","reference","status"}`). Por defecto: `false`. |

### Ejemplos

```bash
# Agregar un manual en PDF
plazbot agent files add age_AbcDef123 -u https://files.example.com/manual.pdf

# Agregar un archivo con referencia y etiquetas
plazbot agent files add age_AbcDef123 -u https://files.example.com/precios.docx -r precios -t sales,2026
```

### Resultado

```text
✔ File added
Reference: manual
File ID: fil_AbcDef123
The file is being processed. Check the status with:
plazbot agent files status fil_AbcDef123
```

Si la extensión no es PDF, DOC ni DOCX, se muestra un aviso (`The file extension ".xlsx" may not be supported (expected PDF, DOC or DOCX).`) y el archivo se envía igual.

### Salida JSON

```json
{ "fileId": "fil_AbcDef123", "agentId": "age_AbcDef123", "reference": "manual", "status": "processing" }
```

## files status

Revisa si un archivo terminó de procesarse.

```bash
plazbot agent files status <fileId> [options]
```

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| `fileId` | (posicional) | Sí | ID del archivo (de `files add` o `files list`). |
| JSON | `--json` | No | Imprime el estado como JSON (`{"fileId","status"}`). Por defecto: `false`. |

### Ejemplos

```bash
# Revisar un archivo
plazbot agent files status fil_AbcDef123

# Revisar un archivo en JSON
plazbot agent files status fil_AbcDef123 --json
```

### Resultado

```text
File status
────────────────────────────────────────
File ID: fil_AbcDef123
Status: Completed
```

El estado es `Completed` o `Processing`.

### Salida JSON

```json
{ "fileId": "fil_AbcDef123", "status": "completed" }
```

`status` es `completed` o `processing`.

## files delete

Elimina un archivo de la base de conocimiento. Pide confirmación antes de borrar.

```bash
plazbot agent files delete <agentId> <fileId> [options]
```

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| `agentId` | (posicional) | Sí | ID del agente. |
| `fileId` | (posicional) | Sí | ID del archivo. |
| JSON | `--json` | No | Imprime el resultado como JSON (`{"agentId","fileId","deleted"}`). Por defecto: `false`. |
| Confirmar | `-y, --yes` | No | Omite la confirmación (scripts y CI). Alias: `--confirm`. Por defecto: `false`. |

### Ejemplos

```bash
# Eliminar un archivo (pide confirmación)
plazbot agent files delete age_AbcDef123 fil_AbcDef123

# Eliminar sin preguntar (scripts y CI)
plazbot agent files delete age_AbcDef123 fil_AbcDef123 --yes
```

### Resultado

```text
? Delete file fil_AbcDef123 from agent age_AbcDef123? This cannot be undone. (y/N) y
✔ File deleted
```

Si respondes que no, se imprime `Aborted.` y el comando termina con código 1.

### Salida JSON

```json
{ "agentId": "age_AbcDef123", "fileId": "fil_AbcDef123", "deleted": true }
```

### Errores comunes

| Mensaje | Causa | Solución |
|---------|-------|----------|
| `error: required option '-u, --url <url>' not specified` | `files add` sin `-u`. | Pasa la URL con `-u`. |
| `Invalid URL "<valor>".` | La URL no es válida. | Usa un enlace público, por ejemplo `-u https://files.example.com/manual.pdf`. |
| `The file URL must start with http:// or https://.` | Protocolo distinto de http o https. | Usa una URL http(s). |
| `The API rejected the file.` | La API no aceptó el archivo. | Revisa que la URL sea pública y el formato sea PDF, DOC o DOCX. |
| `This action needs confirmation and there is no interactive terminal.` | `files delete` sin terminal (o con `--json`) y sin `--yes`. | Agrega `--yes`. |
| `You are not signed in.` | No hay sesión activa. | Ejecuta [`plazbot login`](https://developers.plazbot.com/cli/login). |