이 말은 맞습니다. 그래서 많은 기업들이 Multi-LLM 전략에 집착합니다. “에이전트에서 LLM 설정값만 바꾸면 그대로 쓸 수 있다”고 생각하죠.

하지만 현실에서 이를 실행해 본 분이라면 아실 겁니다. LLM을 바꾸는 순간, 에이전트의 행동 자체가 달라집니다. 같은 도구, 같은 프롬프트, 같은 파이프라인인데 결과가 완전히 다릅니다. Lock-in 방지는 API 엔드포인트를 바꾸는 문제가 아니라, 에이전트를 처음부터 다시 세팅하는 문제입니다.

Multi-LLM의 진짜 문제 “프롬프트는 이식되지 않는다”

많은 분들이 LLM을 API로 바라봅니다. “입력을 넣으면 출력이 나오는 함수”라고 생각하죠. 그래서 OpenAI 대신 Claude를 쓰고, Gemini로 바꾸면 되지 않느냐고 말합니다.

그런데 실제로 해보면 이런 일이 벌어집니다:

• 같은 프롬프트, 다른 결과. GPT-4o에서 잘 동작하던 프롬프트가 Claude에서는 과도하게 cautious한 응답을 내놓고, Gemini에서는 구조가 완전히 달라집니다.
• 컨텍스트 윈도우 전략이 달라집니다. 128K 토큰을 쓸 수 있는 모델과 200K를 쓸 수 있는 모델에서의 컨텍스트 설계는 완전히 다른 엔지니어링입니다.
• System prompt에 대한 반응성이 다릅니다. 어떤 모델은 system prompt를 충실히 따르고, 어떤 모델은 user turn의 마지막 지시를 더 우선합니다.

결국 모델을 바꾸면 프롬프트 엔지니어링을 처음부터 다시 해야 합니다.

LLM을 바꾸면 에이전트가 달라진다

프롬프트 이식성은 시작일 뿐입니다. 진짜 문제는 에이전트 수준에서 드러납니다. 에이전트는 단순히 프롬프트를 실행하는 것이 아니라, LLM의 판단력에 의존해 자율적으로 행동을 결정합니다. LLM이 바뀌면 그 판단이 바뀌고, 에이전트의 행동 전체가 달라집니다.

LLM을 바꾸는 것은 엔진을 바꾸는 것이 아니라 운전자를 바꾸는 것에 가깝습니다. 같은 차, 같은 길이어도 운전 방식이 완전히 달라집니다.

구체적으로 어떤 일이 벌어지는지 보겠습니다:

• Tool calling 패턴이 달라집니다. 같은 도구 목록을 줘도 모델마다 도구 선택 전략이 다릅니다. 어떤 모델은 도구를 적극적으로 호출하고, 어떤 모델은 자체 추론으로 해결하려 합니다. 도구를 호출하는 순서, 병렬 호출 여부, 파라미터 구성 방식까지 전부 달라집니다.
• 판단 기준이 달라집니다. “충분한 정보를 얻었는가”, “사용자에게 추가 질문이 필요한가”, “이 작업을 중단해야 하는가” — 에이전트의 모든 분기점에서 모델마다 다른 판단을 내립니다. GPT-4o에서 한 번에 끝나던 작업이 Claude에서는 확인 질문을 3번 거치는 식입니다.
• 오류 처리 방식이 달라집니다. 도구 호출이 실패했을 때 재시도할지, 대안 경로를 찾을지, 사용자에게 보고할지 — 이 전략이 모델마다 다릅니다. 한 모델에서 안정적이던 에이전트가 다른 모델에서는 무한 재시도 루프에 빠질 수 있습니다.
• 멀티스텝 추론 경로가 달라집니다. 같은 목표를 줘도 모델마다 문제를 분해(decompose)하는 방식과 순서가 다릅니다. 에이전트의 전체 실행 흐름 — 몇 단계를 거치는지, 어떤 순서로 처리하는지 — 이 LLM에 따라 완전히 달라집니다.

결론적으로 에이전트에서 LLM만 교체하면 “같은 에이전트”가 아닙니다. 겉은 같아 보여도 행동이 다른, 사실상 새로운 에이전트입니다. 그래서 LLM을 바꾸면 결국 에이전트의 세팅을 처음부터 다시 해야 합니다.

Lock-in의 본질은 API가 아니라 “엔지니어링 투자”

LLM lock-in을 API 호환성의 문제로 보면 간단해 보입니다. OpenAI 호환 API를 쓰면 되니까요. 하지만 진짜 lock-in은 세 가지 층위에서 발생합니다:

1. Prompt Engineering Lock-in

수개월에 걸쳐 최적화한 프롬프트 체계. Few-shot 예시, chain-of-thought 구조, 출력 포맷 제어 — 이 모든 것이 특정 모델의 행동 패턴에 맞춰져 있습니다.

2. Context Engineering Lock-in

RAG 파이프라인에서 어떤 정보를 얼마나, 어떤 순서로 컨텍스트에 넣을지. 이 설계는 모델의 컨텍스트 윈도우 크기, 위치 편향(positional bias), 정보 검색 능력에 종속됩니다.

3. Harness Engineering Lock-in

에이전트의 도구 호출 방식, 오류 처리, 반복 루프 설계, 멀티턴 대화 관리 — 이런 “모델을 감싸는 시스템”이 특정 모델의 function calling 스펙, 응답 구조, latency 특성에 맞춰져 있습니다. 여기에는 눈에 잘 보이지 않는 세팅들이 포함됩니다: 도구 선택 우선순위, 재시도 횟수와 백오프 정책, “충분하다”고 판단하는 임계값, 안전 장치의 트리거 조건 등. 이 모든 세팅이 특정 LLM의 행동 특성에 맞춰 튜닝된 것입니다. LLM을 교체하면 이 세팅을 전부 재검증하고 재조정해야 하며, 이는 사실상 에이전트를 처음부터 다시 만드는 것에 가까운 비용을 발생시킵니다.

모델을 바꾸는 것은 API 엔드포인트를 바꾸는 것이 아닙니다. 이 세 층위의 엔지니어링을 모두 다시 하는 것입니다.

관점의 전환: Multi-LLM이 아니라 Multi-Agent

여기서 발상의 전환이 필요합니다.

“어떤 LLM이든 갈아끼울 수 있게 만들자”는 접근은 각 모델의 강점을 포기하는 것과 같습니다. 최소공배수 방식으로 프롬프트를 설계하면, 어떤 모델에서도 “그럭저럭” 동작하지만 어떤 모델에서도 “최적”이 되지 않습니다.

대신 이렇게 생각해야 합니다.

각 LLM의 강점을 살리는 에이전트를 설계하고, 이 에이전트들을 오케스트레이션하는 Harness를 만들자.

• 복잡한 추론이 필요한 태스크 → Claude에 최적화된 에이전트
• 코드 생성과 실행 → Gemini에 최적화된 에이전트
• 빠른 분류와 라우팅 → 경량 모델에 최적화된 에이전트

이때 중요한 것은 개별 에이전트가 아니라 이들을 엮는 Harness Engineering입니다. 에이전트 간 통신 프로토콜, 상태 관리, 오류 전파, 관찰 가능성(observability) — 이것이 진정한 엔지니어링 과제입니다.

전체 지도: Gemini 4종 분류

1. Gemini Web (개인용)

gemini.google.com 또는 모바일 앱으로 접근하는 개인용 AI 챗봇입니다.

무료 vs Pro vs Ultra

핵심 포인트

• 무료는 Flash 모델 기반으로 간단한 질문/번역/요약 용도
• Pro는 장문 리포트, 대형 문서 분석, 고급 리서치에 적합
• Ultra는 복잡한 추론, 고난도 코딩, 전문 리서치용

개인용은 “월 ~$20 내고 강력한 Gemini를 쓸 것인가, 무료로 가볍게 쓸 것인가” 선택의 문제입니다.

2. Gemini for Google Workspace

Gmail, Docs, Sheets, Slides, Meet, Chat 등 Workspace 앱 안에 붙는 AI 기능입니다.

어디에서 뭘 해주나?

요금 구조

Google Workspace 요금제 + Gemini 애드온 구조입니다.

• Workspace Business Starter/Standard/Plus 등에 “Gemini 포함 플랜” 또는 “AI 애드온”으로 추가
• 결제 단위: 사용자 수 x 월 요금, 중도 추가/삭제 시 일할 계산

개인용 Gemini Web과의 차이

같은 Gemini라도 Workspace 계정이면:

• 조직 데이터(공유 드라이브, 조직 캘린더 등)에 접근 가능
• 관리 콘솔에서 사용 제한, 로그/감사, DLP, Vault 등과 연계
• 기업 약관 + 데이터 미학습 보장 적용

Workspace용 Gemini는 “직원당 월 X달러를 더 내고, 구글 업무 앱마다 AI를 붙인다”라고 이해하면 됩니다.

3. Gemini Enterprise (GCP 기반)

Workspace에 붙는 도구가 아니라, GCP에서 제공되는 엔터프라이즈 AI 포털/에이전트 플랫폼입니다.

Workspace용 Gemini와 뭐가 다른가?

요금

• 사용자당 월 ~$30부터 (Standard/Plus 등 SKU별 상이)
• 라이선스당 인덱스 스토리지(예: 75GiB) 포함
• 볼륨 디스카운트 가능

주요 기능

• 직원이 접속하는 AI 허브/포털
• 조직 데이터 인덱싱 및 검색 (Drive, Calendar, Gmail, Chat 연동)
• 복잡한 업무용 AI 에이전트 호스팅
• Vertex AI MCP, Search, API 연동으로 워크플로 에이전트 정의
• 고급 보안: VPC-SC, CMEK, 액세스 투명성, 데이터 상주성

Gemini Enterprise는 “직원당 월 $30 이상 내고, 회사 전용 AI 포털과 에이전트 플랫폼을 산다”는 개념입니다.

4. Vertex AI + Gemini API (커스텀 에이전트)

Vertex AI에서 Gemini 모델을 API로 호출해 커스텀 에이전트/서비스를 직접 만드는 개발자용 시나리오입니다.

Enterprise와 뭐가 다른가?

요금 (토큰 기반, 참고용)

가격은 수시로 변동됩니다. 최신 가격은 Vertex AI Pricing에서 확인하세요.

주요 특징

• 구독이 아닌 사용량 과금: 엔드유저 수가 아니라 API 호출량이 비용의 관건
• 완전 커스텀: 프롬프트, 툴, 함수 호출, RAG, 외부 API/DB 연동을 마음대로 설계
• B2C/B2B 서비스에 적합: 고객 대상 앱, 사내 자동화 시스템 등에 Gemini를 임베드
• 멀티모달: 텍스트, 이미지, 오디오, 비디오 입력 지원
• 롱 컨텍스트: 최대 100만~200만 토큰
• 보안: VPC-SC, CMEK, HIPAA, FedRAMP High 등 지원

Enterprise는 포털+플랫폼 라이선스, Vertex AI는 빌딩 블록(API) 과금이라고 보시면 됩니다.

고객이 자주 혼동하는 질문 (FAQ)

“Google AI Pro를 샀는데, 우리 회사 Gmail에도 자동으로 붙나요?”

아닙니다. Google AI Pro는 개인 계정용입니다. 회사 Workspace 메일에 AI를 붙이려면 Gemini for Workspace 라이선스를 별도로 구매해야 합니다.

“Gemini Enterprise를 사면, Vertex AI API는 무료인가요?”

별개입니다. Enterprise는 직원용 포털/에이전트 라이선스이고, Vertex AI는 API 사용량 기반 과금입니다. 둘 다 비용이 발생합니다.

“직원 50명 정도인데, Gmail/Docs에서 AI만 있으면 됩니다. 뭘 사야 하나요?”

Google Workspace 플랜 + Gemini 포함 옵션이 기본 선택입니다. 별도 AI 포털이 필요하면 그때 Gemini Enterprise를 검토하시면 됩니다.

“커스텀 AI 챗봇을 우리 서비스에 넣고 싶은데요?”

Vertex AI + Gemini API가 적합합니다. 사용량 기반 과금이라 서비스 규모에 맞게 비용이 조절됩니다.

“개인 Gemini Web과 Workspace용 Gemini, 기능이 같은가요?”

UI는 비슷하지만 보안/감사/데이터 정책이 다릅니다. Workspace 계정이면 조직 데이터 접근, 관리자 정책, 데이터 미학습 보장 등 기업용 약관이 적용됩니다.

“Gemini for Workspace를 구독하면 개인용 Google AI Pro/Ultra를 회사 메일로 쓰는 것과 같나요?”

완전히 같지는 않습니다. Gemini for Workspace를 구독하면 Workspace 앱 내 AI 기능과 Gemini 앱(gemini.google.com) 접근 권한을 얻지만, 개인용 Pro/Ultra와 차이가 있습니다:

“Gemini 웹 채팅을 회사 계정으로 쓸 수 있다”는 맞지만, 모델 등급/기능 범위가 개인 Pro/Ultra와 동일하다고 보장되지는 않습니다. 특히 Ultra급 기능(Deep Think, Veo 등)은 Workspace 플랜에 포함되지 않을 수 있습니다.

“회사 메일(Workspace 계정)로 Google AI Pro/Ultra를 쓰려면 어떻게 하나요?”

개인이 Google One에서 결제하는 것과는 다릅니다. Workspace 관리자가 Admin Console에서 라이선스를 할당하는 방식입니다:

1. Admin Console > 구독 > Gemini 관련 라이선스 추가 구매
2. 사용자별로 라이선스 할당

주의할 점:

• 개인용 “Google AI Pro”와 Workspace용 “Google AI Pro”는 SKU가 다릅니다
• 관리자가 할당해도 기업 데이터 정책(데이터 미학습, 감사 로그 등)은 Workspace 기준으로 적용
• Ultra급이 Workspace SKU로 제공되는지는 아직 명확하지 않음 (Google이 수시로 업데이트 중)
• 정확한 SKU 이름과 포함 기능은 Google이 자주 변경하므로, 도입 시점에 Google 또는 메가존소프트를 통해 최신 SKU를 확인하는 것을 권장합니다.

선택 가이드: 어떤 상황에 어떤 제품?

핵심은 이것입니다:

• “조직에서 직원들이 쓸 포털형 AI”를 원하면 → Enterprise
• “고객/직원 대상 커스텀 앱/에이전트를 직접 개발”하고 싶으면 → Vertex AI API
• “Workspace 앱에서 바로 AI 보조”가 필요하면 → Gemini for Workspace

도입에 대한 자세한 문의는 메가존소프트를 통해 연락해 주세요.

이 글에서는 하네스 엔지니어링의 개념부터 필요한 도구, 실전 적용법, 그리고 현재 트렌드까지 슬라이드 형식으로 정리합니다.

Slide 1. 하네스 엔지니어링이란?

한 줄 정의

AI 에이전트가 무엇을 보고, 무엇을 할 수 있고, 언제 멈추고, 실패하면 어떻게 되는지를 설계하는 엔지니어링 규율

비유: 말과 마구(馬具)

LLM은 강력하지만 방향 감각이 없는 말입니다. 하네스는 그 힘을 통제 가능한 작업으로 전환하는 고삐, 안장, 재갈 역할을 합니다.

하네스 엔지니어링은 프롬프트 엔지니어링의 상위 개념입니다. 프롬프트가 “한 번의 대화를 잘하는 법”이라면, 하네스는 “100번의 세션을 걸쳐 일관되게 잘하는 법”입니다.

Slide 2. 왜 하네스가 필요한가?

LLM의 근본적 한계

LLM은 기본적으로 무상태(stateless)입니다. 매 세션은 이전 작업에 대한 기억 없이 시작됩니다.

모델은 상품화되었다

Claude, GPT, Gemini, 오픈소스 모델들의 성능 차이는 좁아지고 있습니다. 동일한 모델을 사용해도 하네스 품질에 따라 작업 완료율이 40%p 차이가 납니다.

모델은 교체 가능한 부품이고, 하네스가 곧 제품이다.

Slide 3. 하네스의 6대 핵심 구성요소

1. 컨텍스트 엔지니어링

에이전트가 무엇을 볼 수 있는지 결정합니다.

• 코드베이스 내 지속적으로 개선되는 지식 기반 (AGENTS.md, CLAUDE.md 등)
• 관찰 가능성 데이터, 브라우저 네비게이션 같은 동적 컨텍스트
• “Lost in the Middle” 문제 대응 — 가장 중요한 정보를 프롬프트의 시작과 끝에 배치
• 3종 메모리 운영: 작업 컨텍스트(임시), 세션 상태(중기), 장기 메모리(영구)

2. 검증 루프

에이전트가 제대로 했는지 확인합니다.

• 코딩 에이전트: 테스트 스위트 통과 후에만 기능 완료 표시
• 기능 목록을 JSON으로 관리 → 각 기능의 pass/fail 상태를 기계적으로 추적
• 결정론적 린터 + 구조 테스트로 아키텍처 제약 위반 감지

