AI 에이전트가 인프라를 환각하는 것을 막기: Cognee용 Docker Compose 커넥터 구축

Claude Code, Devin, Cursor, GitHub Copilot과 같은 자율 AI DevOps 및 코딩 에이전트는 배포 실패 문제 해결, CI/CD 파이프라인 구성, 로컬 다중 컨테이너 개발 환경 관리에 점점 더 많이 신뢰받고 있습니다.

하지만 개발자들이 에이전트에게 '종단 간(end-to-end) 테스트 스크립트를 작성해 달라'거나 '백엔드 네트워크 연결을 디버깅해 달라'와 같은 작업을 요청할 때, 그들은 공통적인 문제에 직면할 수 있습니다: 컨테이너 토폴로지 환각(container topology hallucination).

예를 들어:

• 서비스 호스트 이름 환각: 내부 네트워크 별칭인 db:5432 대신 localhost:5432를 호출하는 경우.
• 포트 혼동: Redis가 Compose 파일에서 6379:6379로 매핑되었음에도 불구하고, 에이전트가 잘못된 호스트-컨테이너 포트 매핑을 추측하여 6380에 노출되어 있다고 가정하는 경우.
• 볼륨 마운트 누락: 구성된 마운트와 일치하지 않는 영구 파일 경로를 가정하는 경우.
• 종속성 사각지대: depends_on 관계나 service_healthy와 같은 헬스 체크 조건이 누락되는 경우.

왜 이런 일이 발생할까요?

거대 언어 모델(LLMs)은 학습된 패턴과 자신에게 주어진 컨텍스트를 기반으로 응답을 생성합니다. 애플리케이션의 실제 인프라 구성에 대한 신뢰할 수 있는 접근 권한이 없으면, 그들은 그럴듯해 보이지만 실제로는 잘못된 명령어와 배포 스크립트를 생성할 수 있습니다.

컨테이너화된 개발 환경에서 compose.yaml 또는 docker-compose.yml은 서비스, 네트워크, 볼륨, 포트 매핑 및 환경 구성을 정의합니다.

만약 AI 에이전트가 추측하는 대신 이 인프라 정보를 검색할 수 있다면 어떨까요?

Mergetober의 일환으로, 저는 컨테이너 구성을 구조화된 지식 그래프와 검색 파이프라인을 통해 사용할 수 있도록 하는 Cognee용 Docker Compose 데이터 소스 커넥터를 개발했습니다.

본 글에서는 인프라 컨텍스트가 왜 중요한지 설명하고, 커넥터 아키텍처를 개괄하며, Cognee로 Docker Compose 구성을 가져오는(ingesting) 의도된 워크플로우를 시연할 것입니다.

1. Docker Compose 토폴로지가 중요한 이유

다중 컨테이너 애플리케이션에서 서비스들은 구성된 네트워크를 통해 통신하고, 포트를 노출하며, 볼륨을 마운트하고, 다른 서비스에 의존합니다.

일반적인 Docker Compose 파일은 여러 중요한 구성 요소를 정의합니다:

• 서비스 및 이미지(Services and images): postgres:16-alpine 및 redis:7과 같은 컨테이너 이미지, 빌드 컨텍스트(build contexts), 그리고 Dockerfile.
• 포트 바인딩(Port bindings): "8080:80" 및 "5432:5432"와 같은 호스트-대-컨테이너 매핑.
• 서비스 의존성(Service dependencies): depends_on 관계 및 service_healthy와 같은 조건.
• 환경 변수(Environment variables): 연결 문자열(Connection strings), 자격 증명(credentials), 그리고 서비스 URL.
• 볼륨 및 네트워크(Volumes and networks): 이름 지정된 볼륨(Named volumes), 바인드 마운트(bind mounts), 그리고 app-network와 같은 사용자 정의 네트워크.

이러한 컨텍스트 없이 AI DevOps 에이전트가 마이그레이션(migrations)을 실행하거나, 데이터베이스를 시딩(seed)하거나, 통합 테스트(integration tests)를 작성하거나, 네트워크 연결성을 디버깅하려고 할 때, 잘못된 가정을 할 수 있습니다.

