4.6 AI Agent 워크플로우
코드를 생성하는 agent는 database schema도 바꿉니다. 사람이 리뷰하기 전에 agent가 실행한 ALTER TABLE이 공용 개발 database에 남으면 다른 작업을 방해하고, 되돌리기도 어렵습니다. branch가 수 초에 만들어지고 diverge한 만큼만 비용이 드는 구조에서는 agent마다, 나아가 agent의 시도마다 별도의 database를 할당할 수 있습니다. 이 장은 그 구성을 정리합니다.
기본 원칙: agent는 branch 안에서만 쓴다
agent에게 production이나 공용 개발 branch의 쓰기 권한을 주지 않습니다. 작업 시작 시점에 branch를 만들고, 그 연결 문자열만 넘깁니다. 결과를 사람이 검토한 뒤 migration 파일 형태로 코드 저장소에 반영합니다. database 상태를 직접 승격하지 않습니다. 대신 코드로 남긴 변경을 정상 배포 경로로 적용합니다.
도식에서 snapshot이 main에 붙어 있는 것은 실수가 아닙니다. snapshot 생성은 root branch에서만 지원되므로 agent/task-42 같은 자식 branch에서는 만들지 못합니다. 자식 branch의 되돌리기는 reset --parent나 history window 안의 restore로 처리합니다.
MCP server로 branch 조작
Neon MCP server는 agent가 도구를 통해 Neon API를 호출하게 합니다. 원격 endpoint는 https://mcp.neon.tech/mcp이고, 로컬 설정은 CLI가 안내합니다.
npx neon@latest mcp
제공되는 도구는 프로젝트 관리, branch 관리(생성, reset, 삭제), compute 관리 등입니다. snapshot 생성과 복원, schema 조회와 비교, SQL 실행, migration 준비와 완료 도구도 제공합니다. branch 생성 도구는 parentId를 받아 default branch가 아닌 임의의 branch에서도 분기합니다. 이 인자가 없던 시기에는 agent가 항상 default branch에서만 분기했습니다. 지금은 agent용 기준 branch를 따로 두고 그 아래에 작업 branch를 만드는 구성이 가능합니다.
migration 흐름은 두 단계로 나뉩니다. 준비 단계에서는 임시 branch를 만들어 DDL을 적용한 결과를 보여 줍니다. 사람이 승인하면 완료 단계에서 대상 branch에 같은 변경을 적용합니다. 도구 설계에는 사람이 중간에 검토하는 지점이 포함됩니다.
MCP server는 읽기 전용 모드(?readonly=true)를 지원합니다. 조회만 필요한 agent에는 이 모드를 씁니다. 문서는 MCP를 production database에 연결하지 말고 개발과 테스트에 한정하라고 안내합니다.
체크포인트로서의 snapshot
agent가 여러 단계로 작업할 때는 각 단계가 끝난 시점을 되돌릴 수 있게 남겨 두는 편이 좋습니다. snapshot이 그 역할을 하지만 제약이 있습니다. snapshot은 root branch에서만 생성됩니다. 대상은 positional 인자가 아니라 --branch 옵션으로 지정합니다. 따라서 단계별 체크포인트를 snapshot으로 남기려면 agent의 작업 database가 자식 branch가 아니라 독립 root branch여야 합니다.
Neon 문서가 권하는 구성은 agent 프로젝트마다 root branch 하나를 두고 그 branch를 계속 쓰는 방식입니다. 단계마다 snapshot을 만듭니다. 되돌릴 때는 snapshot을 복원해 compute endpoint를 새 branch로 옮깁니다. 연결 문자열이 유지되므로 agent 설정을 고칠 필요가 없습니다.
# agent 전용 프로젝트의 root branch 를 대상으로 합니다.
neon snapshots create --branch main --name step-1-schema
# agent 작업 진행
neon snapshots create --branch main --name step-2-backfill
# 되돌리기: 복원 branch 를 만들고 endpoint 를 옮깁니다.
neon snapshots restore <snapshot id> --finalize
수동 snapshot 한도는 Free 1개, 유료 플랜 100개입니다. 단계마다 snapshot을 남기는 agent는 이 한도를 빠르게 소모합니다. 따라서 오래된 snapshot을 지우는 단계가 필요합니다.
작업 database를 main의 자식 branch로 두는 구성이라면 snapshot을 사용하지 못합니다. 이때 되돌리기는 두 가지입니다. 작업 전체를 버리려면 reset --parent로 부모 상태로 되돌립니다. 중간 시점으로 가려면 history window 안에서 restore ^self@<timestamp>를 씁니다. 다만 자기 과거 restore는 root branch에서만 지원합니다. 따라서 자식 branch에 남는 방법은 reset뿐입니다. 단계별 되돌리기가 요구사항이라면 처음부터 root branch 구성을 고릅니다.
코드 저장소의 커밋과 database snapshot을 짝지어 둡니다. 그러면 database가 "이 커밋이 기대하는 schema"에 맞춰집니다. Neon은 이 조합을 agent 환경의 versioning으로 설명합니다.
작업 단위와 branch 이름
agent에게 branch를 어떤 단위로 주는지가 운영 부담을 정합니다. 주로 세 가지 단위를 사용합니다.
| 단위 | branch 수명 | 맞는 경우 |
|---|---|---|
| agent 인스턴스 | 인스턴스가 살아 있는 동안 | 장기 실행 agent, 대화형 조수 |
| 작업(task) | 작업 시작에서 리뷰 완료까지 | 티켓 단위 코드 생성 |
| 시도(attempt) | 한 번의 실행 | 자동 재시도, 평가 벤치마크 |
작업 단위가 가장 흔합니다. 같은 작업을 재시도할 때는 reset --parent로 branch를 재사용합니다. 작업이 끝나면 branch를 지웁니다. 시도 단위는 branch 수가 빠르게 늘어 한도에 걸리기 쉬우므로 만료 시간을 짧게 설정합니다.
이름은 기계가 처리하기 쉬운 규칙으로 정합니다. agent/<작업 ID> 형태를 사용하면 agent는 이름으로 자기 branch를 찾습니다. 정리 스크립트도 접두어로 agent branch만 선별합니다.
neon branches list --output json \
| jq -r '.[] | select(.name | startswith("agent/")) | [.name, .created_at] | @tsv'
실패 처리
사람이 agent가 만든 변경을 검토해 거부하면 branch를 지웁니다. 재시도하려면 reset --parent로 부모 상태로 되돌리고 같은 branch를 재사용합니다. 연결 문자열이 바뀌지 않으므로 agent 설정을 고칠 필요가 없습니다.
neon branches reset agent/task-42 --parent
agent가 DROP TABLE처럼 되돌리기 어려운 문장을 실행해도 변경은 branch 안에만 남습니다. 따라서 부모에는 영향이 없습니다. 이 격리가 agent에게 쓰기 권한을 주는 근거입니다.
규모
agent 플랫폼은 사용자마다, 세션마다 database를 만드는 경우가 있습니다. Neon 문서는 API로 수만 개 프로젝트를 관리하는 구성을 언급합니다. 또한 전체적으로 수백만 개 데이터베이스를 운영하는 구성도 언급합니다. 프로젝트와 데이터베이스는 단위가 다르므로 규모를 읽을 때 구분해야 합니다. 이 규모에서는 사람이 개별 branch를 확인하지 않으므로 다음 자동화가 필요합니다.
- 생성 시점에 만료 시간을 설정합니다. agent 작업은 대부분 몇 시간 안에 끝나므로 하루 정도가 보통입니다.
- 작업 완료 이벤트에서 branch를 명시적으로 지웁니다. 만료는 지우기를 놓쳤을 때의 보조 장치입니다.
- compute 크기를 작게 고정합니다. agent의 DDL 검증에는 0.25 CU가 대부분 충분합니다.
- Free 플랜은 10개가 생성 상한이므로 동시 작업 수를 그 아래로 유지하는 큐가 필요합니다. Launch와 Scale은 포함량(10개, 25개)을 넘겨도 생성이 계속됩니다. 초과분에는 branch 단위 요금이 부과되며, 프로젝트당 5,000개에서 생성이 제한됩니다. 유료 플랜에서 큐를 두는 이유는 생성 실패 방지가 아닙니다. 비용을 예측 가능하게 만들기 위해서입니다.
플랜 문서에는 agent 플랫폼을 위한 Agent Plan이 예정되어 있다고 나와 있습니다. 한도와 가격이 다를 수 있으므로 대량 구성을 계획한다면 그 플랜의 조건을 확인합니다.
비용
agent branch의 비용은 storage와 compute에서 발생합니다. storage는 diverge한 page만 차지하므로 schema 변경과 소량 backfill이면 비용이 작습니다. compute는 branch마다 할당되므로 동시에 살아 있는 agent 수에 비례합니다. scale to zero의 기본값은 5분입니다. 따라서 agent가 쉬는 동안 compute는 멈춥니다. 하지만 agent가 주기적으로 연결을 유지하면 계속 켜져 있습니다. agent 클라이언트가 idle 연결을 오래 유지하지 않도록 합니다.
snapshot이 가리키는 layer는 GC 대상에서 제외됩니다. 단계마다 snapshot을 만들고 지우지 않으면 오래된 layer가 쌓입니다. 작업이 끝나면 마지막 snapshot 하나만 남기고 나머지를 정리하는 단계를 넣습니다. 비용 구조는 6.1 비용 모델을 참고합니다.
검토 지점
agent 결과를 사람이 검토할 때는 schema-diff를 씁니다. 부모와 agent branch의 schema 차이가 SQL로 표시됩니다. 리뷰어는 migration 파일과 diff를 나란히 봅니다.
neon branches schema-diff main agent/task-42 --database app
diff에 의도하지 않은 변경이 있으면 agent가 지시하지 않은 DDL을 실행한 것입니다. 이 경우 branch를 지우고 지시를 고쳐 다시 시작합니다. diff가 migration 파일과 일치하면 branch 대신 migration 파일을 PR로 올립니다. branch는 검증 증거로 잠시 보관했다가 PR이 머지되면 지웁니다.
데이터 변경은 schema-diff에 나타나지 않습니다. agent가 backfill이나 데이터 정정을 수행했다면 SELECT count(*)나 체크섬 쿼리를 부모와 agent branch에서 각각 실행해 비교하는 단계를 리뷰에 넣습니다.
권한 설계
agent에 넘기는 API key의 범위는 필요한 프로젝트로 제한합니다. 조직 전체 key를 agent에 주면 다른 프로젝트의 branch까지 지울 수 있습니다. 연결 문자열의 role도 마찬가지입니다. agent가 접속하는 role에는 필요한 schema 권한만 부여합니다. 다른 database나 확장 설치 권한은 주지 않습니다.
문서는 MCP를 통한 조작을 실행 전에 사람이 검토하라고 권합니다. 자동 승인을 설정하면 branch 삭제처럼 되돌릴 수 없는 도구 호출도 검토 없이 실행됩니다.
흔한 실패
agent가 branch 생성 도구를 반복 호출해 한도에 도달하는 경우가 있습니다. 같은 작업에는 같은 branch 이름을 사용하도록 합니다. 이미 있으면 재사용하는 규칙을 agent 지시에 넣습니다.
agent가 만든 branch에서 CREATE EXTENSION이 실패하면 Neon이 지원하는 확장 목록에 없는 확장일 가능성이 높습니다. 지원 목록은 6.4 호환성과 제약 목록을 참고합니다.
연습 문제
- MCP server를 읽기 전용으로 연결해 agent가 schema를 설명하도록 하고, 쓰기 도구가 거부되는지 확인합니다.
- agent용 root branch에 snapshot 두 개를 만듭니다. 두 번째 단계 뒤에 첫 snapshot을 복원해 새 branch가 생기는지 확인합니다. 자식 branch를 대상으로 같은 명령을 실행하고, 거부되는지도 확인합니다. Free 플랜은 manual snapshot이 한 개까지이므로 Launch 이상이 필요합니다.
- 만료 1시간짜리 agent branch를 여러 개 만들어 시간이 지난 뒤 자동으로 정리되는지 확인합니다.