3. 상태 관리

에이전트가 어디까지 했는지 기억합니다.

• claude-progress.txt 같은 진행 로그
• Git 커밋으로 각 단계의 진행 상황 문서화
• JSON 형식 선호 (모델이 마크다운보다 JSON을 덜 임의로 수정함)

4. 도구 오케스트레이션

에이전트가 무엇을 할 수 있는지 제어합니다.

• 파일 시스템 접근, 코드 실행, API 호출, 웹 검색 등
• 사전 승인된 도구만 접근 가능하도록 제한
• MCP(Model Context Protocol) 서버를 통한 도구 연결

5. 휴먼-인-더-루프

에이전트가 언제 사람에게 물어봐야 하는지 결정합니다.

• 파괴적 작업(삭제, 배포 등)에 대한 인간 승인 요구
• 완전 자율은 드물게 적절 — 대부분의 시나리오에서 인간 개입 지점 설계 필수
• 민감한 결정에 대한 에스컬레이션 경로

6. 생명주기 관리

에이전트의 시작과 끝, 그리고 세션 간 전환을 관리합니다.

• 초기화 에이전트 → 코딩 에이전트 분리 패턴
• 각 세션 시작 시 표준 절차: pwd 확인 → git 로그 읽기 → 기능 목록 확인 → 다음 작업 선택
• 실패 시 안전한 롤백 경로

Slide 4. 하네스 엔지니어링에 필요한 도구들

코드 품질 & 제약 도구

컨텍스트 & 메모리 도구

도구 연결 & 오케스트레이션

검증 & 안전 도구

Slide 5. 실전: 하네스 엔지니어링은 어떻게 하는가?

아키텍처 패턴 선택

패턴 A: 단일 에이전트 + 감독자 루프

• 하나의 모델이 도구·메모리·검증과 함께 루프
• 적합: 고객 지원, 단순 자동화

패턴 B: 초기화-실행자 분할 (Anthropic 추천)

• 초기화 에이전트가 환경 세팅 후, 코딩 에이전트가 증분 진행
• 적합: 장기 실행 코딩 작업

패턴 C: 멀티 에이전트 조율

• 연구자·작가·검토자 등 전문가 에이전트 간 작업 위임
• 적합: 복잡한 프로젝트, 다단계 파이프라인

실전 체크리스트

Step 1: 기능 목록 정의

[
  {
    "category": "functional",
    "description": "사용자가 새 대화를 생성할 수 있다",
    "passes": false
  },
  {
    "category": "functional",
    "description": "메시지 전송 시 실시간 응답이 표시된다",
    "passes": false
  }
]

모든 기능을 false로 시작하여 완료 기준을 명확히 합니다.

Step 2: 초기화 스크립트 작성

#!/bin/bash
# init.sh — 에이전트가 매 세션 시작 시 실행
npm install
npm run dev &
echo "Development server started"

Step 3: 에이전트 지시사항 문서 작성

# AGENTS.md

## 작업 규칙
- 한 번에 하나의 기능만 작업할 것
- 기능 완료 전 반드시 E2E 테스트를 실행할 것
- 테스트를 삭제하거나 수정하는 것은 금지
- 작업 완료 후 git commit으로 진행 상황을 기록할 것

## 세션 시작 절차
1. pwd로 현재 디렉토리 확인
2. git log로 최근 진행 상황 확인
3. features.json에서 다음 미완료 기능 선택
4. init.sh로 개발 서버 시작

Step 4: 검증 자동화 구축

# .github/workflows/agent-verify.yml
on: [push]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint        # 커스텀 린터
      - run: npm run test:arch   # 구조 테스트
      - run: npm run test:e2e    # E2E 테스트

Step 5: 엔트로피 관리 (가비지 컬렉션)

주기적으로 별도 에이전트가 코드베이스를 스캔합니다:

• 문서화 불일치 감지 및 수정
• 아키텍처 제약 위반 탐지
• 코드 부패(code rot) 식별

OpenAI 팀의 핵심 통찰: 에이전트가 어려움을 겪을 때, 그것을 신호로 해석하라. 부족한 도구, 가드레일, 문서를 식별하고 저장소에 피드백하는 것이 하네스 엔지니어링의 핵심 루프다.

Slide 6. 하네스 엔지니어링을 위한 SDK & 개발 킷

하네스를 직접 처음부터 만들 필요는 없습니다. 주요 벤더와 오픈소스 커뮤니티가 에이전트 하네스 구축을 위한 SDK와 프레임워크를 제공합니다.

코딩 에이전트 하네스 (완성형)

이미 하네스가 내장된 에이전트 환경으로, 즉시 사용 가능합니다.

Claude Code 하네스 아키텍처 상세

Claude Code는 가장 정교한 하네스 시스템 중 하나입니다:

에이전트 개발 SDK (프레임워크)

에이전트를 직접 구축할 때 하네스 기능을 제공하는 SDK입니다.

Claude Agent SDK (Anthropic)

• 접근 방식: Tool-use-first — 에이전트 = Claude 모델 + 도구
• 하네스 기능: 훅 시스템, 권한 모델, 다른 에이전트를 도구로 호출
• 아키텍처: 프롬프트 수신 → 필요시 도구 호출 → 구조화된 응답 반환
• 강점: 의도적으로 단순한 설계, Anthropic 플랫폼 네이티브 통합

from claude_agent_sdk import Agent, Tool

agent = Agent(
    model="claude-sonnet-4-6",
    tools=[filesystem, code_runner, browser],
    hooks={"pre_tool_use": lint_check, "post_tool_use": test_runner},
    permissions={"file_write": "ask", "bash": "restricted"}
)

OpenAI Agents SDK

• 접근 방식: 최소주의 — 핵심 추상화는 “Handoff”
• 하네스 기능: 입력/출력 가드레일, 낙관적 실행 + 롤백, 추적/평가
• 아키텍처: 에이전트 간 명시적 제어 전환 (Handoff 메커니즘)
• 강점: 가장 낮은 학습 곡선, 빠른 프로토타이핑

from agents import Agent, Runner, InputGuardrail

agent = Agent(
    name="code_agent",
    instructions="...",
    tools=[file_tool, shell_tool],
    input_guardrails=[safety_check],
    output_guardrails=[quality_check]
)
result = Runner.run(agent, "Fix the login bug")

Google ADK (Agent Development Kit)

• 접근 방식: 명시적 워크플로우 타입 (Sequential, Parallel, Loop)
• 하네스 기능: 에이전트를 도구로 사용하는 계층 구조, Vertex AI 통합, Developer UI
• 아키텍처: 결정론적 + 동적 흐름 혼합, OpenAPI 자동 변환
• 강점: GCP 생태계 네이티브, 풍부한 내장 도구, 평가 도구 내장

from google.adk import Agent, SequentialAgent, ParallelAgent

researcher = Agent(name="researcher", tools=[search, scrape])
writer = Agent(name="writer", tools=[file_write])
pipeline = SequentialAgent(
    agents=[researcher, writer],
    guardrails=safety_filter
)

AWS Strands Agents SDK

• 접근 방식: 모델 주도(model-driven) — Model + Tools + Prompt
• 하네스 기능: 내장 도구 20+, MCP 서버 연결, @tool 데코레이터
• 아키텍처: 모델이 계획·도구 선택·결과 반영을 모두 주도
• 강점: AWS Bedrock 네이티브, 복잡한 오케스트레이션 불필요

from strands import Agent
from strands.tools import tool

@tool
def deploy(service: str) -> str:
    """Deploy a service to production"""
    return run_deploy(service)

agent = Agent(tools=[deploy])
result = agent("Deploy the user service")

오케스트레이션 프레임워크

에이전트 간 조율과 복잡한 워크플로우를 위한 프레임워크입니다.

Microsoft AutoGen

• 접근 방식: 대화 기반 멀티 에이전트 — 에이전트들이 그룹 채팅처럼 대화
• 하네스 기능: 코드 실행 샌드박스, 비동기 메시징, 그룹 채팅 관리자
• 아키텍처: AssistantAgent, UserProxyAgent 등 역할별 에이전트가 대화로 협업
• 강점: Microsoft 생태계 통합, 인간 참여가 자연스러운 대화 흐름에 녹아듦

from autogen import AssistantAgent, UserProxyAgent, GroupChat

coder = AssistantAgent("coder", llm_config=llm_config)
reviewer = AssistantAgent("reviewer", llm_config=llm_config)
executor = UserProxyAgent("executor", code_execution_config={"work_dir": "workspace"})

group_chat = GroupChat(agents=[coder, reviewer, executor], messages=[])

도구 연결 표준: MCP (Model Context Protocol)

모든 SDK를 관통하는 핵심 표준이 MCP입니다.

• 어떤 SDK를 사용하든 동일한 도구 인터페이스 제공
• Claude Code, Cursor, Codex 모두 MCP 지원
• 한 번 만든 MCP 서버를 여러 에이전트에서 재사용

SDK 선택 가이드

비교 요약

Slide 7. 실제 사례: OpenAI Codex

OpenAI의 Codex 팀은 하네스 엔지니어링의 가장 대표적인 사례입니다.

프로젝트 개요

• 5개월 동안 프로덕션 애플리케이션 개발
• 100만 줄 이상의 코드, 전부 AI가 생성
• 인간 엔지니어는 코드를 한 줄도 직접 작성하지 않음
• 엔지니어의 역할: AI가 코드를 안정적으로 작성할 수 있는 시스템을 설계

3가지 핵심 하네스 전략

1. 컨텍스트 엔지니어링

• 코드베이스 내 지속적으로 개선되는 지식 기반
• 관찰 가능성 데이터와 동적 컨텍스트 제공

2. 아키텍처 제약

• 결정론적 커스텀 린터와 구조 테스트
• LLM 기반 방식과 결정론적 방식의 혼합
• 에이전트의 “해결 공간”을 좁혀서 신뢰성 확보

3. 가비지 컬렉션 에이전트

• 주기적으로 코드베이스 엔트로피를 감지·수정
• 문서 불일치, 아키텍처 위반, 코드 부패 자동 탐지

핵심 교훈

“제약이 클수록 신뢰성이 높다” — 무제한 유연성보다 제약된 해결 공간이 더 나은 결과를 만든다

Slide 8. 실제 사례: Anthropic의 장기 실행 에이전트 하네스

Anthropic은 장기 실행 코딩 에이전트를 위한 초기화-실행자 분할 패턴을 권장합니다.

2단계 아키텍처

주요 실패 패턴과 해결책

베스트 프랙티스

• JSON > Markdown: 모델이 JSON 파일은 임의로 수정하는 경향이 적음
• 강력한 금지 지시: “테스트를 삭제하거나 수정하는 것은 허용되지 않음”
• E2E 검증 우선: 단위 테스트보다 실제 사용자 관점의 E2E 테스트

Slide 9. 현재 트렌드와 미래 방향

트렌드 1: 하네스 = 새로운 경쟁 우위

모델 성능이 수렴하면서, 하네스 품질이 곧 제품 품질이 되었습니다. 동일 모델에서 하네스 유무에 따라 2~5배의 신뢰성 차이가 발생합니다.

트렌드 2: 하네스 엔지니어, 새로운 직군의 탄생

에이전트 기반 제품을 만드는 회사에서 “Harness Engineer”가 독립적인 역할로 등장하고 있습니다. 기존 소프트웨어 엔지니어링 + AI 시스템 설계 + 안전성 엔지니어링의 교차점입니다.

트렌드 3: Meta-Harness — 하네스를 최적화하는 AI

최신 연구에서는 하네스 코드 자체를 AI가 최적화하는 메타 하네스 개념이 등장했습니다. 소스 코드, 점수, 실행 트레이스를 분석하여 더 나은 하네스를 자동으로 제안합니다.

트렌드 4: 기술 스택의 수렴

개발자의 프레임워크/언어 취향보다 AI 친화적 구조가 우선시되는 경향입니다. 하네스가 유지보수하기 좋은 코드 구조가 사실상의 표준으로 자리잡고 있습니다.

트렌드 5: 모델 드리프트 감지

하네스가 모델이 100번째 스텝 이후 지시를 따르지 않거나 추론 오류를 범하는 시점을 정확히 감지하는 도구로 진화하고 있습니다.

트렌드 6: 신규 vs 기존 코드베이스 분화

• 신규 프로젝트: 처음부터 하네스를 고려하여 설계
• 기존 프로젝트: 하네스 레트로핏이 항상 가치 있지는 않음 — 엔트로피가 높은 레거시 코드는 비용 대비 효과가 낮을 수 있음

Slide 10. 핵심 요약

“더 나은 모델”이 아니라 “더 나은 제어 환경”이 장기적 코드 품질과 에이전트 신뢰성을 결정한다

참고 자료

• Harness Engineering — Martin Fowler
• Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI
• Effective Harnesses for Long-Running Agents — Anthropic
• What Is an Agent Harness? — Firecrawl
• What is AI Harness Engineering? — Medium
• The Importance of Agent Harness in 2026 — Philipp Schmid
• 2025 Was Agents. 2026 Is Agent Harnesses. — Aakash Gupta
• The State of AI Agent Frameworks — Roberto Infante
• Everything Claude Code: The Agent Harness — Big Hat Group
• Claude Agent SDK Overview — Anthropic

“에이전트 A가 과거에 나눈 대화 내역과 학습한 맥락을 에이전트 B에게 넘겨줄 수 있을까?”

이 글에서는 Google의 A2A(Agent-to-Agent) 프로토콜을 중심으로 에이전트 간 대화 내역과 메모리를 공유하는 방법을 정리합니다.

1. A2A 프로토콜이란?

A2A(Agent-to-Agent)는 Google이 2024년에 발표하고 2026년 3월에 v1.0.0을 릴리스한 오픈 프로토콜입니다. 서로 다른 프레임워크, 다른 벤더에서 만든 AI 에이전트들이 표준화된 방식으로 통신하고 협업할 수 있게 해줍니다.

기술 스택

핵심 데이터 모델

A2A의 통신은 다음 구조로 이루어집니다.

Task (작업 단위)
├── Message (대화 턴)
│   ├── role: "user" | "agent"
│   ├── contextId
│   ├── messageId
│   └── parts[]
│       ├── TextPart   (텍스트)
│       ├── FilePart   (파일 참조)
│       └── DataPart   (구조화된 JSON 데이터)
└── Artifact (에이전트가 생성한 산출물)
    └── parts[]

• Task: 에이전트 간 협업의 기본 단위. 하나의 작업 요청과 그에 대한 응답 전체를 포괄합니다.
• Message: Task 내의 개별 대화 턴. contextId로 대화 맥락을 추적합니다.
• Part: 메시지를 구성하는 최소 콘텐츠 단위. 텍스트, 파일, 구조화된 데이터를 담을 수 있습니다.
• Artifact: 에이전트가 작업 결과로 생성한 산출물(문서, 이미지, 데이터 등).

2. A2A의 핵심 원칙: Opaque Execution

A2A 프로토콜의 가장 중요한 설계 원칙은 Opaque Execution(불투명 실행)입니다.

에이전트는 자신의 내부 상태, 메모리, 도구, 추론 과정을 상대 에이전트에게 공개하지 않습니다.

이것은 의도적인 설계입니다. 각 에이전트의 독립성, 보안, 지적 재산을 보호하면서도 협업을 가능하게 하기 위함입니다. 에이전트는 서로를 블랙박스로 취급하되, 선언된 능력(Agent Card)과 교환된 메시지(Message/Artifact)를 기반으로 협력합니다.

이것이 의미하는 것

에이전트 A                    에이전트 B
┌─────────────┐              ┌─────────────┐
│ 내부 메모리  │   ← 비공개    │ 내부 메모리  │
│ 추론 과정    │              │ 추론 과정    │
│ 사용 도구    │              │ 사용 도구    │
├─────────────┤              ├─────────────┤
│ Agent Card  │ ─── 공개 ───→ │             │
│ Message     │ ←── 교환 ───→ │ Message     │
│ Artifact    │ ←── 교환 ───→ │ Artifact    │
└─────────────┘              └─────────────┘

즉, A2A 프로토콜 자체만으로는 에이전트의 과거 대화 내역이나 내부 메모리를 직접 공유하는 메커니즘이 없습니다. 하지만 이를 해결하기 위한 여러 접근 방식이 존재합니다.

3. A2A 내에서 컨텍스트를 전달하는 방법

A2A가 내부 메모리를 직접 공유하지는 않지만, 프로토콜이 제공하는 메커니즘을 활용하면 필요한 맥락을 명시적으로 전달할 수 있습니다.

3-1. DataPart를 활용한 구조화된 컨텍스트 전달

