# Flujos de trabajo de agentes

> Lo que DuckLocal 0.4.0 añadió para agentes de IA: SQL restringido, un traspaso verificado a la ventana, propuestas de panel, registros de análisis y proyectos portátiles.

Source: https://ducklocal.app/docs/es/agent-workflows

::: info Nuevo en 0.4.0
Todo lo de esta página llegó en [v0.4.0](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.0). Si `ducklocal check --help` no muestra `--restricted`, tu copia es más antigua; [actualiza](getting-started.md) para usarlo.
:::

Un agente ya puede consultar archivos, crear un panel y leer tus comentarios con la [CLI](cli.md). Estas novedades cubren lo que rodea a ese trabajo: limitar el SQL que no escribió, saber qué hizo la ventana con una petición, dejarte aprobar un cambio y registrar cómo se llegó a una respuesta.

## Limita el SQL que no escribiste {#restricted}

`--restricted` es para SQL copiado de los datos, y para un panel que escribió otra persona. El modo de solo lectura por sí solo no cubre esto: protege el archivo de la base de datos, mientras que `COPY` puede seguir escribiendo en cualquier sitio donde tú puedas y `FROM 'https://...'` puede seguir enviando una petición.

```bash
ducklocal query --restricted --allow-read ./data --sql "SELECT * FROM 'data/sales.csv'"
ducklocal check report.dash --restricted --allow-read ./data
```

| El SQL intenta | Resultado |
| --- | --- |
| Leer un archivo bajo `--allow-read` | Permitido |
| Leer cualquier otro archivo, por ruta, glob o `..` | Denegado |
| Escribir un archivo, incluso bajo `--allow-read` | Denegado |
| Hacer `ATTACH` a una base de datos, o crear una | Denegado |
| Alcanzar `http`, `https`, `s3` o cualquier otra URL | Denegado |
| `INSTALL` o `LOAD` una extensión | Denegado |
| Cambiar un ajuste, incluidos estos límites | Denegado |
| Ejecutarse más de `--timeout` (60 segundos por defecto) | Interrumpido, kind `timeout` |
| Usar más de `--memory-limit` (`2GB` por defecto) | Falla, kind `resource_limit` |

Sin `--allow-read`, no se puede leer ningún archivo, y eso incluye la propia carpeta de un panel. Una sentencia denegada sale con código 1 y kind `policy_denied`, y nunca recurre a ejecutarse sin restricciones. `EXPLAIN`, `PRAGMA` y un `PIVOT` de nivel superior también se rechazan, porque la sentencia debe ser un único SELECT.

**Esto no es una sandbox.** Los límites son los de DuckDB, y DuckLocal no aplica aislamiento del sistema operativo en ninguna plataforma. Atan el SQL, no a quien elige las flags: un agente con una shell puede quitar `--restricted`. Para contener a un agente en el que no confías, ejecuta el agente mismo en un contenedor o una VM. `schema`, `profile`, `project check` y `open --run` no se ejecutan restringidos, y tampoco la ventana cuando abre un panel.

[Qué limita el SQL que ejecuta un agente](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-security.md) tiene el modelo de amenazas completo y lo que se probó en cada plataforma.

## Mantente sincronizado con la ventana {#handoff}

`ducklocal open` antes solo informaba de la entrega y nada más. Ahora dos flags informan de cómo terminó una petición y protegen frente a actuar sobre una ventana que ha cambiado.

```bash
ducklocal open --state --active                  # note `revision`
ducklocal open --if-revision REV --run --wait \
  --title "Revenue by channel" --sql "SELECT ..."
```

- `--wait` espera hasta 5 minutos y añade `status`, `tab_id`, `result_status`, `error` y `revision` a la salida.
- `--if-revision REV` no abre nada si la ventana ya no muestra esa revisión, y sale con código 1 y kind `stale`. Vuelve a leer el estado antes de reintentar. Que una persona escriba en otra pestaña también lo deja obsoleto, a propósito.

`--state` ahora también informa de:

| Campo | Significado |
| --- | --- |
| `schema_version`, `revision` | La versión del contrato y un token de lo que muestra la ventana |
| `actions` | Qué fue de las peticiones recientes: `stale`, `queued`, `running`, `opened`, `succeeded` o `failed` |
| `limits` | Los límites de las previsualizaciones. Una lectura nunca devuelve un resultado completo |
| `connections` | El endpoint y la región de S3, y el nombre, tipo, ubicación y dirección de cada base de datos adjunta. **Nunca una clave** |
| `result.reach` | `local`, `remote` o `unknown`, leído solo del SQL, y si usó tu clave de S3 |
| `sql_withheld` | `true` cuando el SQL de una pestaña puede contener una credencial, y el texto se sustituye |
| `scope`, en cada gráfico | Cuánto de su consulta dibuja el gráfico |

