AI 에이전트 데모는 대개 질문을 입력하면 모델이 답하는 장면에서 끝난다. 하지만 기업 환경에서 중요한 질문은 답변의 자연스러움보다 그 다음에 있다. 어떤 데이터에 접근했는가, 다른 고객의 정보가 섞일 가능성은 없는가, 실제 업무를 변경하기 전에 누가 승인했는가, 실행이 중단된 뒤 같은 작업이 두 번 생기지는 않는가를 설명할 수 있어야 한다.
enterprise-agent-reference는 이 문제를 하나의 완성된 세로 단면으로 다룬다. 가상의 운영 담당자가 고객 상황과 정책을 조사하고, 근거를 인용한 권고를 받은 뒤, 후속 작업 생성 직전에 사람의 승인을 거치는 흐름이다. 기능 수는 많지 않지만 요청의 시작부터 데이터 조회, 승인, 재개, 감사까지 한 경로를 끝까지 연결한다.
한 번의 요청이 지나가는 경로
사용자는 Streamlit 화면에서 질문하지만 프런트엔드는 에이전트 패키지를 직접 불러오지 않는다. 모든 요청은 FastAPI의 버전이 붙은 HTTP 계약을 통과한다. API는 인증 문맥과 대화 스레드를 준비하고, 요청 단위 MCP 클라이언트를 만들어 에이전트가 사용할 수 있는 도구만 전달한다.
조사 작업은 두 전문 에이전트로 나뉜다.
account_analyst는 고객과 지원 사례처럼 구조화된 운영 기록을 조회한다.policy_researcher는 정책 문서를 검색하고 인용 가능한 근거를 돌려준다.- supervisor는 두 결과를 종합하지만 민감한 쓰기 작업은 직접 완료하지 못한다.
후속 작업을 만들려 하면 Deep Agents의 interrupt가 발생한다. API는 제안된 인자를 승인 레코드와 체크포인트에 남기고 화면에 보여준다. 사용자가 승인하면 동일한 스레드의 체크포인트를 불러와 실행을 재개한다. 이때 승인 ID가 멱등성 키가 되고 Records MCP가 고객과 사례의 소유권을 다시 검사한 뒤 한 번만 기록한다.
저장소를 역할에 따라 나눈 이유
PostgreSQL은 고객, 사례, 후속 작업 같은 업무 데이터뿐 아니라 대화 스레드, 승인 상태, 체크포인트와 감사 이벤트를 가진다. 서로 강한 일관성이 필요한 상태를 한곳에서 관리하기 위해서다. 반면 OpenSearch는 정책 문서의 chunk, 검색 벡터, 인용 메타데이터를 맡는다. 검색을 위한 저장 구조와 트랜잭션 업무 데이터를 분리하면 각 저장소가 잘하는 일에 집중할 수 있다.
사용자 → Streamlit → FastAPI → Deep Agent
├─ Records MCP → PostgreSQL
└─ Knowledge MCP → OpenSearch이 구조에서 MCP는 단순한 연결 규격이 아니다. 모델과 업무 시스템 사이에 놓인 권한 경계다. 에이전트는 데이터베이스 연결 문자열도, 임의 SQL도, 파일 시스템도 받지 않는다. 허용된 이름과 입력 스키마를 가진 여섯 개 도구만 발견한다.
의도적으로 완성하지 않은 부분
이 레퍼런스는 로컬 Docker 구성을 production 플랫폼이라고 주장하지 않는다. 개발용 헤더 인증, 단일 PostgreSQL과 OpenSearch, 보안이 꺼진 로컬 검색 클러스터는 모두 명시적인 한계다. 실제 운영에서는 OIDC/JWT, 역할 기반 권한, 전송 구간 암호화, 관리형 데이터 서비스, 백업과 복구 훈련이 추가되어야 한다.
좋은 레퍼런스 아키텍처는 모든 문제를 해결한 척하지 않는다. 지금 보장하는 것과 다음 단계에서 보강할 것을 구분한다.
이 프로젝트의 가치는 화려한 자율성보다 경계를 관찰할 수 있다는 데 있다. 하나의 요청이 어느 서비스를 지났고, 누가 승인했으며, 어떤 근거로 어떤 쓰기가 발생했는지 코드와 테스트에서 추적할 수 있다. 앞으로의 글에서는 이 흐름을 구성하는 각각의 결정을 분리해 살펴본다.
확인할 질문
- 모델이 접근할 수 있는 시스템과 도구가 명시되어 있는가?
- 읽기와 쓰기의 권한 경계가 다른가?
- 사용자에게 보여주는 상태와 에이전트 실행 상태가 분리되어 있는가?
- 중단과 재시도 후에도 같은 부작용이 한 번만 발생하는가?
- 현재 구현의 한계를 문서에서 숨기지 않는가?