DataPart에 과거 대화 요약, 사용자 선호도, 작업 상태 등을 JSON 구조로 담아 전달할 수 있습니다.

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": {
    "id": "task-001",
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "이전 대화를 바탕으로 보고서를 작성해주세요."
        },
        {
          "kind": "data",
          "data": {
            "conversation_summary": "사용자가 Q1 매출 분석을 요청했고, 특히 아시아 시장에 관심이 많음",
            "key_decisions": ["분석 기간: 2025 Q1", "비교 대상: 전년 동기"],
            "user_preferences": {
              "format": "executive_summary",
              "language": "ko"
            }
          }
        }
      ]
    }
  }
}

3-2. Artifact를 통한 작업 결과 전달

에이전트 A의 작업 결과(Artifact)를 에이전트 B의 입력으로 사용하는 파이프라인 패턴입니다.

에이전트 A (데이터 분석) → Artifact(분석 결과) → 에이전트 B (보고서 작성)

Artifact에는 텍스트, 파일, 구조화된 데이터를 모두 담을 수 있으므로, 이전 에이전트의 작업 결과를 풍부하게 전달할 수 있습니다.

3-3. contextId를 통한 대화 맥락 유지

A2A의 Message에는 contextId 필드가 있어, 같은 맥락에 속하는 메시지들을 그룹핑할 수 있습니다. 이를 통해 에이전트가 하나의 대화 흐름 안에서 맥락을 유지하며 통신할 수 있습니다.

한계

이 방법들은 모두 명시적 전달입니다. 오케스트레이터(혹은 클라이언트)가 “어떤 맥락을 전달할지”를 결정하고 직접 구성해야 합니다. 에이전트가 자동으로 과거 기억을 검색하거나 공유하는 것은 아닙니다.

4. A2A를 넘어서: 에이전트 간 메모리 공유 솔루션

A2A만으로는 부족한 부분을 보완하기 위해 여러 프로토콜과 프레임워크가 등장했습니다.

4-1. MACP (Multi-Agent Cognition Protocol)

MACP는 A2A와 MCP 사이의 간극을 메우는 공유 조정 프로토콜입니다.

핵심 아이디어: 로컬 SQLite 파일을 공유 버스로 사용하여, 에이전트 간에 메모리와 컨텍스트를 교환합니다.

에이전트 A ──┐
             ├──→ [ SQLite (공유 메모리) ] ←──┤
에이전트 B ──┘                                 ├── 에이전트 C
                                               │

제공 기능:

특징:

• 제로 런타임 의존성 (TypeScript, npm i macp)
• 중앙 네트워크 서비스 불필요 (로컬 SQLite 파일로 동작)
• Claude Code, Cursor, Gemini CLI 등 주요 AI 도구 지원
• 에이전트별 독립적 워킹 컨텍스트를 유지하면서 공유 메모리 접근

활용 시나리오: 하나의 프로젝트에서 여러 에이전트가 동시에 작업할 때, 파일 소유권 시그널링, 작업 대기열 관리, 발견한 사실의 공유 등에 활용됩니다.

4-2. SAMEP (Secure Agent Memory Exchange Protocol)

SAMEP은 2025년 arXiv에 발표된 논문에서 제안된 프로토콜로, 보안이 중요한 환경에서의 에이전트 메모리 공유를 다룹니다.

해결하는 세 가지 문제:

1. 세션 간 컨텍스트 영속성: 에이전트가 재시작되어도 과거 대화 맥락을 유지
2. 안전한 멀티 에이전트 협업: 세밀한 접근 제어로 필요한 정보만 공유
3. 효율적인 시맨틱 검색: 과거 맥락 중 관련된 것만 빠르게 찾기

기술 구성:

• 분산 메모리 저장소 + 벡터 기반 시맨틱 검색
• AES-256-GCM 암호화 기반 접근 제어
• 기존 프로토콜(MCP, A2A)과의 호환성
• HIPAA 등 규제 컴플라이언스 지원

실험 결과:

• 중복 연산 73% 감소
• 컨텍스트 관련성 점수 89% 향상

4-3. A2A Memory System (Context Engineering 접근)

A2A Memory System은 Google의 “Context Engineering: Sessions & Memory” 원칙을 구현한 오픈소스 프로젝트입니다.

다섯 가지 메모리 유형:

이렇게 메모리를 유형별로 분류하면, 에이전트가 상황에 맞는 메모리를 선택적으로 검색하고 공유할 수 있어 128K 토큰 컨텍스트 윈도우를 효율적으로 활용할 수 있습니다.

5. 실전 아키텍처 패턴

패턴 1: 오케스트레이터 + 공유 메모리

가장 실용적인 패턴으로, 오케스트레이터가 컨텍스트 라우팅을 담당합니다.

                    ┌──────────────────────┐
                    │    Orchestrator      │
                    │  (A2A Client)        │
                    └──┬───────┬───────┬───┘
                       │       │       │
                  A2A  │  A2A  │  A2A  │
                       │       │       │
                    ┌──┴──┐ ┌──┴──┐ ┌──┴──┐
                    │ 분석 │ │ 작성 │ │ 검증 │
                    │Agent│ │Agent│ │Agent│
                    └──┬──┘ └──┬──┘ └──┬──┘
                       │       │       │
                  MCP  │  MCP  │  MCP  │
                       │       │       │
                    ┌──┴───────┴───────┴──┐
                    │   Shared Memory     │
                    │ (MACP / Vector DB)  │
                    └─────────────────────┘

동작 방식:

1. 오케스트레이터가 사용자 요청을 받아 Task를 생성
2. 분석 에이전트에게 A2A로 분석 요청 → 결과를 공유 메모리에 저장
3. 작성 에이전트에게 A2A로 작성 요청 시, DataPart에 이전 분석 결과의 참조를 포함
4. 작성 에이전트는 공유 메모리(MCP 서버)에서 상세 컨텍스트를 가져와 작업

패턴 2: 파이프라인 + Artifact 체인

에이전트의 Artifact를 다음 에이전트의 입력으로 직접 연결하는 패턴입니다.

사용자 요청
    │
    ▼
[리서치 Agent] ──Artifact(조사 결과)──→ [분석 Agent] ──Artifact(분석 보고서)──→ [요약 Agent]
                                                                                    │
                                                                              최종 결과물

이 패턴에서는 각 에이전트가 이전 에이전트의 산출물을 “대화 내역”처럼 받아서 작업합니다. Artifact가 곧 공유되는 컨텍스트 역할을 합니다.

패턴 3: 메모리 서버 + MCP

MCP(Model Context Protocol) 서버로 메모리 저장소를 구성하고, A2A 에이전트들이 MCP를 통해 접근하는 패턴입니다.

에이전트 A ──(MCP)──→ Memory MCP Server ←──(MCP)── 에이전트 B
                          │
                    ┌─────┴─────┐
                    │ Vector DB │
                    │ (메모리)   │
                    └───────────┘

장점:

• A2A는 에이전트 간 통신에만 집중
• 메모리 관리는 MCP 도구로 분리
• 각 에이전트가 필요한 메모리만 시맨틱 검색으로 가져옴

6. 프로토콜 간 역할 비교

이 프로토콜들은 상호 배타적이지 않습니다. 오히려 함께 사용할 때 완전한 멀티 에이전트 메모리 공유 시스템을 구축할 수 있습니다.

A2A  → 에이전트가 서로 대화하는 방법
MCP  → 에이전트가 메모리 저장소에 접근하는 방법
MACP → 에이전트가 실시간으로 컨텍스트를 조정하는 방법
SAMEP → 메모리를 안전하게 암호화하고 접근 제어하는 방법

7. 현실적인 한계와 고려사항

표준화의 현재 상태

A2A v1.0.0이 2026년 3월에 출시되었지만, 에이전트 간 메모리 공유에 대한 공식 표준은 아직 없습니다. 현재의 인터롭 표준들(A2A, MCP, AG-UI)은 “통신”을 해결하지만 “인지”는 해결하지 않는다는 지적이 있습니다.

“Standards without shared memory create connected strangers.” — MemU Blog

토큰 효율성

과거 대화를 통째로 전달하면 토큰 사용량이 급증합니다. 실제로는 다음과 같은 최적화가 필요합니다.

• 요약(Summarization): 긴 대화를 핵심 포인트로 압축
• 시맨틱 검색: 현재 작업에 관련된 과거 맥락만 선택적으로 가져오기
• 계층적 메모리: 중요도에 따라 메모리를 계층화하여 관리

보안 고려사항

에이전트 간 메모리를 공유할 때 반드시 고려해야 할 점들입니다.

• 어떤 에이전트가 어떤 메모리에 접근 가능한지 접근 제어
• 민감 정보의 암호화 (SAMEP의 AES-256-GCM 등)
• 메모리 교환의 감사 로그 (특히 규제 환경)
• 한 에이전트의 hallucination이 다른 에이전트로 전파되는 오염 방지

8. 정리

A2A 프로토콜은 에이전트 간 통신의 표준을 제공하지만, 과거 대화 내역과 메모리의 직접적인 공유 메커니즘은 내장되어 있지 않습니다. 이는 보안과 독립성을 위한 의도적인 설계입니다.

하지만 다음과 같은 방법으로 에이전트 간 대화 내역과 메모리를 공유할 수 있습니다.

멀티 에이전트 시스템에서 메모리 공유는 아직 발전 중인 영역입니다. 하지만 A2A + MCP를 기반으로 MACP나 SAMEP 같은 보완 프로토콜을 결합하면, 에이전트들이 과거 대화와 학습한 맥락을 효과적으로 공유하는 시스템을 지금도 구축할 수 있습니다.

참고 자료

• A2A Protocol v1.0.0 공식 문서
• A2A GitHub 저장소
• MACP - Multi-Agent Cognition Protocol
• SAMEP: Secure Agent Memory Exchange Protocol (arXiv)
• A2A Memory System
• MCP vs A2A: The Complete Guide (2026)

이 글에서는 ADK에서 제공하는 컨텍스트 공유 메커니즘과 에스컬레이션 패턴을 네 가지 축으로 정리합니다.

1. Agent ↔ Agent 간 컨텍스트 공유
2. Agent ↔ SubAgent 간 컨텍스트 공유
3. Agent ↔ Tool 간 컨텍스트 공유
4. Escalation — 다른 에이전트나 상위 에이전트로 제어를 되돌리는 방법

1. ADK의 컨텍스트 관리 구조

ADK는 대화형 컨텍스트를 세 가지 계층으로 관리합니다.

Session (대화 스레드)
├── Events[] (메시지/액션 이력)
├── State (session.state) ← 현재 대화의 임시 데이터
│   ├── 기본 키 (세션 스코프)
│   ├── user: 접두사 (사용자 스코프)
│   ├── app: 접두사 (앱 전역 스코프)
│   └── temp: 접두사 (단일 호출 스코프)
└── Memory (교차 세션 장기 기억)

State의 네 가지 스코프 접두사

ADK State의 핵심은 접두사(prefix)로 스코프를 구분한다는 점입니다.

# 세션 스코프 — 현재 세션에서만 유효
session.state['current_step'] = 'analysis'

# 사용자 스코프 — 같은 사용자의 모든 세션에서 공유
session.state['user:preferred_language'] = 'ko'

# 앱 스코프 — 모든 사용자와 세션에서 공유
session.state['app:global_config'] = 'v2'

# 임시 스코프 — 현재 호출(invocation)에서만 유효, 호출 완료 후 폐기
session.state['temp:intermediate_result'] = {'score': 0.95}

특히 temp: 접두사는 부모 에이전트가 서브에이전트를 호출할 때 같은 InvocationContext를 전달하기 때문에, 동일 호출 체인 내에서 에이전트 간 데이터를 임시로 주고받는 데 유용합니다.

2. Agent ↔ Agent 간 컨텍스트 공유

같은 시스템 내 에이전트들이 서로 데이터를 교환하는 방법은 크게 세 가지입니다.

2-1. Shared Session State (공유 세션 상태)

가장 기본적이고 널리 사용되는 방식입니다. 같은 Session을 공유하는 에이전트들은 session.state를 통해 데이터를 읽고 쓸 수 있습니다.

from google.adk.agents import LlmAgent, SequentialAgent

agent_a = LlmAgent(
    name="AgentA",
    model="gemini-2.0-flash",
    instruction="프랑스의 수도를 찾아주세요.",
    output_key="capital_city"  # 결과를 state['capital_city']에 저장
)

agent_b = LlmAgent(
    name="AgentB",
    model="gemini-2.0-flash",
    instruction="{capital_city}에 대해 자세히 알려주세요."
    # {capital_city} → state['capital_city'] 값이 자동 주입됨
)

pipeline = SequentialAgent(
    name="CityInfoPipeline",
    sub_agents=[agent_a, agent_b]
)

여기서 핵심은 output_key 파라미터입니다. 에이전트의 최종 텍스트 응답이 자동으로 지정된 State 키에 저장되어, 후속 에이전트가 {key} 템플릿 구문으로 바로 참조할 수 있습니다.

2-2. LLM-Driven Delegation (transfer_to_agent)

LLM이 상황을 판단하여 다른 에이전트에게 동적으로 제어를 넘기는 방식입니다.

from google.adk.agents import LlmAgent

billing_agent = LlmAgent(
    name="Billing",
    model="gemini-2.0-flash",
    description="결제 관련 문의를 처리합니다."
)

support_agent = LlmAgent(
    name="Support",
    model="gemini-2.0-flash",
    description="기술 지원 요청을 처리합니다."
)

coordinator = LlmAgent(
    name="HelpDesk",
    model="gemini-2.0-flash",
    instruction="결제 문제는 Billing에게, 기술 문제는 Support에게 전달하세요.",
    sub_agents=[billing_agent, support_agent]
)

사용자가 “결제가 안 돼요”라고 말하면, Coordinator의 LLM이 자동으로 다음과 같은 함수 호출을 생성합니다.

transfer_to_agent(agent_name='Billing')

ADK 프레임워크의 AutoFlow가 이 호출을 가로채서 root_agent.find_agent()로 대상 에이전트를 찾고, InvocationContext를 갱신하여 실행 초점을 전환합니다.

2-3. AgentTool을 통한 명시적 호출

다른 에이전트를 도구(Tool)처럼 감싸서 호출하는 방식입니다. transfer_to_agent가 제어 자체를 넘기는 것과 달리, AgentTool은 현재 에이전트의 흐름 안에서 다른 에이전트를 실행하고 결과를 받아옵니다.

from google.adk.agents import LlmAgent
from google.adk.tools import agent_tool

summarizer = LlmAgent(
    name="Summarizer",
    model="gemini-2.0-flash",
    description="텍스트를 요약합니다."
)

research_agent = LlmAgent(
    name="Researcher",
    model="gemini-2.0-flash",
    instruction="주제를 조사하고, Summarizer 도구를 사용해 결과를 요약하세요.",
    tools=[agent_tool.AgentTool(agent=summarizer)]
)

3. Agent ↔ SubAgent 간 컨텍스트 공유

ADK에서 에이전트 계층은 트리 구조로 구성됩니다. 부모 에이전트가 서브에이전트를 호출할 때 같은 InvocationContext를 전달하므로, 여러 가지 메커니즘으로 컨텍스트를 공유할 수 있습니다.

3-1. InvocationContext 공유

Coordinator (부모)
├── InvocationContext ──── 공유 ────→ SubAgent A
│   ├── session
│   ├── state (temp: 포함)        ──→ SubAgent B
│   └── services

부모 에이전트가 SequentialAgent나 ParallelAgent로 서브에이전트를 실행하면, 같은 InvocationContext가 전달됩니다. 이는 곧 동일한 temp: 상태를 공유한다는 의미입니다.

from google.adk.agents import SequentialAgent, LlmAgent

# Step1이 temp: 상태에 데이터를 저장
step1 = LlmAgent(
    name="Analyzer",
    model="gemini-2.0-flash",
    instruction="데이터를 분석하세요.",
    output_key="temp:analysis_result"
)

# Step2가 같은 temp: 상태에서 데이터를 읽음
step2 = LlmAgent(
    name="Reporter",
    model="gemini-2.0-flash",
    instruction="{temp:analysis_result}를 바탕으로 보고서를 작성하세요."
)

pipeline = SequentialAgent(
    name="AnalysisPipeline",
    sub_agents=[step1, step2]
)

3-2. Workflow Agent별 컨텍스트 전달 방식

3-3. Parallel Agent에서의 State 공유 주의점

from google.adk.agents import ParallelAgent, SequentialAgent, LlmAgent

# 병렬 실행 시 서로 다른 output_key를 사용해야 경합 조건을 방지
fetch_weather = LlmAgent(
    name="WeatherFetcher",
    model="gemini-2.0-flash",
    instruction="날씨 정보를 가져오세요.",
    output_key="weather_data"  # 고유한 키
)

fetch_news = LlmAgent(
    name="NewsFetcher",
    model="gemini-2.0-flash",
    instruction="뉴스를 가져오세요.",
    output_key="news_data"  # 고유한 키
)

