# 에이전트 워크플로

> DuckLocal 0.4.0이 AI 에이전트를 위해 추가한 것: 제한된 SQL, 창으로의 검증 가능한 핸드오프, 대시보드 제안, 분석 기록, 이동 가능한 프로젝트.

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

::: info 0.4.0의 새로운 기능
이 페이지의 모든 내용은 [v0.4.0](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.0)에 포함되어 있습니다. `ducklocal check --help`에 `--restricted`가 보이지 않는다면 사용 중인 버전이 오래된 것이니, [업데이트](getting-started.md)한 뒤 사용하세요.
:::

에이전트는 이미 [CLI](cli.md)로 파일을 쿼리하고, 대시보드를 만들고, 주석을 읽을 수 있습니다. 여기서 추가된 기능은 그 작업을 둘러싼 부분을 다룹니다. 에이전트가 직접 작성하지 않은 SQL을 제한하고, 창이 요청을 어떻게 처리했는지 확인하고, 변경을 직접 승인하고, 답에 어떻게 도달했는지 기록하는 것입니다.

## 직접 작성하지 않은 SQL 제한하기 {#restricted}

`--restricted`는 데이터에서 복사해 온 SQL과 다른 사람이 만든 대시보드를 위한 것입니다. 읽기 전용 모드만으로는 부족합니다. 읽기 전용은 데이터베이스 파일을 보호하지만, `COPY`는 여전히 권한이 있는 곳 어디든 쓸 수 있고 `FROM 'https://...'`는 여전히 요청을 보낼 수 있습니다.

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

| SQL이 시도하는 것 | 결과 |
| --- | --- |
| `--allow-read` 아래의 파일 읽기 | 허용 |
| 경로, glob, `..`로 다른 파일 읽기 | 거부 |
| 파일 쓰기, 심지어 `--allow-read` 아래라도 | 거부 |
| 데이터베이스 `ATTACH` 또는 생성 | 거부 |
| `http`, `https`, `s3` 또는 다른 URL 접근 | 거부 |
| 확장 기능 `INSTALL` 또는 `LOAD` | 거부 |
| 이 제한을 포함한 설정 변경 | 거부 |
| `--timeout`(기본 60초)보다 오래 실행 | 중단됨, kind `timeout` |
| `--memory-limit`(기본 `2GB`)보다 많이 사용 | 실패, kind `resource_limit` |

`--allow-read`를 주지 않으면 어떤 파일도 읽을 수 없으며, 대시보드가 있는 폴더도 마찬가지입니다. 거부된 문은 kind `policy_denied`로 종료 코드 1을 반환하고, 제한 없이 실행되는 쪽으로 절대 되돌아가지 않습니다. 문은 하나의 SELECT여야 하므로 `EXPLAIN`, `PRAGMA`, 최상위 `PIVOT`도 거부됩니다.

**이것은 샌드박스가 아닙니다.** 이 제한은 DuckDB 자체의 것이며, DuckLocal은 어떤 플랫폼에서도 운영체제 수준의 격리를 적용하지 않습니다. 제한이 구속하는 것은 SQL이지, 플래그를 고르는 사람이 아닙니다. 셸을 가진 에이전트는 `--restricted`를 그냥 뺄 수 있습니다. 신뢰하지 않는 에이전트를 가두려면 에이전트 자체를 컨테이너나 VM에서 실행하세요. `schema`, `profile`, `project check`, `open --run`은 제한 모드로 실행되지 않으며, 창이 대시보드를 열 때도 마찬가지입니다.

전체 위협 모델과 플랫폼별 테스트 내용은 [에이전트가 실행하는 SQL을 제한한다는 것](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-security.md)에 정리되어 있습니다.

## 창과 보조 맞추기 {#handoff}

`ducklocal open`은 예전에는 전달 여부만 보고했습니다. 이제 두 개의 플래그가 요청이 어떻게 끝났는지 보고하고, 이미 바뀐 창에 대해 작업하는 것을 막습니다.

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

- `--wait`는 최대 5분 기다리며 출력에 `status`, `tab_id`, `result_status`, `error`, `revision`을 추가합니다.
- `--if-revision REV`는 창이 더 이상 그 revision을 보여주지 않으면 아무것도 열지 않고, kind `stale`로 종료 코드 1을 반환합니다. 다시 시도하기 전에 상태를 다시 읽으세요. 다른 탭에서 사람이 타이핑하는 것도 의도적으로 stale을 만듭니다.

`--state`는 이제 다음도 보고합니다.

