Flujos de trabajo de agentes
Nuevo en 0.4.0
Todo lo de esta página llegó en v0.4.0. Si ducklocal check --help no muestra --restricted, tu copia es más antigua; actualiza para usarlo.
Un agente ya puede consultar archivos, crear un panel y leer tus comentarios con la CLI. 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 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.
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 tiene el modelo de amenazas completo y lo que se probó en cada plataforma.
Mantente sincronizado con la ventana
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.
ducklocal open --state --active # note `revision`
ducklocal open --if-revision REV --run --wait \
--title "Revenue by channel" --sql "SELECT ..."--waitespera hasta 5 minutos y añadestatus,tab_id,result_status,erroryrevisiona la salida.--if-revision REVno abre nada si la ventana ya no muestra esa revisión, y sale con código 1 y kindstale. 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 enumera todos los campos y tipos de error, y el esquema JSON describe el estado.
Propón un cambio en un panel
Cuando quieres aprobar un cambio, un agente puede proponerlo en lugar de editar el archivo:
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 rejectedLa 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 --restrictedsobre ella primero.
Registra cómo se llegó a un análisis
Define DUCKLOCAL_SESSION, y query, check, propose y open registran cada uno lo que hicieron:
export DUCKLOCAL_SESSION=analysis.session.jsonl
ducklocal session note --text "EU revenue fell 12%" --refs 3,4
ducklocal session show --last 20Sin 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
ducklocal project init # write ducklocal-project.json
ducklocal project check # what a move would break
ducklocal project relink --source orders --to data/2026/orders.csvUn 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
Una clave filtrada, investigada por un agente y una persona 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.