gather = ParallelAgent(
    name="InfoGatherer",
    sub_agents=[fetch_weather, fetch_news]
)

synthesizer = LlmAgent(
    name="Synthesizer",
    model="gemini-2.0-flash",
    instruction="{weather_data}와 {news_data}를 종합하세요."
)

workflow = SequentialAgent(
    name="GatherAndSynthesize",
    sub_agents=[gather, synthesizer]
)

4. Agent ↔ Tool 간 컨텍스트 공유

도구(Tool)는 에이전트의 실행 환경과 상태에 접근해야 할 때가 많습니다. ADK는 이를 위해 ToolContext를 제공합니다.

4-1. ToolContext의 구조

ToolContext는 CallbackContext를 확장한 것으로, 도구 함수 내에서 세션 상태, 아티팩트, 메모리, 인증 등 프레임워크의 다양한 기능에 접근할 수 있게 합니다.

ToolContext (도구 함수에 전달)
├── state (읽기/쓰기 가능)
│   ├── session.state['key'] 읽기
│   └── session.state['key'] 쓰기 → EventActions.state_delta로 자동 추적
├── load_artifact() / save_artifact()
├── list_artifacts()
├── search_memory(query)
├── request_credential() / get_auth_response()
├── function_call_id
└── actions (EventActions 직접 접근)

4-2. 도구에서 State 읽기/쓰기

from google.adk.tools import ToolContext

def search_database(query: str, tool_context: ToolContext) -> dict:
    # State에서 사용자 설정 읽기
    user_lang = tool_context.state.get("user:preferred_language", "en")
    
    # 도구 실행 로직
    results = perform_search(query, language=user_lang)
    
    # State에 결과 저장 (자동으로 EventActions.state_delta에 추적됨)
    tool_context.state["last_search_query"] = query
    tool_context.state["temp:search_result_count"] = len(results)
    
    return {"results": results, "count": len(results)}

도구 함수에서 tool_context.state를 수정하면, ADK 프레임워크가 자동으로 이 변경을 EventActions.state_delta에 포함시킵니다. 수동으로 EventActions를 구성할 필요가 없습니다.

4-3. CallbackContext를 통한 콜백에서의 State 접근

에이전트의 콜백 함수(before_agent_callback, after_agent_callback 등)에서도 CallbackContext를 통해 동일하게 State에 접근할 수 있습니다.

from google.adk.agents.context import Context
from google.adk.models import LlmRequest
from google.genai import types

def before_model_callback(context: Context, request: LlmRequest):
    call_count = context.state.get("model_calls", 0)
    context.state["model_calls"] = call_count + 1
    
    # 특정 조건에서 모델 호출을 가로채기
    if context.state.get("temp:skip_model"):
        return types.Content(
            parts=[types.Part(text="캐시된 응답을 반환합니다.")]
        )
    
    return None  # 정상적으로 모델 호출 진행

4-4. 도구에서 메모리와 아티팩트 활용

ToolContext는 State 외에도 메모리 검색과 아티팩트 관리 기능을 제공합니다.

from google.adk.tools import ToolContext

async def intelligent_search(query: str, tool_context: ToolContext) -> dict:
    # 과거 세션 메모리에서 관련 정보 검색
    relevant_memories = await tool_context.search_memory(
        f"{query}와 관련된 과거 대화"
    )
    
    # 세션 아티팩트 목록 조회
    artifacts = await tool_context.list_artifacts()
    
    # 특정 아티팩트 로드
    config = await tool_context.load_artifact("search_config.json")
    
    # 결과를 아티팩트로 저장
    await tool_context.save_artifact(
        "search_results.json",
        types.Part(text=json.dumps(results))
    )
    
    return {"results": results, "memory_context": relevant_memories}

5. Escalation — 제어를 상위 또는 다른 에이전트로 되돌리기

Escalation은 서브에이전트가 작업을 완료했거나, 자신이 처리할 수 없는 상황에서 상위 에이전트나 다른 에이전트에게 제어를 반환하는 메커니즘입니다.

5-1. EventActions.escalate — LoopAgent 탈출

LoopAgent 안에서 서브에이전트가 escalate=True를 설정한 이벤트를 발생시키면, 루프가 즉시 종료됩니다.

from google.adk.agents import LoopAgent, LlmAgent, BaseAgent
from google.adk.events import Event, EventActions
from google.adk.agents.invocation_context import InvocationContext

class QualityGate(BaseAgent):
    async def _run_async_impl(self, ctx: InvocationContext):
        status = ctx.session.state.get("quality_status", "fail")
        should_stop = (status == "pass")
        yield Event(
            author=self.name,
            actions=EventActions(escalate=should_stop)
        )

code_refiner = LlmAgent(
    name="CodeRefiner",
    model="gemini-2.0-flash",
    instruction="코드를 개선하세요. 현재 코드: {current_code}",
    output_key="current_code"
)

quality_checker = LlmAgent(
    name="QualityChecker",
    model="gemini-2.0-flash",
    instruction="{current_code}의 품질을 평가하세요. 'pass' 또는 'fail'로 답하세요.",
    output_key="quality_status"
)

refinement_loop = LoopAgent(
    name="RefinementLoop",
    max_iterations=5,
    sub_agents=[code_refiner, quality_checker, QualityGate(name="Gate")]
)

동작 흐름:

[반복 1] CodeRefiner → QualityChecker → Gate(escalate=False) → 계속
[반복 2] CodeRefiner → QualityChecker → Gate(escalate=False) → 계속
[반복 3] CodeRefiner → QualityChecker(pass!) → Gate(escalate=True) → 루프 종료

5-2. transfer_to_agent — 부모/형제 에이전트로 전환

서브에이전트가 transfer_to_agent를 호출하여 부모 에이전트나 형제 에이전트에게 제어를 넘길 수 있습니다. 이는 LLM이 자연어 이해를 기반으로 동적으로 결정합니다.

billing_agent = LlmAgent(
    name="Billing",
    model="gemini-2.0-flash",
    description="결제 관련 문의를 처리합니다.",
    instruction="""결제 관련 질문에 답하세요.
    기술 지원이 필요한 질문이면 Support 에이전트로 전환하세요.
    일반적인 문의면 HelpDesk(부모)로 전환하세요."""
)

support_agent = LlmAgent(
    name="Support",
    model="gemini-2.0-flash",
    description="기술 지원을 제공합니다.",
    instruction="""기술 문제를 해결하세요.
    결제 관련 문의면 Billing 에이전트로 전환하세요."""
)

coordinator = LlmAgent(
    name="HelpDesk",
    model="gemini-2.0-flash",
    instruction="사용자 요청을 분석해 적절한 에이전트에게 전달하세요.",
    sub_agents=[billing_agent, support_agent]
)

전환 가능한 범위:

HelpDesk (부모)
├── Billing ←→ Support (형제 간 전환 가능)
│   └── Billing → HelpDesk (자식 → 부모 전환 가능)
└── Support → HelpDesk (자식 → 부모 전환 가능)

ADK에서는 disallow_transfer_to_parent와 disallow_transfer_to_peers 옵션으로 전환 범위를 세밀하게 제어할 수 있습니다.

5-3. fallback_to_parent — 자동 부모 복귀

ADK에 추가된 fallback_to_parent 기능은 서브에이전트가 작업을 완료한 후 자동으로 부모 에이전트에게 제어를 반환합니다.

specialist = LlmAgent(
    name="DataAnalyst",
    model="gemini-2.0-flash",
    description="데이터 분석 전문가입니다.",
    instruction="요청된 데이터 분석을 수행하세요.",
    fallback_to_parent=True  # 작업 완료 후 자동으로 부모에게 복귀
)

coordinator = LlmAgent(
    name="ProjectManager",
    model="gemini-2.0-flash",
    instruction="프로젝트 관리를 담당합니다. 데이터 분석이 필요하면 DataAnalyst에게 위임하세요.",
    sub_agents=[specialist]
)

fallback_to_parent=True가 동작하는 조건:

1. 해당 에이전트가 LlmAgent 인스턴스일 것
2. fallback_to_parent=True로 설정되어 있을 것
3. 부모 에이전트가 존재할 것
4. 모델 응답에 명시적 transfer_to_agent 호출이 없을 것

이 네 가지 조건이 모두 충족되면, 에이전트는 실행을 마친 후 자동으로 transfer_to_agent(parent_name)을 생성하여 부모에게 돌아갑니다.

5-4. Escalation 패턴 비교

6. 실전 종합 예제: 고객 지원 시스템

지금까지 다룬 모든 메커니즘을 결합한 고객 지원 멀티에이전트 시스템 예제입니다.

from google.adk.agents import (
    LlmAgent, SequentialAgent, ParallelAgent, LoopAgent, BaseAgent
)
from google.adk.tools import agent_tool, ToolContext
from google.adk.events import Event, EventActions


# === 도구 정의: ToolContext를 통한 상태 접근 ===

def lookup_customer(customer_id: str, tool_context: ToolContext) -> dict:
    """고객 정보 조회 도구 — State를 통해 결과를 공유"""
    customer = db.get_customer(customer_id)
    tool_context.state["user:customer_tier"] = customer["tier"]
    tool_context.state["temp:customer_name"] = customer["name"]
    return customer

def check_order_status(order_id: str, tool_context: ToolContext) -> dict:
    """주문 상태 확인 — 메모리 검색으로 과거 맥락 활용"""
    past_context = tool_context.search_memory(f"주문 {order_id} 관련 이력")
    status = db.get_order(order_id)
    return {"status": status, "history": past_context}


# === 전문 서브에이전트 ===

billing_specialist = LlmAgent(
    name="BillingSpecialist",
    model="gemini-2.0-flash",
    description="결제, 환불, 청구서 관련 문제를 처리합니다.",
    instruction="""결제 관련 문제를 해결하세요.
    고객 등급은 {user:customer_tier}입니다.
    기술 문제라면 TechSupport로 전환하세요.
    해결 완료되면 요약을 작성하세요.""",
    output_key="resolution_summary",
    fallback_to_parent=True  # 완료 후 자동 복귀
)

tech_support = LlmAgent(
    name="TechSupport",
    model="gemini-2.0-flash",
    description="기술 지원과 계정 접근 문제를 처리합니다.",
    instruction="""기술 문제를 해결하세요.
    결제 문제라면 BillingSpecialist로 전환하세요.""",
    output_key="resolution_summary",
    fallback_to_parent=True
)


# === 품질 검증 루프 ===

class ResolutionValidator(BaseAgent):
    """해결 결과 검증 — escalate로 루프 탈출"""
    async def _run_async_impl(self, ctx):
        score = ctx.session.state.get("satisfaction_score", 0)
        yield Event(
            author=self.name,
            actions=EventActions(escalate=(score >= 4))
        )

satisfaction_check = LlmAgent(
    name="SatisfactionChecker",
    model="gemini-2.0-flash",
    instruction="""고객 만족도를 1-5점으로 평가하세요.
    해결 내용: {resolution_summary}""",
    output_key="satisfaction_score"
)

quality_loop = LoopAgent(
    name="QualityAssurance",
    max_iterations=3,
    sub_agents=[satisfaction_check, ResolutionValidator(name="Validator")]
)


# === 루트 에이전트: 전체 오케스트레이션 ===

root_agent = LlmAgent(
    name="CustomerServiceHub",
    model="gemini-2.0-flash",
    instruction="""고객 지원 허브입니다.
    1. 먼저 고객 정보를 조회하세요.
    2. 문제 유형에 따라 적절한 전문가에게 전달하세요.
    3. 해결 후 품질을 검증하세요.""",
    tools=[lookup_customer, check_order_status],
    sub_agents=[billing_specialist, tech_support]
)

이 시스템의 데이터 흐름:

사용자: "주문 #1234 환불 요청합니다"
    │
    ▼
[CustomerServiceHub]
    ├── lookup_customer() → tool_context.state에 고객 정보 저장
    ├── transfer_to_agent('BillingSpecialist')
    │
    ▼
[BillingSpecialist]
    ├── {user:customer_tier}로 고객 등급 참조 (State 공유)
    ├── 환불 처리
    ├── output_key="resolution_summary"로 결과 저장
    └── fallback_to_parent → CustomerServiceHub로 자동 복귀
    │
    ▼
[CustomerServiceHub]
    └── resolution_summary를 확인하고 최종 응답

7. 컨텍스트 공유 전략 요약

메커니즘별 비교표

설계 원칙

1. State 키 네이밍 컨벤션을 정하세요. 에이전트 간 공유하는 키는 문서화하고, 접두사로 스코프를 명확히 하세요.
2. ParallelAgent에서는 고유 키를 사용하세요. 병렬 실행 시 같은 키에 쓰면 경합 조건이 발생합니다.
3. temp:는 호출 체인 내에서만 사용하세요. 다음 사용자 입력까지 데이터를 유지하려면 기본 키나 user: 접두사를 쓰세요.
4. fallback_to_parent로 자동 복귀를 보장하세요. 단일 작업을 위임하는 서브에이전트에 설정하면, 제어 흐름이 예측 가능해집니다.
5. ToolContext에서 State 변경을 추적하세요. session.state를 직접 수정하지 말고, 항상 Context 객체를 통해 수정해야 변경이 올바르게 추적됩니다.

참고 자료

• ADK 공식 문서 - Multi-Agent Systems
• ADK 공식 문서 - Context
• ADK 공식 문서 - State
• ADK 공식 문서 - Sessions
• ADK 공식 문서 - Custom Tools
• Google Cloud Blog - Agent state and memory with ADK
• Google Developers Blog - Developer’s guide to multi-agent patterns in ADK
• ADK GitHub - fallback_to_parent PR #2253

이 글에서는 BigQuery에서 사용할 수 있는 모든 테이블 유형을 나열하고, 각 방식의 구조·특징·장단점을 비교합니다.

전체 구조 한눈에 보기

BigQuery에서 데이터를 사용하는 방법
│
├── 1. Native Table (BigQuery 내부 저장)
│
├── 2. External Table (GCS 파일 참조)
│   │
│   ├── 메타스토어 없음 (BigQuery 카탈로그만)
│   │   ├── 2-A. 기본 External Table
│   │   └── 2-B. BigLake External Table (flat files)
│   │
│   ├── BigQuery가 메타스토어 관리
│   │   └── 2-C. BigLake Managed Iceberg Table
│   │
│   ├── GCS 파일 자체가 메타스토어 (자체 관리)
│   │   └── 2-D. BigLake External Table (Iceberg / Delta Lake / Hudi)
│   │
│   ├── GCP 관리형 메타스토어
│   │   ├── 2-E. BigLake Metastore (REST Catalog)
│   │   └── 2-F. Dataproc Metastore (Hive Metastore Service)
│   │
│   └── 자체 호스팅 메타스토어
│       └── 2-G. Self-hosted Hive Metastore
│
└── 3. Object Table (비정형 데이터)

1. BigQuery Native Table

데이터 위치: BigQuery 내부 (Capacitor 포맷) 메타스토어: BigQuery 카탈로그 (완전 관리형)

BigQuery의 기본이자 가장 성능이 좋은 방식입니다. 데이터가 BigQuery 내부 스토리지에 Capacitor라는 독자 컬럼형 포맷으로 저장됩니다.

CREATE TABLE project.dataset.sales (
  order_id INT64,
  customer_id STRING,
  amount NUMERIC,
  order_date DATE
)
PARTITION BY order_date
CLUSTER BY customer_id;

핵심 기능

장점

• 최고 성능: BigQuery 엔진에 최적화된 Capacitor 포맷, 자동 파티션 pruning과 클러스터링
• 완전 관리형: 인프라 관리 불필요, 자동 스토리지 최적화
• 풍부한 기능: Time Travel, 스냅샷, 복제, CDC 등 엔터프라이즈 기능 전체 사용 가능
• 비용 모델 단순: 스토리지 비용 + 쿼리 비용 (on-demand 또는 슬롯 기반)

단점

• 데이터 이동 필수: GCS 등 외부에 있는 데이터를 BigQuery로 로드해야 함
• 독점 포맷: Capacitor는 BigQuery 전용이라 Spark 등 다른 엔진에서 직접 읽을 수 없음
• 스토리지 비용 이중화: 원본 소스와 BigQuery 양쪽에 데이터가 존재하면 비용 증가
• 대용량 로드 시간: 초기 데이터 적재에 시간 소요

적합한 경우

• BigQuery가 유일한 분석 엔진인 환경
• 최고 쿼리 성능과 SLA가 필요한 프로덕션 대시보드
• DML이 빈번한 워크로드 (실시간 업데이트, CDC)
• 데이터가 이미 BigQuery에 있거나, 적재 파이프라인이 확립된 환경

2-A. 기본 External Table (메타스토어 없음)

데이터 위치: GCS 메타스토어: 없음 (BigQuery 카탈로그에 스키마만 등록) BigLake Connection: 사용하지 않음