| 필드 | 의미 |
| --- | --- |
| `schema_version`, `revision` | 계약의 버전, 그리고 창이 보여주는 내용을 가리키는 토큰 |
| `actions` | 최근 요청이 어떻게 되었는지: `stale`, `queued`, `running`, `opened`, `succeeded`, `failed` |
| `limits` | 미리보기의 한도. 읽기는 전체 결과를 반환하지 않습니다 |
| `connections` | S3의 endpoint와 region, 그리고 연결된 각 데이터베이스의 이름, 종류, 위치, 주소. **키는 절대 포함되지 않습니다** |
| `result.reach` | `local`, `remote`, `unknown`. SQL만 보고 판단하며, S3 키를 사용했는지도 알려줍니다 |
| `sql_withheld` | 탭의 SQL에 자격 증명이 있을 수 있으면 `true`이고, 텍스트가 대체됩니다 |
| 각 plot의 `scope` | 그 plot이 쿼리 결과의 얼마만큼을 그리는지 |

`reach`는 SQL에 적힌 것만 볼 수 있으므로, 원격 데이터 위에 만든 로컬 뷰는 `local`로 표시됩니다. 이 정보를 읽는 데는 네트워크 요청이 발생하지 않습니다. 따라서 `location: "remote"`는 데이터베이스가 어디에 있는지를 뜻할 뿐, 여전히 응답한다는 뜻은 아닙니다.

에이전트는 키를 보지 않고도 S3가 설정되어 있음을 알 수 있지만, `open --run`으로 실행하는 SQL은 여전히 그 키를 사용할 수 있습니다.

모든 필드와 오류 kind는 [핸드오프 계약](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-handoff.md)에, 상태 구조는 [JSON schema](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-state-v1.schema.json)에 정리되어 있습니다.

## 대시보드 변경 제안하기 {#propose}

변경을 승인받고 싶을 때, 에이전트는 파일을 고치는 대신 제안할 수 있습니다.

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

스펙은 그대로 남고, 대시보드 탭에 변경이 대기 중임이 표시됩니다. **검토** 를 클릭하면 제안된 SQL을 실행하고 diff와 검사 결과를 보여주며, 그다음 **적용** 또는 **거부** 를 클릭합니다.

- 제안을 적용할 수 있는 것은 창에서 직접 조작하는 본인뿐입니다. 그에 해당하는 명령은 없습니다.
- 적용하면 이전 버전이 `sales.dash.bak`으로 남고, 제안 이후 스펙이 바뀌었다면 거부됩니다.
- 거부하면 스펙은 그대로입니다.
- **검토** 를 클릭하면 제안된 SQL이 실행되므로, 신뢰하지 않는 제안은 대시보드의 SQL이 닿을 수 있는 곳에 모두 닿을 수 있습니다. 먼저 `check --restricted`를 실행하세요.

## 분석이 어떻게 여기까지 왔는지 기록하기 {#session}

`DUCKLOCAL_SESSION`을 설정하면 `query`, `check`, `propose`, `open`이 각각 한 일을 기록합니다.

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

이 변수가 없으면 아무것도 기록되지 않습니다. 파일에는 SQL과 스펙 텍스트, 각 데이터 소스의 크기와 수정 시각, 각 결과의 형태가 들어가며, 행은 절대 들어가지 않습니다. 오류는 최대 500자까지 보관되고 값을 인용할 수 있으므로, 공유할 생각이 없다면 이 파일을 공유 폴더에 두지 마세요.

각 단계와 결론에는 `doubts`가 붙고, 파일을 읽을 때 계산됩니다. 무엇이 실패했는지, 잘렸는지, 이후에 바뀌었는지입니다. 목록이 비어 있다는 것은 그에 반하는 알려진 것이 없다는 뜻이지, 맞다는 뜻은 아닙니다.

자격 증명이 있을 수 있는 SQL은 제외됩니다. 이 검사는 `secret`, `token`, `access_key` 같은 단어를 기준으로 하므로, 그런 이름을 가진 열이 있으면 그 쿼리도 함께 가려집니다.

## 분석을 옮길 수 있게 유지하기 {#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
```

`ducklocal-project.json`은 선택 사항입니다. 폴더의 대시보드와 그것들이 필요로 하는 것을 나열하며, 데이터는 참조만 하고 절대 복사하지 않습니다. 창에서 이 파일을 열면 해당 대시보드들이 열립니다.

`project check`는 `ok`, `portable`, `problems`(각 항목에 `hint` 포함), `limitations`를 보고하고, 무엇을 찾든 종료 코드 0을 반환하므로 출력을 읽어야 합니다. 네트워크에 접속하지도, 무언가를 설치하지도 않습니다. 통과했다고 해서 데이터가 같다는 것이 증명되지는 않습니다. `project relink`는 대시보드를 바꾸고 이전 버전을 각각 `NAME.dash.bak`으로 남깁니다.

## 단계별 예시 {#worked-example}

[유출된 키, 에이전트와 사람이 함께 조사하다](https://github.com/JetSquirrel/DuckLocal/tree/main/examples/cloudtrail_investigation)는 가상의 일주일치 CloudTrail 로그를 첫 쿼리부터 검토가 끝난 대시보드까지 따라갑니다. 에이전트가 맡는 부분은 변경이 있을 때마다 테스트로 실행됩니다. 창이 맡는 부분은 아직 아무도 직접 클릭해 보지 않았으며, 어떤 단계인지는 README에 적혀 있습니다.
