Ir al contenido

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.

bash
ducklocal query --restricted --allow-read ./data --sql "SELECT * FROM 'data/sales.csv'"
ducklocal check report.dash --restricted --allow-read ./data
El SQL intentaResultado
Leer un archivo bajo --allow-readPermitido
Leer cualquier otro archivo, por ruta, glob o ..Denegado
Escribir un archivo, incluso bajo --allow-readDenegado
Hacer ATTACH a una base de datos, o crear unaDenegado
Alcanzar http, https, s3 o cualquier otra URLDenegado
INSTALL o LOAD una extensiónDenegado
Cambiar un ajuste, incluidos estos límitesDenegado
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.

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:

CampoSignificado
schema_version, revisionLa versión del contrato y un token de lo que muestra la ventana
actionsQué fue de las peticiones recientes: stale, queued, running, opened, succeeded o failed
limitsLos límites de las previsualizaciones. Una lectura nunca devuelve un resultado completo
connectionsEl 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.reachlocal, remote o unknown, leído solo del SQL, y si usó tu clave de S3
sql_withheldtrue cuando el SQL de una pestaña puede contener una credencial, y el texto se sustituye
scope, en cada gráficoCuá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:

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 ​

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 ​

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 ​

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.

Publicado bajo la licencia Apache-2.0.