가장 단순한 External Table입니다. GCS의 파일을 직접 URI로 참조하며, BigLake Connection 없이 사용자의 GCS 권한으로 직접 접근합니다.

CREATE EXTERNAL TABLE project.dataset.ext_sales
OPTIONS (
  format = 'PARQUET',
  uris = ['gs://my-bucket/sales/*.parquet']
);

CSV, JSON(newline-delimited), Avro, Parquet, ORC 등 다양한 파일 포맷을 지원합니다.

장점

• 설정 최소화: URI만 지정하면 바로 쿼리 가능
• 데이터 이동 없음: GCS에 있는 파일을 그대로 사용
• 비용 절감: BigQuery 스토리지 비용 없음 (쿼리 비용만 발생)
• ETL 파이프라인 간소화: 별도 로드 단계 불필요

단점

• 성능 제한: 매 쿼리마다 GCS에서 파일을 읽으므로 Native 대비 느림
• DML 불가: 읽기 전용 (INSERT/UPDATE/DELETE 불가)
• 메타데이터 캐싱 없음: 쿼리마다 파일 목록을 다시 탐색
• 보안 제한: Row/Column 수준 보안 미지원
• 권한 관리 복잡: 쿼리 실행자가 GCS 버킷에 직접 권한이 있어야 함
• 파일 관리 부담: 파일 추가/삭제 시 URI 패턴에 맞춰야 함
• Hive 파티션 탐색 제한: _FILE_NAME 가상 컬럼을 사용하거나 Hive 파티셔닝 옵션을 별도로 설정해야 함

적합한 경우

• 빠른 PoC나 일회성 분석
• 소규모 데이터셋 (수 GB 이하)
• 데이터 파이프라인 초기 단계에서 빠르게 테스트

2-B. BigLake External Table (Flat Files)

데이터 위치: GCS 메타스토어: 없음 (BigQuery 카탈로그에 스키마만 등록) BigLake Connection: 사용

기본 External Table에 BigLake Connection을 추가한 형태입니다. 구조는 동일하지만, 접근 위임(Access Delegation)이 핵심 차이입니다.

-- BigLake Connection 생성 (1회)
-- Console: BigQuery → External Connections → Cloud Resource Connection

CREATE EXTERNAL TABLE project.dataset.bl_sales
WITH CONNECTION `project.region.my-connection`
OPTIONS (
  format = 'PARQUET',
  uris = ['gs://my-bucket/sales/*.parquet']
);

BigLake Connection의 서비스 계정이 GCS에 접근하므로, 개별 사용자에게 GCS 권한을 부여할 필요가 없습니다.

2-A 대비 추가 장점

• 접근 위임: 사용자에게 GCS 직접 권한 불필요 → 데이터 유출 위험 감소
• Row/Column 수준 보안: 정책 태그와 행 수준 보안 필터 적용 가능
• 메타데이터 캐싱: BigQuery가 파일 목록과 스키마를 캐싱하여 쿼리 계획 시간 단축
• BigQuery 옵티마이저 통합: 더 나은 쿼리 최적화 가능
• 통합 거버넌스: Data Catalog, DLP 등과 연계

단점

• 여전히 읽기 전용: DML 미지원
• BigLake Connection 설정 필요: 초기 설정이 기본 External Table보다 복잡
• 쿼리 성능: Native Table 대비 여전히 느림 (GCS I/O)
• 메타데이터 캐시 갱신: 파일이 자주 변경되면 캐시 무효화 전략 필요

적합한 경우

• 프로덕션 환경에서 GCS 데이터를 BigQuery로 조회해야 하는 경우
• 데이터 거버넌스와 보안이 중요한 조직
• 다수의 사용자가 동일 GCS 데이터를 조회하는 환경

2-C. BigLake Managed Iceberg Table

데이터 위치: GCS (Parquet) 메타스토어: BigQuery 내부 (Big Metadata) BigLake Connection: 사용

BigQuery가 Iceberg 메타데이터를 내부적으로 완전 관리하는 방식입니다. 사용자 입장에서는 Native Table과 거의 동일한 경험을 제공하면서, 데이터는 고객 소유의 GCS 버킷에 열린 포맷(Parquet)으로 저장됩니다.

CREATE TABLE project.dataset.managed_sales (
  order_id INT64,
  customer_id STRING,
  amount NUMERIC,
  order_date DATE
)
CLUSTER BY customer_id
WITH CONNECTION `project.region.my-connection`
OPTIONS (
  file_format = 'PARQUET',
  table_format = 'ICEBERG',
  storage_uri = 'gs://my-bucket/managed-sales'
);

-- Native Table과 동일하게 DML 사용 가능
INSERT INTO project.dataset.managed_sales
VALUES (1, 'C001', 150.00, '2026-01-15');

UPDATE project.dataset.managed_sales
SET amount = 200.00
WHERE order_id = 1;

장점

• Native Table 수준의 사용성: DML, Streaming, Time Travel 전부 지원
• 열린 포맷: 데이터가 GCS에 Parquet으로 저장되어 벤더 종속 최소화
• 자동 최적화: 파일 크기 최적화, 클러스터링, 메타데이터 컴팩션, 고아 파일 GC 자동 수행
• Row/Column 보안: 완전 지원
• 외부 엔진 접근 가능: EXPORT TABLE METADATA로 Iceberg 메타데이터를 내보내면 Spark 등에서 읽기 가능

단점

• 외부 엔진 읽기가 즉시적이지 않음: Spark에서 읽으려면 EXPORT TABLE METADATA 실행 필요
• 외부 엔진 쓰기 불가: BigQuery만 쓰기 가능, Spark에서 직접 INSERT 불가
• BigQuery 종속: 메타데이터가 BigQuery 내부에 있으므로 BigQuery 없이는 테이블 관리 불가
• BigLake Connection 필수: 초기 설정 비용

적합한 경우

• BigQuery가 주 분석 엔진이면서, 가끔 Spark 등에서 데이터를 읽어야 하는 경우
• Native Table의 기능이 필요하면서 데이터를 열린 포맷으로 유지하고 싶은 경우
• 벤더 종속을 줄이면서도 BigQuery의 편의성을 포기하고 싶지 않은 경우

2-D. BigLake External Table (Open Table Format)

데이터 위치: GCS (Parquet) 메타스토어: GCS의 메타데이터 파일 (자체 관리) BigLake Connection: 사용

Spark, Flink 등 외부 엔진이 GCS에 직접 Open Table Format(Iceberg, Delta Lake, Hudi)으로 데이터를 쓰고, BigQuery에서 이를 읽는 방식입니다. 메타데이터 파일이 GCS에 존재하며, 데이터를 쓰는 엔진이 메타스토어를 직접 관리합니다.

Iceberg

CREATE EXTERNAL TABLE project.dataset.ext_iceberg_sales
WITH CONNECTION `project.region.my-connection`
OPTIONS (
  format = 'ICEBERG',
  uris = ["gs://my-bucket/warehouse/sales/metadata/v3.metadata.json"]
);

Spark 등이 GCS에 Iceberg 표준 메타데이터(metadata.json, manifest list, manifest file)를 직접 관리합니다. BigQuery는 이 메타데이터를 읽어서 쿼리합니다.

Delta Lake

CREATE EXTERNAL TABLE project.dataset.ext_delta_sales
WITH CONNECTION `project.region.my-connection`
OPTIONS (
  format = 'DELTA_LAKE',
  uris = ["gs://my-bucket/delta/sales"]
);

Delta Lake의 트랜잭션 로그(_delta_log/)를 BigQuery가 직접 해석합니다.

Apache Hudi

CREATE EXTERNAL TABLE project.dataset.ext_hudi_sales
WITH CONNECTION `project.region.my-connection`
OPTIONS (
  format = 'HUDI',
  uris = ["gs://my-bucket/hudi/sales"]
);

Hudi 테이블은 manifest 파일 기반으로 BigQuery에서 조회할 수 있습니다.

장점

• 외부 엔진 주도: Spark/Flink가 자유롭게 데이터를 쓰고, BigQuery에서 즉시 조회
• 추가 인프라 불필요: GCS만 있으면 되므로 별도 메타스토어 서비스 없음
• 오픈 포맷 호환: 표준 Iceberg/Delta/Hudi 포맷이라 다양한 엔진에서 접근 가능
• 비용 효율: 메타스토어 서비스 비용 없음

단점

• BigQuery에서 읽기 전용: BigQuery로는 DML 불가
• 메타데이터 수동 관리: Iceberg의 경우 metadata.json URI를 직접 관리해야 하고, 스냅샷이 업데이트될 때마다 URI를 갱신해야 할 수 있음
• 스키마 진화 복잡: BigQuery 외부 테이블 정의와 실제 메타데이터 간 불일치 가능
• 컴팩션 직접 수행: small files 문제를 Spark 등에서 직접 해결해야 함
• 동시성 제어 제한: 여러 엔진이 동시에 쓰면 충돌 가능 (특히 Catalog 없이 사용 시)

Open Table Format 비교

적합한 경우

• Spark/Flink가 주 적재 엔진이고 BigQuery는 분석 전용인 환경
• 별도 메타스토어 서비스를 운영하고 싶지 않은 소규모 팀
• 이미 Iceberg/Delta/Hudi로 데이터를 관리하고 있어 BigQuery에서 조회만 하면 되는 경우

2-E. BigLake Metastore + REST Catalog

데이터 위치: GCS (Parquet) 메타스토어: BigLake Metastore (GCP 관리형 서비스) BigLake Connection: 사용

GCP가 제공하는 관리형 Iceberg REST Catalog 서비스입니다. Iceberg의 표준 REST Catalog API를 지원하므로, Spark·Flink·BigQuery·Databricks·Trino 등 여러 엔진이 동일한 메타스토어를 공유할 수 있습니다.

Spark에서 테이블 생성

spark.conf.set("spark.sql.catalog.my_catalog", "org.apache.iceberg.spark.SparkCatalog")
spark.conf.set("spark.sql.catalog.my_catalog.type", "rest")
spark.conf.set("spark.sql.catalog.my_catalog.uri",
    "https://biglake.googleapis.com/iceberg/v1beta/restcatalog")
spark.conf.set("spark.sql.catalog.my_catalog.warehouse",
    "projects/PROJECT/locations/REGION/catalogs/CATALOG")
spark.conf.set("spark.sql.catalog.my_catalog.token", "<access_token>")

spark.sql("""
  CREATE TABLE my_catalog.db.sales (
    order_id BIGINT,
    customer_id STRING,
    amount DECIMAL(10,2),
    order_date DATE
  ) USING iceberg
  PARTITIONED BY (month(order_date))
""")

BigQuery에서 조회

BigLake Metastore에 등록된 테이블은 BigQuery에서 자동으로 보입니다. 별도의 CREATE EXTERNAL TABLE 없이도 BigQuery 카탈로그에 나타납니다.

SELECT * FROM `project.dataset.sales`
WHERE order_date >= '2026-01-01';

장점

• 진정한 멀티엔진: Spark, BigQuery, Databricks, Flink, Trino 모두에서 읽기/쓰기 가능
• 서버리스: 메타스토어 인프라 관리 불필요
• 자동 동기화: 한 엔진에서 변경한 메타데이터가 다른 엔진에서 즉시 반영
• 표준 API: Iceberg REST Catalog 표준을 따르므로 벤더 종속 최소
• Credential Vending: 세밀한 접근 제어 지원
• metadata.json URI 수동 관리 불필요: 카탈로그가 자동 추적

단점

• Iceberg 전용: Delta Lake, Hudi는 지원하지 않음
• 서비스 비용: BigLake Metastore 사용에 따른 추가 비용
• Region 제약: 지원 Region이 제한적일 수 있음
• 비교적 새로운 서비스: 아직 GA 전이거나 기능이 빠르게 변화 중
• 설정 복잡도: Spark Catalog 설정, 인증 토큰 관리 등 초기 설정이 복잡

적합한 경우

• 멀티엔진 레이크하우스: Spark로 적재하고 BigQuery + Databricks로 분석하는 환경
• Iceberg 기반 데이터 레이크를 구축하면서 메타스토어 운영 부담을 줄이고 싶은 경우
• 여러 팀/서비스가 동일 데이터를 다양한 엔진으로 접근하는 대규모 조직

2-F. Dataproc Metastore (Hive Metastore Service)

데이터 위치: GCS (Parquet, ORC 등) 메타스토어: Dataproc Metastore (GCP 관리형 Hive Metastore) BigLake Connection: 사용 가능

GCP가 관리하는 Hive Metastore 호환 서비스입니다. 기존 Hadoop/Hive 생태계와의 호환성이 핵심입니다.

Dataproc에서 테이블 생성

-- Dataproc Spark SQL
CREATE TABLE db.sales (
  order_id BIGINT,
  customer_id STRING,
  amount DECIMAL(10,2)
)
PARTITIONED BY (order_date STRING)
STORED AS PARQUET
LOCATION 'gs://my-bucket/hive/sales';

BigQuery에서 연동

Dataproc Metastore에 등록된 Hive 테이블을 BigQuery에서 외부 테이블로 연결할 수 있습니다.

CREATE EXTERNAL TABLE project.dataset.hive_sales
WITH CONNECTION `project.region.my-connection`
OPTIONS (
  format = 'PARQUET',
  uris = ['gs://my-bucket/hive/sales/*'],
  hive_partition_uri_prefix = 'gs://my-bucket/hive/sales',
  require_hive_partition_filter = true
);

장점

• Hive 호환: 기존 Hive 쿼리, Spark SQL, Presto 등과 완벽 호환
• 관리형 서비스: Hive Metastore를 직접 운영할 필요 없음
• Dataproc 통합: Dataproc 클러스터와 자동 연결
• 성숙한 생태계: 수년간 검증된 Hive Metastore 프로토콜
• 다양한 테이블 포맷: Hive, Iceberg, Delta Lake 등 여러 포맷의 메타데이터 저장 가능

단점

• BigLake Metastore 대비 레거시: Google은 BigLake Metastore로의 마이그레이션을 권장
• 인스턴스 관리 필요: 서버리스가 아닌 인스턴스 기반이라 크기 조정 필요
• 비용: 인스턴스 비용이 발생 (사용하지 않아도 과금)
• BigQuery 연동 제한: BigQuery에서 직접 Hive Metastore를 참조하지 못하고, 외부 테이블을 별도로 생성해야 함
• 메타데이터 동기화: BigQuery 외부 테이블의 스키마가 Hive 테이블 변경을 자동 반영하지 않을 수 있음

적합한 경우

• 기존 Hadoop/Hive 워크로드를 GCP로 마이그레이션한 환경
• Hive 호환 메타스토어가 필요한 레거시 시스템과의 연계
• Dataproc 클러스터를 주로 사용하는 팀

2-G. Self-hosted Hive Metastore

데이터 위치: GCS (Parquet, ORC 등) 메타스토어: 직접 구축한 Hive Metastore (GCE/GKE에서 운영) BigLake Connection: 사용 가능

Hive Metastore를 GCE VM이나 GKE 위에 직접 설치하고 운영하는 방식입니다.

구성 예시

┌─────────────────────────────────────┐
│ GCE VM / GKE Pod                    │
│  ├── Hive Metastore Service         │
│  └── Backend DB (MySQL / PostgreSQL)│
└──────────────┬──────────────────────┘
               │ Thrift Protocol
    ┌──────────┼──────────┐
    │          │          │
  Spark     Presto    BigQuery
                    (External Table)

장점

• 완전한 제어: 버전, 설정, 플러그인 등을 자유롭게 커스터마이징
• 비용 최적화 가능: 소규모 환경에서는 작은 VM으로 운영 가능
• 특수 요구사항 대응: 커스텀 Serde, UDF 등 특수 기능 사용 가능

단점

• 운영 부담 최대: 가용성, 백업, 업그레이드, 모니터링 전부 직접 관리
• 단일 장애점: Metastore 다운 시 모든 연관 워크로드 영향
• 스케일링 직접 관리: 부하 증가에 따른 스케일업/아웃 직접 수행
• BigQuery 연동 번거로움: BigQuery에서 직접 참조 불가, 별도 외부 테이블 생성 필요
• 보안 관리: 네트워크, 인증 등 보안 구성 직접 수행

적합한 경우

• 온프레미스에서 마이그레이션 중이고 Hive Metastore를 그대로 가져온 경우
• Dataproc Metastore의 기능이나 Region 지원이 부족한 특수 환경
• 이미 Hive Metastore 운영 노하우가 있는 팀

3. Object Table (비정형 데이터)

데이터 위치: GCS (이미지, PDF, 텍스트, 오디오 등) 메타스토어: 없음

구조화된 데이터가 아닌 비정형 데이터를 BigQuery에서 다루기 위한 특수한 테이블 유형입니다.

CREATE EXTERNAL TABLE project.dataset.product_images
WITH CONNECTION `project.region.my-connection`
OPTIONS (
  object_metadata = 'SIMPLE',
  uris = ['gs://my-bucket/images/*']
);