`reach` solo puede ver lo que nombra el SQL, así que una vista local sobre datos remotos se lee como `local`. Leer cualquiera de estos datos no hace ninguna petición de red, así que `location: "remote"` dice dónde está una base de datos, no que siga respondiendo.

Un agente puede ver que S3 está configurado sin ver la clave, pero el SQL que ejecute con `open --run` puede seguir usando esa clave.

El [contrato de traspaso](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-handoff.md) enumera todos los campos y tipos de error, y el [esquema JSON](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-state-v1.schema.json) describe el estado.

## Propón un cambio en un panel {#propose}

Cuando quieres aprobar un cambio, un agente puede proponerlo en lugar de editar el archivo:

```bash
ducklocal propose sales.dash --status                  # note current_hash
ducklocal propose sales.dash --from new.dash --note "Split revenue by region" --based-on HASH
ducklocal propose sales.dash --status                  # pending, applied or rejected
```

La especificación se queda como está, y la pestaña del panel muestra que hay un cambio en espera. Haz clic en **Revisar** para ejecutar el SQL propuesto y ver el diff y las comprobaciones, y luego en **Aplicar** o **Rechazar**.

- Solo tú puedes aplicar una propuesta, en la ventana. No hay ningún comando para ello.
- Al aplicar se conserva la versión anterior como `sales.dash.bak`, y se rechaza si la especificación ha cambiado desde la propuesta.
- Rechazar deja la especificación intacta.
- Al hacer clic en **Revisar** se ejecuta el SQL propuesto, así que una propuesta en la que no confías puede llegar a todo lo que puede llegar el SQL del panel. Ejecuta `check --restricted` sobre ella primero.

## Registra cómo se llegó a un análisis {#session}

Define `DUCKLOCAL_SESSION`, y `query`, `check`, `propose` y `open` registran cada uno lo que hicieron:

```bash
export DUCKLOCAL_SESSION=analysis.session.jsonl
ducklocal session note --text "EU revenue fell 12%" --refs 3,4
ducklocal session show --last 20
```

Sin esa variable no se registra nada. El archivo contiene texto de SQL y de especificaciones, el tamaño y la fecha de modificación de cada fuente, y la forma de cada resultado, nunca sus filas. Los errores se guardan hasta 500 caracteres y pueden citar valores, así que mantén el archivo fuera de carpetas compartidas a menos que quieras compartirlas.

Cada paso y cada conclusión tiene `doubts`, calculado al leer el archivo: qué falló, quedó cortado o ha cambiado desde entonces. Una lista vacía significa que no se sabe nada en su contra, no que sea correcto.

El SQL que puede contener una credencial se omite. Esa comprobación se guía por palabras como `secret`, `token` y `access_key`, así que una columna con uno de esos nombres también oculta su consulta.

## Mantén un análisis transportable {#project}

```bash
ducklocal project init             # write ducklocal-project.json
ducklocal project check            # what a move would break
ducklocal project relink --source orders --to data/2026/orders.csv
```

Un `ducklocal-project.json` es opcional. Enumera los paneles de una carpeta y lo que necesitan; los datos se referencian, nunca se copian. Si lo abres en la ventana, se abren esos paneles.

`project check` informa de `ok`, `portable`, `problems` (cada uno con un `hint`) y `limitations`, y sale con 0 encuentre lo que encuentre, así que lee la salida. Nunca accede a la red ni instala nada. Que pase no demuestra que los datos sean los mismos. `project relink` cambia tus paneles y conserva cada uno de los antiguos como `NAME.dash.bak`.

## Un ejemplo completo {#worked-example}

[Una clave filtrada, investigada por un agente y una persona](https://github.com/JetSquirrel/DuckLocal/tree/main/examples/cloudtrail_investigation) recorre una semana inventada de CloudTrail desde la primera consulta hasta un panel revisado. Un test ejecuta la mitad del agente en cada cambio. Nadie ha hecho clic todavía en la mitad de la ventana de este ejemplo, y su README indica qué pasos son esos.
