# Fluxos de trabalho de agentes

> O que o DuckLocal 0.4.0 acrescentou para agentes de IA: SQL restrito, uma entrega verificada para a janela, propostas de painel, registros de análise e projetos portáteis.

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

::: info Novo na 0.4.0
Tudo nesta página chegou na
[v0.4.0](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.0). Se
`ducklocal check --help` não lista `--restricted`, sua cópia é mais antiga;
[atualize](getting-started.md) para usá-lo.
:::

Um agente já consegue consultar arquivos, montar um painel e ler seus comentários
com a [CLI](cli.md). Estas novidades cobrem o que gira em torno desse trabalho:
limitar SQL que ele não escreveu, saber o que a janela fez com uma requisição,
deixar você aprovar uma mudança e registrar como uma resposta foi alcançada.

## Limite SQL que você não escreveu {#restricted}

`--restricted` serve para SQL copiado dos dados, e para um painel que outra pessoa
escreveu. O modo somente leitura sozinho não cobre isso: ele protege o arquivo do
banco de dados, enquanto `COPY` ainda pode escrever em qualquer lugar onde você
possa, e `FROM 'https://...'` ainda pode enviar uma requisição.

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

| O SQL tenta | Resultado |
| --- | --- |
| Ler um arquivo sob `--allow-read` | Permitido |
| Ler qualquer outro arquivo, por caminho, glob ou `..` | Negado |
| Escrever um arquivo, mesmo sob `--allow-read` | Negado |
| Fazer `ATTACH` de um banco de dados, ou criar um | Negado |
| Alcançar `http`, `https`, `s3` ou qualquer outra URL | Negado |
| `INSTALL` ou `LOAD` de uma extensão | Negado |
| Mudar uma configuração, incluindo estes limites | Negado |
| Rodar por mais de `--timeout` (60 segundos por padrão) | Interrompido, kind `timeout` |
| Usar mais de `--memory-limit` (`2GB` por padrão) | Falha, kind `resource_limit` |

Sem `--allow-read`, nenhum arquivo é legível, e isso inclui a própria pasta do
painel. Uma instrução negada sai com código 1 e kind `policy_denied` e nunca cai
para a execução sem restrições. `EXPLAIN`, `PRAGMA` e um `PIVOT` de nível superior
também são recusados, porque a instrução precisa ser um único SELECT.

**Isto não é uma sandbox.** Os limites são os do próprio DuckDB, e o DuckLocal não
aplica isolamento de sistema operacional em nenhuma plataforma. Eles prendem o
SQL, não quem escolhe as flags: um agente com shell pode remover `--restricted`.
Para conter um agente em quem você não confia, execute o próprio agente em um
contêiner ou VM. `schema`, `profile`, `project check` e `open --run` não rodam
restritos, e a janela também não, quando abre um painel.

[O que limita o SQL executado por um agente](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-security.md)
traz o modelo de ameaças completo e o que foi testado em cada plataforma.

## Fique em sincronia com a janela {#handoff}

O `ducklocal open` antes informava a entrega e nada mais. Duas flags agora
informam como uma requisição terminou e protegem contra agir sobre uma janela que
mudou.

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

- `--wait` espera até 5 minutos e acrescenta `status`, `tab_id`, `result_status`,
  `error` e `revision` à saída.
- `--if-revision REV` não abre nada se a janela já não mostra aquela revisão, e
  sai com código 1 e kind `stale`. Releia o estado antes de tentar de novo. Uma
  pessoa digitando em outra aba também o deixa obsoleto, de propósito.

`--state` agora também informa:

| Campo | Significado |
| --- | --- |
| `schema_version`, `revision` | A versão do contrato, e um token para o que a janela mostra |
| `actions` | O que aconteceu com as requisições recentes: `stale`, `queued`, `running`, `opened`, `succeeded` ou `failed` |
| `limits` | Os limites das prévias. Uma leitura nunca devolve um resultado inteiro |
| `connections` | O endpoint e a região do S3, e o nome, tipo, localização e endereço de cada banco de dados anexado. **Nunca uma chave** |
| `result.reach` | `local`, `remote` ou `unknown`, lido só do SQL, e se ele usou sua chave do S3 |
| `sql_withheld` | `true` quando o SQL de uma aba pode conter uma credencial, e o texto é substituído |
| `scope`, em cada gráfico | Quanto da consulta o gráfico desenha |

`reach` só consegue ver o que o SQL nomeia, então uma visão local sobre dados
remotos é lida como `local`. Ler qualquer um destes dados não faz requisição de
rede, então `location: "remote"` diz onde um banco de dados está, não que ele
ainda responda.

Um agente consegue ver que o S3 está configurado sem ver a chave, mas o SQL que ele
executa com `open --run` ainda pode usar essa chave.

O [contrato de entrega](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-handoff.md)
lista todos os campos e kinds de erro, e o
[JSON schema](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-state-v1.schema.json)
descreve o estado.

## Proponha uma mudança em um painel {#propose}

Quando você quer aprovar uma mudança, um agente pode propô-la em vez de editar o
arquivo:

```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
```

A especificação continua como está, e a aba do painel mostra que há uma mudança
esperando. Clique em **Revisar** para executar o SQL proposto e ver o diff e as
verificações, e depois clique em **Aplicar** ou **Rejeitar**.

- Só você pode aplicar uma proposta, na janela. Não há comando para isso.
- Aplicar mantém a versão antiga como `sales.dash.bak`, e é recusado se a
  especificação mudou desde a proposta.
- Rejeitar deixa a especificação intacta.
- Clicar em **Revisar** executa o SQL proposto, então uma proposta em que você não
  confia pode alcançar tudo o que o SQL do painel alcança. Execute
  `check --restricted` nela primeiro.

## Registre como uma análise chegou até aqui {#session}

Defina `DUCKLOCAL_SESSION`, e `query`, `check`, `propose` e `open` registram cada um
o que fizeram:

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

Nada é registrado sem essa variável. O arquivo guarda texto de SQL e de
especificações, o tamanho e o horário de modificação de cada fonte, e a forma de
cada resultado, nunca suas linhas. Os erros são mantidos até 500 caracteres e
podem citar valores, então mantenha o arquivo fora de pastas compartilhadas, a
menos que você queira compartilhá-las.

Cada passo e cada conclusão tem `doubts`, calculado quando você lê o arquivo: o que
falhou, foi cortado ou mudou desde então. Uma lista vazia significa que nada se sabe
contra ele, não que esteja certo.

SQL que pode conter uma credencial fica de fora. Essa verificação se guia por
palavras como `secret`, `token` e `access_key`, então uma coluna com um desses
nomes também esconde sua consulta.

## Mantenha uma análise transportável {#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
```

Um `ducklocal-project.json` é opcional. Ele lista os painéis de uma pasta e do que
eles precisam; os dados são referenciados, nunca copiados. Abri-lo na janela abre
aqueles painéis.

`project check` informa `ok`, `portable`, `problems` (cada um com um `hint`) e
`limitations`, e sai com 0 seja o que encontrar, então leia a saída. Ele nunca
acessa a rede nem instala nada. Passar não prova que os dados são os mesmos.
`project relink` muda seus painéis e mantém cada antigo como `NAME.dash.bak`.

## Um exemplo completo {#worked-example}

[Uma chave vazada, investigada por um agente e uma pessoa](https://github.com/JetSquirrel/DuckLocal/tree/main/examples/cloudtrail_investigation)
percorre uma semana inventada de CloudTrail da primeira consulta até um painel
revisado. Um teste executa a metade do agente a cada mudança. Ninguém ainda
percorreu clicando a metade da janela deste exemplo, e o README dele diz quais
passos são esses.