-- 파일 메타데이터 조회
SELECT uri, content_type, size, updated
FROM project.dataset.product_images;

-- BigQuery ML과 연동하여 이미지 분류
SELECT uri, ml_predict_row.label
FROM ML.PREDICT(
  MODEL `project.dataset.vision_model`,
  TABLE `project.dataset.product_images`
);

장점

• 비정형 데이터 통합: SQL로 이미지, 문서 등의 메타데이터 조회 가능
• BigQuery ML 연동: 비정형 데이터에 대한 ML 추론 파이프라인 구성 가능
• Vertex AI 통합: 비전 모델 등과 연계하여 분석

단점

• 데이터 자체를 읽지는 않음: 파일의 메타데이터만 BigQuery에서 조회
• 특수 목적: 일반적인 데이터 분석과는 용도가 다름

전체 비교 요약

기능 비교

메타스토어 관리 비교

성능 비교 (상대적)

의사결정 가이드

질문 1: BigQuery 외에 다른 엔진이 필요한가?

BigQuery만 사용
├── DML이 필요한가?
│   ├── Yes → Native Table 또는 Managed Iceberg
│   └── No  → BigLake External Table (flat files)
│
Spark/Flink/Databricks도 사용
├── 어느 엔진이 데이터를 쓰는가?
│   ├── BigQuery가 씀 → Managed Iceberg + EXPORT METADATA
│   ├── Spark가 씀   → BigLake Metastore (REST Catalog) 또는 External Iceberg
│   └── 양쪽 다 씀   → BigLake Metastore (REST Catalog)

질문 2: 메타스토어 운영에 얼마나 투자할 수 있는가?

전혀 관리하고 싶지 않다
├── BigQuery 중심 → Native Table
└── 멀티엔진      → BigLake Metastore (서버리스)

최소한으로 관리하겠다
├── 메타데이터 파일만 → External Iceberg (GCS)
└── Hive 호환 필요   → Dataproc Metastore

전부 직접 제어하겠다
└── Self-hosted Hive Metastore

질문 3: 기존 환경은 무엇인가?

자주 하는 오해

“External Table이면 다 같은 거 아닌가요?”

아닙니다. BigLake Connection 유무에 따라 보안 모델이 완전히 달라지고, Open Table Format 사용 여부에 따라 pruning 성능이 크게 차이납니다. 같은 “External Table”이라는 이름이지만, 기본 External Table과 BigLake Metastore 기반 Iceberg 테이블은 아키텍처적으로 완전히 다른 방식입니다.

“Managed Iceberg이면 Native Table이랑 뭐가 다른가요?”

사용성은 비슷하지만, 데이터가 고객 소유 GCS 버킷에 Parquet으로 저장된다는 점이 핵심 차이입니다. Native Table은 BigQuery 내부 Capacitor 포맷이라 다른 엔진에서 읽을 수 없지만, Managed Iceberg는 메타데이터를 export하면 Spark 등에서도 읽을 수 있습니다. 반면 쿼리 성능은 Native Table이 조금 더 좋습니다.

“BigLake Metastore와 Dataproc Metastore는 같은 건가요?”

다릅니다. Dataproc Metastore는 Hive Metastore 호환 서비스이고, BigLake Metastore는 Iceberg REST Catalog 표준 서비스입니다. Google은 BigLake Metastore로의 마이그레이션을 권장하고 있으며, 이를 위한 마이그레이션 도구도 제공합니다.

“GCS에 Parquet만 올려두면 바로 쿼리할 수 있나요?”

기본 External Table이나 BigLake External Table(flat files)을 만들면 가능합니다. 하지만 이 방식은 파일 수준에서만 작동하므로, 테이블 수준의 스키마 진화, ACID 트랜잭션, Time Travel 등은 지원되지 않습니다. 이런 기능이 필요하면 Iceberg 같은 Open Table Format을 사용해야 합니다.

마무리

BigQuery에서 데이터를 다루는 방법은 생각보다 많고, 각 방식마다 메타스토어 관리 주체·성능·기능·운영 부담이 다릅니다. “어떤 방식이 제일 좋은가”보다는 “우리 조직의 데이터 흐름에서 메타스토어를 누가, 어떻게 관리하는 것이 가장 자연스러운가”를 기준으로 선택하는 것이 핵심입니다.

이 글에서는 각 CSP의 에이전트 스택을 프레임워크 ↔ 런타임 두 축으로 분리하여 비교하고, 오픈소스 대안과 벤더 Lock-in 리스크를 체계적으로 정리합니다.

1. 전체 구조 한눈에 보기

핵심 관찰: 3사 모두 자체 프레임워크는 오픈소스로 공개하면서, 매니지드 런타임에서 수익을 창출하는 동일한 전략을 취하고 있습니다. 프레임워크 레벨에서는 Lock-in이 적지만, 런타임 레벨에서 종속성이 발생합니다.

2. AWS: Bedrock AgentCore + Strands Agents

2.1 Strands Agents SDK (오픈소스 프레임워크)

AWS가 내부적으로 Amazon Q Developer, AWS Glue, VPC Reachability Analyzer 등에서 사용하던 에이전트 프레임워크를 Apache 2.0으로 공개한 것입니다.

핵심 철학 — “모델 주도(Model-Driven)”

기존 프레임워크들이 개발자가 오케스트레이션 로직을 명시적으로 작성하도록 요구했다면, Strands는 최신 LLM의 추론 능력에 의존하여 몇 줄의 코드만으로 에이전트를 구성합니다.

from strands import Agent

agent = Agent(system_prompt="You are a helpful assistant.")
agent("서울의 오늘 날씨를 알려줘")

주요 특징:

• Python/TypeScript 듀얼 SDK
• MCP(Model Context Protocol) 네이티브 지원
• Swarm, Graph, A2A 세 가지 멀티에이전트 패턴
• OpenTelemetry 기반 관측성
• 20+ 내장 도구 (Retrieve, Thinking, Shell, HTTP 등)

2.2 Amazon Bedrock AgentCore (매니지드 런타임)

2025년 12월 GA된 AgentCore는 모듈러 아키텍처가 특징입니다. 9개 서비스를 독립적으로 또는 조합하여 사용할 수 있습니다.

차별점:

• 프레임워크 무관: LangGraph, CrewAI, LlamaIndex, Google ADK, OpenAI Agents SDK, Strands 모두 지원
• 모델 무관: OpenAI, Gemini, Claude, Nova, Llama, Mistral 등 자유롭게 선택
• 과금: 실제 리소스 소비 기반, I/O 대기 시간은 무료
• 세션 격리: 각 세션이 전용 microVM에서 실행되어 CPU/메모리/파일시스템 완전 격리

2.3 Lock-in 분석

탈출 전략: Strands SDK + Docker/K8s 자체 배포. Strands는 4가지 배포 아키텍처(로컬, API 모놀리스, 에이전트/도구 분리, Return-of-Control)를 공식 지원합니다.

3. Azure: AI Foundry Agent Service + Microsoft Agent Framework

3.1 Microsoft Agent Framework (오픈소스 프레임워크)

Semantic Kernel과 AutoGen을 통합한 차세대 프레임워크로, 2026년 RC(Release Candidate)에 도달했습니다.

핵심 특징:

• .NET과 Python 지원
• 그래프 기반 워크플로 (순차, 동시, 핸드오프, 그룹 채팅)
• MCP, A2A, OpenAPI 등 오픈 표준 지원
• 스트리밍, 체크포인팅, Human-in-the-Loop
• MIT 라이선스

에이전트 타입이 풍부합니다:

다중 모델 공급자 지원: Azure OpenAI, OpenAI, GitHub Copilot, Anthropic Claude, AWS Bedrock, Ollama 등과 호환됩니다. 이 점에서 Semantic Kernel은 특정 CSP에 종속되지 않는 유연성을 가집니다.

3.2 Azure AI Foundry Agent Service (매니지드 런타임)

10,000개 이상의 고객사가 GA 이후 사용 중인 매니지드 서비스입니다.

메모리 관리가 세분화되어 있습니다:

• 단기 메모리: 현재 세션 대화를 추적
• 장기 메모리: 세션 간 지속되는 영속 메모리, 3단계 프로세스(추출 → 통합 → 검색)로 운영
• MemorySearchTool: 네임스페이스로 메모리 격리, 검색 옵션 커스터마이징 가능

도구 통합:

• Bing Search, Azure AI Search (지식 검색)
• REST API 자동 호출 (Swagger/OpenAPI 3.0 정의 기반)
• Azure Function Apps 연동
• Azure Logic Apps 통합
• RAG (TextSearchProvider)

Microsoft 생태계 통합이 최대 강점입니다:

• Microsoft 365, Teams 원클릭 배포
• Entra ID 기반 거버넌스 및 SSO
• Copilot Studio 연동
• Application Insights 기반 모니터링
• Azure DevOps CI/CD 통합

3.3 Lock-in 분석

탈출 전략: Semantic Kernel은 OpenAI, Anthropic, Bedrock 등 다양한 모델 백엔드를 지원하므로, 프레임워크 레벨에서는 전환이 용이합니다. 런타임은 Docker/K8s + FastAPI로 직접 구축하되, 메모리 관리와 도구 통합을 재구현해야 합니다.

4. GCP: Vertex AI Agent Engine + ADK

4.1 Agent Development Kit — ADK (오픈소스 프레임워크)

Google이 자체 AI 에이전트 구축에 사용하는 프레임워크를 Apache 2.0으로 공개한 것입니다.

핵심 특징:

• SequentialAgent, ParallelAgent, LoopAgent 등 명시적 워크플로 패턴
• 세션 기반 상태 관리 (session.state)
• 사용자/앱/세션/임시 4단계 스코프의 상태 관리
• MCP 도구 통합
• A2A 프로토콜 지원

ADK v1.2.0+ 부터 CLI 단일 명령 배포 지원:

# Agent Engine 배포
adk deploy agent_engine \
  --project <project-id> \
  --region us-central1 \
  --staging_bucket <bucket-name>

# Cloud Run 배포 (Agent Engine 없이)
adk deploy cloud_run \
  --project <project-id> \
  --region us-central1

4.2 Vertex AI Agent Engine (매니지드 런타임)

GCP의 완전 관리형 에이전트 배포 서비스입니다.

주요 기능:

• 자동 스케일링
• 세션 관리 (대화 컨텍스트 유지)
• 메모리 서비스: InMemoryMemoryService (프로토타이핑) / VertexAiMemoryBankService (영속)
• VPC-SC (서비스 경계) 보안
• IAM 기반 접근 제어
• CMEK (고객 관리 암호화 키)
• ADK API 서버 및 웹 UI 제공

Agent Starter Pack(ASP): Terraform/CI/CD 템플릿을 제공하여 새 GCP 프로젝트에서 빠르게 시작할 수 있습니다.

4.3 Lock-in 분석

탈출 전략: adk deploy cloud_run으로 Agent Engine 없이 Cloud Run에 직접 배포. 세션 관리는 Firestore, 메모리는 Cloud SQL + Redis로 직접 구현합니다. GCP 완전 이탈 시 Docker/K8s로 어디든 배포 가능합니다.

5. CSP 매니지드 런타임 기능 상세 비교

5.1 세션 및 메모리

5.2 보안 및 거버넌스

5.3 도구 통합 및 확장

5.4 관측성 및 평가

6. 오픈소스 대안: 런타임 레이어

프레임워크 레벨에서는 ADK(Apache 2.0), Strands(Apache 2.0), Semantic Kernel(MIT) 모두 오픈소스이므로 Lock-in이 없습니다. 진짜 문제는 매니지드 런타임을 오픈소스로 어떻게 대체하느냐입니다.

6.1 LangGraph (MIT) — 프레임워크 + 체크포인팅 + 메모리

LangGraph 프레임워크 자체가 MIT 라이선스로 체크포인팅과 메모리를 내장하고 있습니다.

from langgraph.graph import StateGraph
from langgraph.checkpoint.postgres import PostgresSaver

checkpointer = PostgresSaver.from_conn_string("postgresql://...")

graph = StateGraph(State)
graph.add_node("agent", agent_node)
# ... 그래프 정의

app = graph.compile(checkpointer=checkpointer)

제공 기능:

• Durable execution (장애 자동 복구)
• PostgreSQL 기반 체크포인팅 (langgraph-checkpoint-postgres, MIT)
• 단기/장기 메모리
• Human-in-the-Loop
• 스트리밍

직접 구축해야 하는 것: API 서버(FastAPI), 세션 라우팅, 인증/인가, 스케일링, 모니터링

⚠️ 주의: LangGraph Platform(구 LangSmith Deployments)은 Elastic License 2.0으로, OSI 승인 오픈소스가 아닙니다. 셀프호스팅에는 라이선스 키가 필요하고, Enterprise 계약이 요구됩니다.

6.2 Aegra (Apache 2.0) — LangGraph Platform 드롭인 대체

LangGraph SDK와 API를 그대로 사용하면서 자체 인프라에서 PostgreSQL 영속성과 함께 운영할 수 있는 Apache 2.0 프로젝트입니다.

제공 기능:

• LangGraph SDK 호환 (기존 코드 수정 없이 사용)
• Agent Protocol 스펙 구현
• 체크포인트 포함 내구성 있는 대화 저장
• JWT/OAuth/Firebase 인증
• Docker Compose 5분 배포
• OpenTelemetry 관측성

성숙도: v0.8.x 초기 단계로 대규모 프로덕션 검증 사례가 부족합니다. PoC/평가 용도로 적합합니다.

6.3 Dify (수정 Apache 2.0) — 노코드/로우코드 플랫폼

⚠️ “Apache 2.0”으로 소개되지만 추가 제한 조건이 있습니다:

• 멀티테넌트 서비스 운영 시 별도 상업 라이선스 필요
• 프론트엔드 로고/저작권 정보 제거 불가

제공 기능: 시각적 워크플로 빌더, 빌트인 RAG, 지식 베이스, 100+ LLM 지원, 셀프호스팅

고객사에 멀티테넌트 SaaS로 제공하지 않는다면 사용 가능하지만, 금융권 등 라이선스 심사가 엄격한 환경에서는 주의가 필요합니다.

6.4 Mem0 (Apache 2.0) — 메모리 전용 레이어

에이전트 프레임워크가 아닌 메모리 계층 전용 오픈소스입니다.

• Apache 2.0 라이선스
• 온프레미스/프라이빗 클라우드/K8s 배포
• ADK, LangGraph, Strands 등과 조합하여 장기 메모리 레이어로 활용
• 50,000+ 개발자 사용 중

6.5 오픈소스 조합 전략 비교

7. Lock-in 리스크 종합 매트릭스

7.1 프레임워크 레벨

결론: 프레임워크 레벨에서는 3대 CSP 모두 오픈소스이며, Lock-in 리스크가 낮습니다.

7.2 매니지드 런타임 레벨

7.3 Lock-in 유형별 분석

1. 모델 Lock-in

• AWS: 가장 적음. 7개 이상의 모델 공급자 지원
• Azure: 가장 높음. Azure OpenAI가 중심이며 Claude 미지원
• GCP: 중간. Gemini 최적화이나 Model Garden을 통해 Claude, Llama 등 접근 가능

2. 인프라 Lock-in

• AWS: AgentCore의 microVM 세션 격리 모델은 AWS 고유
• Azure: Entra ID, M365, Copilot Studio 통합은 Azure 고유
• GCP: VPC-SC, CMEK는 GCP 고유이나, Cloud Run 배포로 런타임 Lock-in 회피 가능

3. 데이터/메모리 Lock-in

• 3사 모두: 매니지드 메모리 서비스의 데이터를 다른 플랫폼으로 이식하기 어려움
• 완화 전략: PostgreSQL/Redis 같은 표준 저장소에 메모리를 직접 저장하면 이식성 확보

4. 생태계 Lock-in

• AWS: AWS Lambda, Step Functions, CloudWatch 등과 깊은 통합
• Azure: M365, Teams, Dynamics, Power Platform과의 통합이 강력하지만 탈출 비용도 높음
• GCP: BigQuery, Firestore, Cloud Functions과의 통합

8. 실무 의사결정 프레임워크

8.1 어떤 CSP 런타임을 선택할 것인가

기존 클라우드가 있는가?
├── AWS 사용 중 → Bedrock AgentCore (프레임워크 무관 강점)
├── Azure 사용 중 → AI Foundry Agent Service (M365 통합 강점)
├── GCP 사용 중 → Agent Engine 또는 ADK + Cloud Run
└── 멀티 클라우드 / 없음
    ├── 모델 선택 자유도 우선 → AWS (가장 넓은 모델 선택지)
    ├── 엔터프라이즈 통합 우선 → Azure (M365/Copilot 생태계)
    └── 비용 우선 → GCP (Gemini 기준 가장 저렴)