전체 500줄짜리 Compose 파일을 모든 프롬프트에 붙여넣는 것은 한 가지 가능한 해결책이지만, 컨텍스트 창(context-window) 공간을 소모하고 관련 구성을 찾기 어렵게 만들 수 있습니다.

더 나은 접근 방식은 인프라 토폴로지(infrastructure topology)를 온디맨드(on demand)로 수집(ingest), 구조화(structure), 인덱싱(index), 그리고 검색(retrieve)하는 것입니다.

2. Cognee 소개: AI 에이전트를 위한 인프라 메모리

Cognee는 구조화된 지식(structured knowledge)과 검색(retrieval)을 사용하여 AI 메모리 시스템을 구축하기 위한 오픈 소스 프레임워크입니다.

Docker Compose와 Cognee를 결합하는 아이디어는 인프라 구성을 필요한 시점에 AI 에이전트가 더 쉽게 검색할 수 있도록 만드는 것입니다:

• 서비스 엔티티(Service entities): 서비스와 해당 구성을 검색 가능한 정보로 표현합니다.
• 의존성 관계(Dependency relationships): 인제스천 파이프라인에서 지원하는 경우, 서비스 간의 관계를 유지합니다.
• 의미론적 검색(Semantic retrieval): 개발자가 포트, 볼륨, 네트워크 및 의존성에 대해 자연어 질문을 할 수 있게 합니다.
• 근거 기반 데브옵스 워크플로우(Grounded DevOps workflows): 에이전트가 명령어, 테스트 또는 배포 스크립트를 생성하기 전에 구성 컨텍스트를 제공합니다.

예를 들어, 개발자는 다음과 같이 질문할 수 있습니다:

PostgreSQL에 의존하는 서비스는 무엇이며, 어떤 포트가 공개되어 있고, 어떤 상태 확인(health-check) 조건이 설정되어 있습니까?

검색 시스템은 에이전트의 응답을 위한 관련 Compose 구성을 컨텍스트로 제공할 수 있습니다. 결과의 품질은 구성이 얼마나 완전히 파싱되고, 표현되며, 검색되는지에 달려있습니다.

3. 아키텍처 개요: Docker Compose 커넥터

예상되는 데이터 흐름은 다음과 같습니다:

docker-compose.yml / compose.yaml
              |
              v
...

3.1. 안정적인 서비스 식별자(Stable Service Identifiers)

커넥터는 개별 서비스에 안정적인 식별자를 할당할 수 있습니다:

docker_compose:service:{서비스_이름}

안정적인 식별자는 반복되는 임포트 과정에서 서비스를 구분하는 데 도움을 줍니다. 이들이 중복 노드를 방지하는지는 커넥터와 인제스천 파이프라인이 엔티티의 정체성(entity identity)을 어떻게 처리하느냐에 달려있습니다.

3.2. 전체 스냅샷 동기화(Full-Snapshot Synchronization)

인프라 구성은 서비스가 추가, 제거 또는 수정됨에 따라 진화합니다.

스냅샷 기반의 동기화 전략은 인덱싱된 인프라 정보가 현재 Compose 파일과 일치하도록 유지하는 데 도움을 줄 수 있습니다. 하지만 write_disposition="replace"와 같은 설정은 커넥터와 기본 인제스천 파이프라인이 이를 명시적으로 지원할 때만 예상되는 교체 동작(replacement behavior)만을 제공합니다.

제거된 서비스는 동기화 프로세스를 통해 처리되어야 합니다. 단순히 업데이트된 파일을 인제스트하는 것만으로는 기존 메모리에서 오래된 엔티티를 반드시 삭제하지는 않습니다.

3.3. 에이전트 친화적인 풍부한 서비스 표현 방식 (Rich, Agent-Friendly Service Representations)

커넥터는 각 서비스를 구조화되고 사람이 읽기 쉬운 형식으로 표현할 수 있습니다:

Service: api
Image: my-org/api:v1.2.0
Ports:
...

이것은 서비스의 예시적인 표현 방식일 뿐, 완전한 Docker Compose 파일은 아닙니다. 실제 구현에서는 구성 정보를 저장하거나 AI 에이전트에게 노출하기 전에 민감한 환경 변수 값은 마스킹(redact)하거나 제외해야 합니다.

