콘텐츠로 이동

에이전트 워크플로 ​

0.4.0의 새로운 기능

이 페이지의 모든 내용은 v0.4.0에 포함되어 있습니다. ducklocal check --help에 --restricted가 보이지 않는다면 사용 중인 버전이 오래된 것이니, 업데이트한 뒤 사용하세요.

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

직접 작성하지 않은 SQL 제한하기 ​

--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을 제한한다는 것에 정리되어 있습니다.

창과 보조 맞추기 ​

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미리보기의 한도. 읽기는 전체 결과를 반환하지 않습니다
connectionsS3의 endpoint와 region, 그리고 연결된 각 데이터베이스의 이름, 종류, 위치, 주소. 키는 절대 포함되지 않습니다
result.reachlocal, remote, unknown. SQL만 보고 판단하며, S3 키를 사용했는지도 알려줍니다
sql_withheld탭의 SQL에 자격 증명이 있을 수 있으면 true이고, 텍스트가 대체됩니다
각 plot의 scope그 plot이 쿼리 결과의 얼마만큼을 그리는지

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

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

모든 필드와 오류 kind는 핸드오프 계약에, 상태 구조는 JSON schema에 정리되어 있습니다.

대시보드 변경 제안하기 ​

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

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를 실행하세요.

분석이 어떻게 여기까지 왔는지 기록하기 ​

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 같은 단어를 기준으로 하므로, 그런 이름을 가진 열이 있으면 그 쿼리도 함께 가려집니다.

분석을 옮길 수 있게 유지하기 ​

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으로 남깁니다.

단계별 예시 ​

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

Apache-2.0 라이선스로 공개되었습니다.