8.2 오픈소스만으로 구축하고 싶다면

라이선스 리스크 제로가 필요한가?
├── Yes → LangGraph(MIT) + FastAPI + PostgreSQL
│         또는 ADK(Apache 2.0) + Docker/K8s
├── 초기이지만 올인원이 필요 → Aegra(Apache 2.0) 평가
└── No (약간의 제한 허용)
    ├── 노코드 필요 → Dify (수정 Apache 2.0)
    └── 프로덕션 검증 최우선 → LangGraph Platform (Elastic 2.0)

8.3 하이브리드 전략

가장 현실적인 접근은 프레임워크는 오픈소스, 런타임은 CSP입니다.

9. 금융·규제 산업을 위한 추가 고려사항

금융, 의료, 공공 등 규제 산업에서는 추가적인 Lock-in 고려가 필요합니다.

데이터 주권

• AWS: 리전 선택 가능, Data residency 보장
• Azure: 리전 선택 + Data residency + Sovereign Cloud
• GCP: 리전 선택 + VPC-SC + Data Residency 제어

라이선스 감사 대비

완전한 오픈소스만 사용하고 싶다면:
✅ ADK (Apache 2.0)
✅ Strands (Apache 2.0)
✅ Semantic Kernel (MIT)
✅ LangGraph (MIT)
✅ CrewAI (MIT)
✅ Mem0 (Apache 2.0)
✅ PostgreSQL (PostgreSQL License)
✅ Redis (BSD)
✅ FastAPI (MIT)

⚠️ 주의가 필요한 것:
⚠️ LangGraph Platform — Elastic License 2.0 (OSI 미승인)
⚠️ Dify — 수정 Apache 2.0 (멀티테넌트 제한)
⚠️ 각 CSP 매니지드 서비스 — 상용 서비스 약관

탈출 비용 추정

10. 정리

3대 CSP의 공통 전략

1. 프레임워크는 오픈소스로 공개하여 개발자 생태계를 확보
2. 매니지드 런타임에서 차별화하여 수익 창출
3. 타사 프레임워크도 지원하여 런타임 Lock-in 유도

실무 권장

• 프레임워크 선택은 자유롭게: 3사 모두 오픈소스이므로 기술적 적합성으로 선택
• 런타임은 현재 CSP에 맞춰: 기존 클라우드 인프라와의 통합 비용이 전환 비용보다 낮음
• 탈출 전략은 미리 준비: 표준 프로토콜(MCP, A2A, OpenAPI) 활용, 메모리는 PostgreSQL 등 이식 가능한 저장소 사용
• 완전한 오픈소스 구축은 가능하지만 대가가 있음: 세션 관리, 보안, 스케일링, 모니터링을 직접 구현해야 하는 운영 부담

Agent Engine이 제공하는 수준의 “완전 매니지드 + 완전 오픈소스” 조합은 아직 시장에 존재하지 않습니다. 어딘가에서는 직접 구현하거나, 라이선스 제약을 받아들이거나, 또는 클라우드 비용을 지불해야 합니다. 이것이 현재 에이전트 인프라 생태계의 현실입니다.

참고 링크

• Amazon Bedrock AgentCore 공식 문서
• Azure AI Foundry Agent Service
• Vertex AI Agent Engine
• Google ADK 공식 문서
• Strands Agents SDK
• Microsoft Agent Framework
• LangGraph GitHub
• Aegra GitHub
• Mem0 GitHub
• Dify GitHub

특히 기업 환경에서는 개인이 만든 설정을 팀에 공유하고, 검증된 것을 전사 표준으로 승격시키는 계층적 관리 구조가 필수입니다.

이 글에서는 Firestore를 활용하여 Instruction과 Semantic View를 사용자 → 부서 → 글로벌 3단계로 관리하고, 특정 에이전트에 배정하는 구조에 대해서 설명합니다.

가상의 기업 SH은행을 예로 들어 구체적인 설계 방법을 살펴보겠습니다.

1. 왜 계층적 관리가 필요한가

AI Agent 시스템에서 Instruction과 Semantic View를 단순히 1:1로 관리하면 다음과 같은 문제가 발생합니다.

이를 해결하기 위한 핵심 개념이 3단계 계층 구조입니다.

글로벌 (Global)         ← 전사 표준. 관리자가 배포
  ↑ 승격(Promote)
부서 (Department)       ← 팀 내 공유. 팀 리더가 관리
  ↑ 승격(Promote)
사용자 (User)           ← 개인 작업 공간. 자유롭게 실험

2. 관리 대상 정의

설계에 앞서, 이 시스템이 관리하는 두 가지 핵심 리소스를 명확히 정의합니다.

2-1. Instruction (에이전트 지시)

AI Agent에게 전달하는 행동 지침입니다. 시스템 프롬프트, 응답 규칙, 제약 조건 등을 포함합니다.

name: "금융 상담 에이전트 지시"
content: |
  당신은 SH은행의 금융 상담 AI 어시스턴트입니다.
  - 고객 질문에 정확하고 친절하게 답변합니다.
  - 투자 권유는 하지 않습니다.
  - 금리 정보는 반드시 최신 기준으로 안내합니다.
  - 답변 끝에 "추가 문의 사항이 있으시면 말씀해 주세요"를 붙입니다.

2-2. Semantic View (시맨틱 뷰)

데이터를 특정 관점으로 바라보는 가상의 뷰 정의입니다. 에이전트가 데이터에 접근할 때 어떤 테이블을 어떤 관점으로 조회할지를 YAML로 기술합니다.

name: "SV_예금잔액"
description: "일별 전체 예금 잔액 현황"
base_table: "banking.daily_deposit_balance"
columns:
  - name: base_date
    description: "기준일자"
  - name: total_balance
    description: "총 예금잔액 (원)"
filters:
  - "base_date >= CURRENT_DATE - 30"

3. Firestore 컬렉션 설계

Firestore의 특성(문서 기반, 서브컬렉션, 컬렉션 그룹 쿼리, 경로 기반 보안 규칙)을 최대한 활용하는 계층적 컬렉션 구조를 채택합니다.

3-1. 전체 구조

[Firestore]
│
├── instructions/                              ← Instruction 최상위 컬렉션
│   ├── _global/                               ← 글로벌 scope
│   │     └── workspaces/
│   │           └── 표준_상담/
│   │                 └── items/
│   │                       ├── 금융상담_기본
│   │                       └── 리스크_안내
│   │
│   ├── dept:IT팀/                             ← 부서 scope
│   │     └── workspaces/
│   │           └── IT_운영/
│   │                 └── items/
│   │                       └── 장애대응_가이드
│   │
│   └── user:hong@sh-bank.com/                      ← 사용자 scope
│         └── workspaces/
│               ├── 내_실험/
│               │     └── items/
│               │           ├── 테스트_지시_v1
│               │           └── 테스트_지시_v2
│               └── 상담_커스텀/
│                     └── items/
│                           └── VIP_상담_지시
│
├── semantic_views/                            ← Semantic View 최상위 컬렉션
│   ├── _global/
│   │     └── workspaces/
│   │           └── 표준_KPI/
│   │                 └── views/
│   │                       ├── SV_예금잔액
│   │                       └── SV_고객수
│   │
│   ├── dept:IT팀/
│   │     └── workspaces/
│   │           └── IT_대시보드/
│   │                 └── views/
│   │                       └── SV_서버현황
│   │
│   └── user:hong@sh-bank.com/
│         └── workspaces/
│               ├── 예금분석/
│               │     └── views/
│               │           ├── SV_예금잔액
│               │           └── SV_예금추이
│               └── 대출리포트/
│                     └── views/
│                           └── SV_연체현황
│
└── agent_assignments/                         ← 에이전트 배정 컬렉션
      └── {agent_id}/
            └── config
                  ├── instruction_ref: "..."
                  └── semantic_view_refs: [...]

3-2. 경로 패턴

두 리소스 모두 동일한 경로 패턴을 따릅니다.

{resource_type}/{scope}/workspaces/{workspace_id}/{item_collection}/{item_id}

3-3. Scope 문서 ID 규칙

_global은 언더스코어 접두사로 항상 정렬 최상단에 위치합니다. dept:와 user: 접두사로 scope 종류를 경로만 보고 즉시 식별할 수 있습니다.

4. 문서 스키마 설계

4-1. Workspace (워크스페이스) 문서

사용자가 관련 리소스를 논리적으로 묶는 단위입니다.

# instructions/{scope}/workspaces/{workspace_id}
# semantic_views/{scope}/workspaces/{workspace_id}
{
    "name": "예금 분석",
    "description": "예금 관련 시맨틱뷰 모음",
    "owner_id": "hong@sh-bank.com",
    "dept_id": "IT팀",
    "scope": "user",               # "global" | "dept" | "user"
    "tags": ["예금", "분석"],
    "item_count": 3,               # 비정규화: 목록 화면에서 건수 표시용
    "created_at": "2026-03-24T09:00:00Z",
    "updated_at": "2026-03-24T14:30:00Z"
}

4-2. Instruction 문서

# instructions/{scope}/workspaces/{workspace_id}/items/{item_id}
{
    "name": "금융상담 기본 지시",
    "description": "일반 고객 대상 금융 상담 에이전트용 기본 Instruction",
    "content": "당신은 SH은행의 금융 상담 AI 어시스턴트입니다...",
    "content_type": "text",        # "text" | "yaml" | "json"
    "owner_id": "hong@sh-bank.com",
    "workspace_id": "표준_상담",   # 역참조 (collection_group 쿼리용)
    "scope": "global",
    "visibility": "published",     # "draft" | "shared" | "published"
    "promoted_from": "",           # 승격 전 원본 경로
    "assigned_agents": [           # 이 Instruction을 사용 중인 에이전트 목록
        "agent:financial-advisor",
        "agent:loan-consultant"
    ],
    "tags": ["상담", "금융", "기본"],
    "version": 3,
    "created_at": "2026-03-24T09:00:00Z",
    "updated_at": "2026-03-24T14:30:00Z"
}

4-3. Semantic View 문서

# semantic_views/{scope}/workspaces/{workspace_id}/views/{view_id}
{
    "name": "SV_예금잔액",
    "description": "일별 전체 예금 잔액 현황",
    "yaml_string": "base_table: banking.daily_deposit_balance\n...",
    "owner_id": "hong@sh-bank.com",
    "workspace_id": "예금분석",
    "scope": "user",
    "visibility": "draft",
    "promoted_from": "",
    "tags": ["예금", "KPI"],
    "version": 1,
    "created_at": "2026-03-24T09:00:00Z",
    "updated_at": "2026-03-24T14:30:00Z"
}

4-4. Agent Assignment 문서

에이전트에 Instruction과 Semantic View를 배정하는 구조입니다.

# agent_assignments/{agent_id}/config
{
    "agent_id": "financial-advisor",
    "agent_name": "금융 상담 에이전트",
    "instruction_ref": "instructions/_global/workspaces/표준_상담/items/금융상담_기본",
    "semantic_view_refs": [
        "semantic_views/_global/workspaces/표준_KPI/views/SV_예금잔액",
        "semantic_views/dept:IT팀/workspaces/IT_대시보드/views/SV_서버현황"
    ],
    "assigned_by": "hong@sh-bank.com",
    "override_instruction_ref": "",  # 사용자별 오버라이드 (선택)
    "is_active": true,
    "updated_at": "2026-03-24T14:30:00Z"
}

5. 쿼리 패턴

Firestore의 경로 기반 접근과 collection_group 쿼리를 조합하면, 다양한 조회 시나리오를 효율적으로 처리할 수 있습니다.

5-1. 기본 CRUD 쿼리

from google.cloud import firestore

db = firestore.Client()

# ── Instruction 쿼리 ──

# 1) 내 워크스페이스 목록
my_workspaces = db.collection(
    "instructions/user:hong@sh-bank.com/workspaces"
).stream()

# 2) 특정 워크스페이스의 Instruction 목록
my_instructions = db.collection(
    "instructions/user:hong@sh-bank.com/workspaces/내_실험/items"
).stream()

# 3) 글로벌 Instruction 전체
global_instructions = db.collection(
    "instructions/_global/workspaces/표준_상담/items"
).stream()

# 4) 부서 Instruction 전체
dept_instructions = db.collection(
    "instructions/dept:IT팀/workspaces/IT_운영/items"
).stream()

5-2. 컬렉션 그룹 쿼리

collection_group을 사용하면 모든 scope의 같은 이름의 서브컬렉션을 한 번에 검색할 수 있습니다.

# 5) 전체 Instruction 검색 (scope 무관)
all_instructions = db.collection_group("items").stream()

# 6) 전체 Semantic View 검색 (scope 무관)
all_views = db.collection_group("views").stream()

# 7) 특정 태그가 포함된 Instruction 검색
tagged = db.collection_group("items") \
    .where("tags", "array_contains", "상담") \
    .stream()

# 8) 특정 사용자가 만든 모든 Instruction (scope 무관)
user_items = db.collection_group("items") \
    .where("owner_id", "==", "hong@sh-bank.com") \
    .stream()

5-3. 내가 볼 수 있는 모든 리소스 조합

사용자가 접근 가능한 리소스는 글로벌 + 내 부서 + 내 개인 3가지 scope를 병합합니다.

def get_visible_instructions(user_email: str, dept_id: str) -> list:
    """사용자가 접근 가능한 모든 Instruction을 반환"""
    sources = [
        f"instructions/_global/workspaces",
        f"instructions/dept:{dept_id}/workspaces",
        f"instructions/user:{user_email}/workspaces",
    ]

    results = []
    for source in sources:
        workspaces = db.collection(source).stream()
        for ws in workspaces:
            items = db.collection(f"{source}/{ws.id}/items").stream()
            results.extend(items)

    return results


visible = get_visible_instructions("hong@sh-bank.com", "IT팀")

6. 에이전트 배정 구조

이 설계의 핵심 기능 중 하나는 사용자가 자신의 Instruction을 특정 에이전트에 배정하는 것입니다.

6-1. 배정 모델

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│ Instruction │ ──1:N──▶│  Assignment  │◀──N:1── │    Agent    │
└─────────────┘         └─────────────┘         └─────────────┘
                              │
                              │ N:M
                              ▼
                        ┌─────────────┐
                        │Semantic View│
                        └─────────────┘

하나의 에이전트는 하나의 Instruction과 여러 Semantic View를 가질 수 있습니다. 사용자별로 같은 에이전트에 다른 Instruction을 배정할 수 있도록 사용자별 배정 문서를 분리합니다.

6-2. 사용자별 에이전트 배정

agent_assignments/
  └── user:hong@sh-bank.com/                    ← 사용자별 배정
        └── agents/
              ├── financial-advisor/        ← 에이전트별 설정
              │     instruction_ref: "instructions/user:hong@sh-bank.com/..."
              │     semantic_view_refs: [...]
              │     use_global_fallback: true
              │
              └── loan-consultant/
                    instruction_ref: "instructions/dept:IT팀/..."
                    semantic_view_refs: [...]
                    use_global_fallback: false

6-3. Instruction 해석 우선순위

에이전트가 실행될 때, Instruction을 어디서 가져올지 우선순위 체인으로 결정합니다.

1. 사용자별 배정 (user assignment)     ← 최우선
2. 부서별 기본값 (dept default)
3. 글로벌 기본값 (global default)      ← 폴백

def resolve_instruction(agent_id: str, user_email: str, dept_id: str) -> dict:
    """우선순위에 따라 에이전트의 Instruction을 해석"""

    # 1. 사용자별 배정 확인
    user_assignment = db.document(
        f"agent_assignments/user:{user_email}/agents/{agent_id}"
    ).get()

    if user_assignment.exists:
        ref = user_assignment.to_dict().get("instruction_ref")
        if ref:
            doc = db.document(ref).get()
            if doc.exists:
                return doc.to_dict()

    # 2. 부서 기본값 확인
    dept_assignment = db.document(
        f"agent_assignments/dept:{dept_id}/agents/{agent_id}"
    ).get()

    if dept_assignment.exists:
        ref = dept_assignment.to_dict().get("instruction_ref")
        if ref:
            doc = db.document(ref).get()
            if doc.exists:
                return doc.to_dict()

    # 3. 글로벌 기본값
    global_assignment = db.document(
        f"agent_assignments/_global/agents/{agent_id}"
    ).get()

    if global_assignment.exists:
        ref = global_assignment.to_dict().get("instruction_ref")
        if ref:
            doc = db.document(ref).get()
            if doc.exists:
                return doc.to_dict()

    return None

6-4. 배정 API 예시

def assign_instruction_to_agent(
    user_email: str,
    agent_id: str,
    instruction_path: str,
    semantic_view_paths: list[str] = None
):
    """사용자가 자신의 Instruction을 특정 에이전트에 배정"""
    doc_ref = db.document(
        f"agent_assignments/user:{user_email}/agents/{agent_id}"
    )

    data = {
        "agent_id": agent_id,
        "instruction_ref": instruction_path,
        "semantic_view_refs": semantic_view_paths or [],
        "assigned_by": user_email,
        "updated_at": firestore.SERVER_TIMESTAMP,
    }

    doc_ref.set(data, merge=True)