4. 단계별 가이드: Docker Compose를 Cognee에 가져오기 (Step-by-Step: Ingesting Docker Compose into Cognee)

1단계: 종속성 설치 (Install Dependencies)

의도된 설치 명령어는 다음과 같습니다:

pip install cognee cognee-community-connector-docker-compose

커넥터 패키지가 게시되었는지, 그리고 그 설치 지침이 사용하려는 구현과 일치하는지 확인하십시오.

2단계: 디렉토리 준비 (Prepare Your Directory)

Docker Compose 구성을 찾고 가져오기(ingestion)를 위한 Python 스크립트를 생성합니다:

infrastructure-project/
├── docker-compose.yml
└── ingest_topology.py

3단계: 인프라 메모리에 가져오기 및 질의 (Ingest and Query Infrastructure Memory)

다음 예시는 의도된 워크플로우를 보여줍니다. 실행하기 전에 커넥터의 실제 임포트 경로, 함수 시그니처(function signature), 그리고 Cognee API가 저장소와 일치하는지 확인하십시오.

import asyncio
import cognee

...

이 예시는 의도된 순서(sequence)를 보여줍니다:

1. 커넥터를 통해 Compose 구성을 로드합니다.
2. 소스(source)를 Cognee에 제출합니다.
3. 가져온 정보를 검색 가능한 표현 방식으로 처리합니다.
4. 결과로 나온 인프라 컨텍스트를 질의합니다.

정확한 동작은 사용되는 커넥터 구현 및 Cognee 버전에 따라 달라집니다.

5. 결과: 더 신뢰할 수 있고 토폴로지 기반의 DevOps 워크플로우 (Result: More Reliable, Topology-Grounded DevOps Workflows)

인프라 인식 검색(infrastructure-aware retrieval)을 통해 에이전트는 명령을 추천하기 전에 관련 구성을 참조할 수 있습니다.

예를 들어, Compose 파일은 db라는 이름의 서비스와 api라는 애플리케이션 서비스를 정의할 수 있습니다. 구성과 애플리케이션에서 지원하는 명령에 따라 결과 워크플로우에는 다음과 같은 내용이 포함될 수 있습니다:

docker compose exec db pg_isready -U postgres
docker compose run --rm api python manage.py migrate

이 명령어들은 예시일 뿐이며 보편적인 해결책은 아닙니다. 서비스 이름, 데이터베이스 사용자, 실행 파일, 마이그레이션 명령은 실제 프로젝트와 일치해야 합니다.

목표는 AI 에이전트가 서비스 이름, 포트, 의존성(dependencies), 실행 컨텍스트에 대해 더 정보에 입각한 결정을 내리도록 돕는 것입니다.

검색(Retrieval)은 구성 관련 추측을 줄일 수 있지만, 환각(hallucination)이 없는 출력을 보장하지는 않습니다. 에이전트는 여전히 현재 구성에 따라 명령어를 검증하고 프로덕션 환경에서 사용하기 전에 적절한 환경에서 테스트해야 합니다.

6. 오픈 소스 풀 리퀘스트 및 참고 자료

• 풀 리퀘스트: topoteretes/cognee-community#492
• 관련 이슈: topoteretes/cognee#6307
• Cognee 저장소: github.com/topoteretes/cognee
• Docker Compose 문서: docs.docker.com/compose

7. 다음 계획은?

API 사양, 데이터베이스 스키마, 다중 컨테이너 인프라가 다루어졌으므로, 다음 과제는 GraphQL 스키마와 같은 API 계약(API contracts)을 이해하는 것입니다.

제 'Mergetober' 시리즈의 4일차에서는 schema.graphql와 같은 GraphQL 스키마 정의 언어(Schema Definition Language) 파일을 AI 에이전트 메모리 워크플로우를 통해 어떻게 접근 가능하게 만들 수 있는지 탐구할 예정입니다.

여러분의 AI 코딩 에이전트는 얼마나 자주 Docker 포트 매핑, 서비스 이름 또는 네트워크 별칭(network aliases)을 잘못 이해하나요? 댓글에 경험을 공유해 주세요!