# 사용 예시
assign_instruction_to_agent(
    user_email="hong@sh-bank.com",
    agent_id="financial-advisor",
    instruction_path="instructions/user:hong@sh-bank.com/workspaces/상담_커스텀/items/VIP_상담_지시",
    semantic_view_paths=[
        "semantic_views/_global/workspaces/표준_KPI/views/SV_예금잔액",
        "semantic_views/user:hong@sh-bank.com/workspaces/예금분석/views/SV_예금추이",
    ]
)

7. 승격(Promote) 흐름

개인이 만든 리소스를 부서 또는 글로벌로 승격시키는 워크플로입니다.

7-1. 승격 단계

user:hong@sh-bank.com/workspaces/내_실험/items/VIP_상담_지시
        │
        │  ① 부서 공유 (promote to dept)
        ▼
dept:IT팀/workspaces/공유_지시/items/VIP_상담_지시
        │
        │  ② 글로벌 배포 (promote to global)
        ▼
_global/workspaces/표준_상담/items/VIP_상담_지시

7-2. 승격 구현

def promote_instruction(
    source_path: str,
    target_scope: str,
    target_workspace: str,
    promoted_by: str
):
    """Instruction을 상위 scope로 승격(복사)"""
    source_doc = db.document(source_path).get()
    if not source_doc.exists:
        raise ValueError(f"소스 문서를 찾을 수 없습니다: {source_path}")

    data = source_doc.to_dict()
    item_id = source_path.split("/")[-1]

    target_path = f"instructions/{target_scope}/workspaces/{target_workspace}/items/{item_id}"

    data.update({
        "promoted_from": source_path,
        "promoted_by": promoted_by,
        "scope": "global" if target_scope == "_global" else "dept",
        "visibility": "published",
        "promoted_at": firestore.SERVER_TIMESTAMP,
    })

    db.document(target_path).set(data)

    # 원본에 승격 이력 기록
    db.document(source_path).update({
        "promoted_to": target_path,
        "promoted_at": firestore.SERVER_TIMESTAMP,
    })

    return target_path


# 사용 예시: 개인 → 부서로 승격
promote_instruction(
    source_path="instructions/user:hong@sh-bank.com/workspaces/내_실험/items/VIP_상담_지시",
    target_scope="dept:IT팀",
    target_workspace="공유_지시",
    promoted_by="hong@sh-bank.com"
)

8. Firestore 보안 규칙

경로 기반 구조의 장점은 보안 규칙을 간결하게 작성할 수 있다는 것입니다.

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {

    // Instruction 보안 규칙
    match /instructions/{scope}/workspaces/{wsId}/items/{itemId} {

      // 글로벌: 누구나 읽기 가능, 관리자만 쓰기
      allow read: if scope == '_global';
      allow write: if scope == '_global'
                   && request.auth.token.role == 'admin';

      // 부서: 같은 부서원만 읽기, 팀 리더만 쓰기
      allow read: if scope.matches('dept:.*')
                  && request.auth.token.dept_id == scope.split(':')[1];
      allow write: if scope.matches('dept:.*')
                   && request.auth.token.dept_id == scope.split(':')[1]
                   && request.auth.token.is_team_lead == true;

      // 사용자: 본인만 읽기/쓰기
      allow read, write: if scope.matches('user:.*')
                         && request.auth.token.email == scope.split(':')[1];
    }

    // Semantic View도 동일한 패턴 적용
    match /semantic_views/{scope}/workspaces/{wsId}/views/{viewId} {
      allow read: if scope == '_global';
      allow write: if scope == '_global'
                   && request.auth.token.role == 'admin';

      allow read: if scope.matches('dept:.*')
                  && request.auth.token.dept_id == scope.split(':')[1];
      allow write: if scope.matches('dept:.*')
                   && request.auth.token.dept_id == scope.split(':')[1]
                   && request.auth.token.is_team_lead == true;

      allow read, write: if scope.matches('user:.*')
                         && request.auth.token.email == scope.split(':')[1];
    }

    // 에이전트 배정: 본인 배정만 수정 가능
    match /agent_assignments/user:{userEmail}/agents/{agentId} {
      allow read, write: if request.auth.token.email == userEmail;
    }
    match /agent_assignments/dept:{deptId}/agents/{agentId} {
      allow read: if request.auth.token.dept_id == deptId;
      allow write: if request.auth.token.dept_id == deptId
                   && request.auth.token.is_team_lead == true;
    }
    match /agent_assignments/_global/agents/{agentId} {
      allow read: if true;
      allow write: if request.auth.token.role == 'admin';
    }
  }
}

경로 자체에 scope 정보가 담겨 있으므로, 문서 내부 필드를 검사하는 복잡한 조건 없이도 접근 제어가 가능합니다.

9. 전체 워크플로 시나리오

실제 사용 흐름을 시나리오로 정리합니다.

시나리오: 홍길동이 Instruction을 만들어 에이전트에 배정하는 전체 과정

[1단계] 개인 워크스페이스 생성
  └─ POST instructions/user:hong@sh-bank.com/workspaces/상담_커스텀

[2단계] Instruction 작성
  └─ POST .../상담_커스텀/items/VIP_상담_지시
     { content: "VIP 고객 전용 상담 시 존칭 사용..." }

[3단계] 에이전트에 배정
  └─ PUT agent_assignments/user:hong@sh-bank.com/agents/financial-advisor
     { instruction_ref: ".../VIP_상담_지시",
       semantic_view_refs: [".../SV_예금잔액"] }

[4단계] 에이전트 실행 시 Instruction 해석
  └─ resolve_instruction("financial-advisor", "hong@sh-bank.com", "IT팀")
     → 사용자 배정 확인 → VIP_상담_지시 반환

[5단계] 팀에 공유 (승격)
  └─ promote("VIP_상담_지시", "dept:IT팀", "공유_지시")
     → IT팀 전원이 사용 가능

[6단계] 전사 표준 배포 (승격)
  └─ promote("VIP_상담_지시", "_global", "표준_상담")
     → 전사 에이전트 기본 Instruction으로 사용 가능

UI 네비게이션 구조

┌─ 리소스 선택 ──────────────────────────────────┐
│  [📋 Instructions]    [📊 Semantic Views]       │
├─ Scope 선택 ───────────────────────────────────┤
│  [👤 내 뷰]    [👥 IT팀]    [🌐 글로벌]        │
├─ Workspace 선택 ───────────────────────────────┤
│  📁 상담_커스텀 (2)                              │
│  📁 내_실험 (3)                                  │
├─ Items ────────────────────────────────────────┤
│  ◆ VIP_상담_지시          [에이전트 배정 ▶]     │
│  ◆ 테스트_지시_v1                               │
├─ 에이전트 배정 ────────────────────────────────┤
│  🤖 financial-advisor                           │
│     Instruction: VIP_상담_지시 ✅               │
│     Views: SV_예금잔액, SV_예금추이              │
│  🤖 loan-consultant                             │
│     Instruction: (글로벌 기본값)                 │
│     Views: SV_대출잔액                           │
└────────────────────────────────────────────────┘

10. 인덱스 설계

Firestore에서 collection_group 쿼리를 사용하려면 복합 인덱스를 사전에 생성해야 합니다.

// firestore.indexes.json
{
  "indexes": [
    {
      "collectionGroup": "items",
      "queryScope": "COLLECTION_GROUP",
      "fields": [
        { "fieldPath": "owner_id", "order": "ASCENDING" },
        { "fieldPath": "updated_at", "order": "DESCENDING" }
      ]
    },
    {
      "collectionGroup": "views",
      "queryScope": "COLLECTION_GROUP",
      "fields": [
        { "fieldPath": "owner_id", "order": "ASCENDING" },
        { "fieldPath": "updated_at", "order": "DESCENDING" }
      ]
    }
  ]
}

11. 설계 판단 요약

단일 컬렉션 vs 계층 컬렉션

Instruction 참조 방식: 복사 vs 참조

이 설계에서는 에이전트 배정은 참조, 승격은 복사 방식을 혼합합니다. 에이전트가 실행 시점에 항상 최신 Instruction을 사용하되, 승격된 리소스는 독립적으로 관리되어 원본 변경에 영향받지 않도록 합니다.

정리

Firestore의 계층적 컬렉션 구조를 활용하면, AI Agent의 Instruction과 Semantic View를 사용자 → 부서 → 글로벌 3단계로 자연스럽게 관리할 수 있습니다.

핵심 설계 원칙을 다시 정리하면 다음과 같습니다.

이 구조는 Firestore의 100단계 중첩 제한 내에서 충분히 동작하며(최대 6단계), 보안 규칙도 경로 패턴만으로 간결하게 작성할 수 있어 운영 부담을 최소화합니다.

이 글에서는 네트워크 경로를 확인하는 방법, 서비스 유형별 네트워킹 구조, 그리고 Private Service Connect(PSC) 구성까지 실전 관점에서 정리합니다.

1. 내부망인지 확인하는 2가지 방법

1-1. DNS 해석 결과로 판별 (가장 간편)

GCE 인스턴스에서 BigQuery API 엔드포인트의 DNS resolve 결과를 보면 힌트를 얻을 수 있습니다.

# 방법 A: dig로 확인
dig bigquery.googleapis.com

# 방법 B: Python으로 확인
python3 -c "import socket; print(socket.getaddrinfo('bigquery.googleapis.com', 443))"

실제 테스트 결과 예시:

;; ANSWER SECTION:
bigquery.googleapis.com. 300    IN      A       34.128.10.106

[(<AddressFamily.AF_INET: 2>, <SocketKind.SOCK_STREAM: 1>, 6, '', ('34.128.10.106', 443)),
 (<AddressFamily.AF_INET6: 10>, <SocketKind.SOCK_STREAM: 1>, 6, '', ('2600:1900:4250:d::200a', 443, 0, 0)),
 ...]

판별 기준:

위 테스트 결과에서는 34.128.10.106과 2600:1900:4250:d::200a가 나왔는데, 이는 Google 공인 IP 대역입니다. restricted도 private도 아닙니다. 즉 별도의 Private Service Connect나 restricted/private DNS 존 설정이 되어 있지 않다는 뜻입니다.

1-2. VPC Flow Logs로 확인 (가장 확실)

VPC Flow Logs를 켜면 실제 트래픽의 목적지 IP를 볼 수 있습니다.

# GCE에서 BigQuery API 엔드포인트의 IP 확인
nslookup bigquery.googleapis.com

# Private Google Access가 활성화된 서브넷에서는
# restricted.googleapis.com (199.36.153.4/30) 또는
# private.googleapis.com (199.36.153.8/30) 대역으로 resolve 됨

# 반면 외부 인터넷 경유 시에는 공인 IP로 resolve 됨

VPC Flow Logs에서 destination IP가 위의 private 대역이면 내부망을 사용하는 것이 확실합니다.

2. 공인 IP로 resolve 되면 무조건 외부망인가?

아닙니다. 이 부분이 가장 혼동을 주는 포인트입니다.

GCP 공식 문서에 명확한 근거가 있습니다:

“Packets sent from VMs in your VPC network to Google APIs and services remain within Google’s network.” — Private Google Access 공식 문서

“Requests from one Cloud Run resource to another or to other Google Cloud services stay within Google’s internal network.” — Cloud Run Private Networking 공식 문서

즉, IP 주소가 공개 라우팅 가능(publicly routable)하더라도, 실제 패킷은 Google 내부 네트워크 안에서만 이동합니다. 인터넷 공중망을 경유하지 않습니다.

경우를 나눠보면:

따라서 DNS resolve IP만으로 단정할 수 없고, 인스턴스의 구성을 함께 확인해야 합니다.

# 1) 해당 인스턴스에 외부 IP가 있는지
curl -s -H "Metadata-Flavor: Google" \
  http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip

# 2) 서브넷에 Private Google Access가 켜져 있는지
gcloud compute networks subnets describe <SUBNET_NAME> \
  --region=<REGION> \
  --format="get(privateIpGoogleAccess)"

# 3) private/restricted DNS 존이 구성되어 있는지
gcloud dns managed-zones list --filter="visibility=private"

구성별 비교 — 감사(audit) 증명 가능 여부

“인터넷을 경유하지 않는다”는 사실은 구성 수준에 따라 증명 가능성이 달라집니다.

기본 설정에서도 인터넷을 경유하지 않지만, IP 주소가 공개 라우팅 가능하다는 점 때문에 금융권 등 규제 환경에서는 설명이 어렵습니다. PSC 엔드포인트를 사용하면 DNS도 내부 해석(*.googleapis.com → 내부 IP)으로 완전히 격리되어, 기술적으로 증명할 수 있습니다.

3. BigQuery 통신 보안 채널 분석

네트워크 경로와 별개로, 통신 채널 자체의 보안도 중요합니다. BigQuery API 통신은 TLS와 ALTS 이중 보호 구조로 되어 있습니다.

통신 경로별 보안 메커니즘

ALTS (Application Layer Transport Security)

Google 인프라 내부에서 서비스 간 통신을 보호하는 핵심 기술입니다.

• GFE → BigQuery, Cloud Run 백엔드 → BigQuery 모두 ALTS로 보호
• 서비스별 Google internal CA 발급 credential로 상호 인증(mutual auth)
• 암호화: AES-128-GCM (기본), 스토리지 레이어는 AES-256
• Handshake: Elliptic Curve + ML-KEM (양자 내성, FIPS 203)
• BoringSSL 또는 PSP로 구현, FIPS 140-2/3 Level 1 검증

BigQuery API 자체의 보안

• REST API: HTTPS 강제 (http:// 요청 시 “SSL is required” 오류 반환)
• Storage Read/Write API: gRPC + TLS, ALTS 캡슐화
• bigquery.googleapis.com 엔드포인트는 GFE를 통해 TLS 종료 후 ALTS로 내부 전달

참고: Encryption in transit for Google Cloud, Google infrastructure security design overview

4. Private Google Access(PGA) 설정

Private Google Access는 서브넷 단위로 설정합니다.

Console에서 켜기

VPC network → VPC networks → 해당 VPC 선택 → Subnets 탭 → 서브넷 클릭 → Edit → Private Google Access를 On으로 변경 → Save

gcloud CLI로 켜기

gcloud compute networks subnets update <SUBNET_NAME> \
  --region=<REGION> \
  --enable-private-ip-google-access

현재 상태 확인

gcloud compute networks subnets describe <SUBNET_NAME> \
  --region=<REGION> \
  --format="get(privateIpGoogleAccess)"
# True가 나오면 이미 켜져 있음

PGA가 의미를 갖는 건 외부 IP가 없는 GCE 인스턴스일 때입니다. 외부 IP가 있는 인스턴스는 이 설정과 무관하게 이미 Google API에 접근 가능합니다. PGA는 외부 IP 없이 내부 전용으로 운영하는 인스턴스가 googleapis.com 서비스에 접근할 수 있게 해주는 역할입니다.

5. 서비스 유형별 네트워킹 구조

5-1. GCE (Google Compute Engine)

가장 직관적입니다. 사용자 VPC 안에서 실행되므로, 서브넷의 PGA 설정과 외부 IP 유무에 따라 네트워크 경로가 결정됩니다.

GCE 인스턴스 → 서브넷(PGA ON/OFF) → BigQuery API
                  ↓
         외부 IP 없으면 PGA 필요
         외부 IP 있으면 PGA 무관

내부망 경로를 명시적으로 강제하고 싶다면, Cloud DNS에서 googleapis.com을 restricted.googleapis.com(199.36.153.4/30) 또는 private.googleapis.com(199.36.153.8/30)으로 매핑하는 프라이빗 DNS 존을 생성합니다.

5-2. Cloud Run

Cloud Run은 기본적으로 Google 관리형 인프라에서 실행됩니다. BigQuery 등 Google API 호출 시 Google 내부 네트워크를 통해 처리됩니다.

사용자 VPC 내 리소스에 접근하려면 VPC 커넥터(Serverless VPC Access) 또는 Direct VPC Egress를 설정해야 합니다.

VPC 커넥터를 사용하는 경우 VPC Flow Logs로 트래픽을 확인할 수 있으며, 서브넷의 PGA 설정이 적용됩니다.

5-3. Vertex AI Agent Engine

Agent Engine은 GCE처럼 사용자 VPC 안에서 돌아가는 게 아닙니다. Google의 tenant project에서 실행되기 때문에 사용자가 서브넷을 직접 제어할 수 없습니다.

그래서 “PGA를 켜야 하나?”라는 질문 자체가 적용되지 않습니다.

Agent Engine에는 3가지 네트워킹 모드가 있습니다:

각 모드에서 BigQuery를 호출할 때의 보안 수준: