기업급 오케스트레이션 (Orchestration) 인프라를 갖춘 ADK/Vertex 컴플라이언스 (Compliance) 부서.

Bob's Brain은 Google의 Agent Development Kit (ADK) 및 Vertex AI Agent Engine을 기반으로 구축된 ADK 및 Vertex AI 컴플라이언스 작업을 위한 프로덕션급 멀티 에이전트 시스템 (Multi-agent system)입니다. 기업용 제어 기능 (R0-R4 리스크 티어, 정책 게이트, 증거 번들), 표준 에이전트 ID (Canonical agent IDs), A2A 프로토콜, 그리고 Mission Spec v1 워크플로우-코드-형식 (Workflow-as-code)을 특징으로 합니다. 이 프레임워크 인프라는 범용적이며 어떤 도메인에서도 구동될 수 있습니다.

빠른 시작 (Quick Start) • 기능 소개 (What It Does) • 하드 모드 규칙 (Hard Mode Rules) • 템플릿으로 사용하기 (Use as Template)

Bob's Brain은 ADK 표준 준수, 코드 품질 및 문서화를 위해 전문 AI 에이전트들을 조율하는 ADK/Vertex 컴플라이언스 부서입니다. Google의 ADK 및 Vertex AI Agent Engine을 기반으로 구축되었으며, 모든 도메인별 에이전트 부서를 구동할 수 있는 기업급 인프라 (리스크 티어, 정책 게이트, 증거 번들, 워크플로우-코드-형식)를 갖추고 있습니다.

주요 기능:

기업용 제어 (Enterprise Controls): 리스크 티어 (R0-R4), 정책 게이트 (Policy gates), 도구 허용 목록 (Tool allowlists)
감사 추적 (Audit Trails): 매니페스트(Manifest) + 해싱(Hashing)이 포함된 증거 번들 (Evidence bundles)
워크플로우-코드-형식 (Workflow-as-Code): Mission Spec v1 선언적 YAML
멀티 에이전트 오케스트레이션 (Multi-Agent Orchestration): Foreman → 전문가 위임 (Specialist delegation)

Bob은 여러 전문 부서를 조율하는 **글로벌 오케스트레이터 (Global orchestrator)**입니다. 이 저장소(Repo)에는 ADK/Vertex 컴플라이언스에만 집중하는 Bob의 첫 번째 전문 팀인 iam- department (Intent Agent Model)가 포함되어 있습니다:

┌─────────────────────────────────────────────────────────┐
│ Bob (Global Orchestrator) │
│ • Slack 인터페이스 │
...

이 저장소는 Bob의 전체 두뇌가 아니라, Bob의 첫 번째 전문 부서입니다.

Google ADK 및 Vertex AI를 사용하여 구축할 때는 엄격한 아키텍처 패턴이 필요합니다. 대부분의 팀은 시간이 지나면서 다음과 같은 오류를 범합니다:

• ❌ LangChain을 ADK 코드와 혼용
• ❌ Agent Engine을 사용하는 대신 러너(Runners)를 셀프 호스팅
• ❌ 위키(Wikis)와 무작위 파일에 문서를 분산 배치
• ❌ 메모리 배선(Memory wiring)을 건너뛰거나 잘못 수행
• ❌ Google의 권장 패턴 위반

이 팀은 그러한 드리프트(Drift)를 방지합니다. 리포지토리를 감사하고, 위반 사항을 감지하며, 수정 방안을 구축하여 사용자가 Google의 ADK/Vertex 표준을 준수하도록 유지합니다.

우리는 일반적인 에이전트의 혼란을 방지하기 위해 8가지 아키텍처 규칙(R1-R8)을 강제합니다:

• ✅ ADK 전용 (ADK-only) - LangChain, CrewAI 또는 기타 프레임워크를 혼용하지 않음
• ✅ 관리형 런타임 (Managed runtime) - 자체 호스팅 컨테이너가 아닌 Vertex AI Agent Engine 사용
• ✅ CI 강제 (CI-enforced) - 자동화된 체크를 통해 잘못된 패턴이 머지(Merge)되기 전에 차단
• ✅ 작동하는 메모리 (Memory that works) - 진정한 연속성을 위한 이중 세션(Dual Session) + 메모리 뱅크(Memory Bank)
• ✅ 깔끔한 분리 (Clean separation) - 에이전트가 내장된 프랭큰 서버(Franken-servers)가 아닌 Cloud Run 프록시 사용
• ✅ 단일 문서 폴더 (One docs folder) - 흩어진 README 파일 없이 모든 문서를 000-docs/에 보관
• ✅ 불변의 ID (Immutable identity) - 깔끔한 추적을 위해 모든 곳에 SPIFFE ID 사용
• ✅ 드리프트 감지 (Drift detection) - 금지된 임포트(Import)를 몰래 포함하려 할 경우 CI 실패

요약(Tl;dr): 강제된 아키텍처 표준과 컴플라이언스 자동화를 갖춘 프로덕션급 멀티 에이전트 시스템.

iam- 부서는 오직 다음 사항에 집중하는 전문 팀입니다:

Google Vertex/ADK 디자인 시스템 컴플라이언스(Compliance):

🔍 ADK/Vertex 컴플라이언스 감사 (Compliance Audits)

• 리포지토리를 스캔하여 ADK 임포트 위반 사항 감지 (LangChain, CrewAI 혼용 금지)
• Google의 권장 Agent Engine 패턴으로부터의 드리프트 감지
• 메모리 배선(Memory wiring, Session + Memory Bank) 검증
• A2A 프로토콜 구현 확인
• SPIFFE ID 전파(Propagation) 보장
• 게이트웨이 분리 확인 (Cloud Run 내에 Runner를 두지 않음)

🛠️ 자동화된 ADK/Vertex 수정 (Automated ADK/Vertex Fixes)

• ADK 패턴 위반에 대한 수정 계획 구축
• Vertex AI 권장 아키텍처에 맞추기 위한 PR(Pull Request) 생성
• Google의 ADK 패턴을 따르도록 코드 리팩터링(Refactoring)
• ADK/Vertex 표준에 따른 QA 체크 실행

📋 포트폴리오 전반의 ADK 컴플라이언스 (Portfolio-Wide ADK Compliance)

• 여러 리포지토리에 대해 ADK/Vertex 컴플라이언스를 동시에 감사
• 조직 전체의 ADK 패턴 위반 사항 집계
• 컴플라이언스 점수 및 수정률 추적
• 감사 결과를 중앙 집중식 GCS 버킷에 저장

📝 ADK/Vertex 문서화 (ADK/Vertex Documentation)

• 모든 ADK 패턴 수정에 대한 AAR (After Action Reports) 작성
• Vertex AI 정렬(alignment)을 보여주는 아키텍처 문서 생성
• ADK 전용 패턴 및 결정 사항 문서화
• ADK/Vertex 패턴에 대한 검색 가능한 지식 유지

💬 Slack 연동 (Slack Integration)

• ADK/Vertex 패턴에 관한 질문에 답변
• ADK 컴플라이언스(compliance) 실패에 대한 알림 전송
• 팀들이 Google의 권장 아키텍처를 이해하도록 지원

이 부서는 8명의 전문 에이전트(specialist agents)로 구성되어 있으며, 각 에이전트는 ADK/Vertex 컴플라이언스의 특정 측면에 집중합니다:

┌─────────────┐
│ Bob │ ← 글로벌 오케스트레이터 (ADK/Vertex 요청을 이곳으로 라우팅)
└──────┬──────┘
...

중요: 이 팀은 오직 ADK/Vertex 컴플라이언스 작업만 처리합니다. 일반적인 소프트웨어 엔지니어링, 데이터 파이프라인, 보안 감사 등은 Bob의 다른 부서(출시 예정)에서 처리합니다.

최종 사용자용 (Slack):

Slack 내 사용자
↓
Slack 웹훅 (Cloud Run)
...

포트폴리오 감사용 (CLI):

python3 scripts/run_portfolio_swe.py
↓
포트폴리오 오케스트레이터 (Portfolio Orchestrator)
...

bobs-brain/
├── agents/
│ ├── bob/ # 메인 에이전트 (LlmAgent + 도구)
...

핵심 원칙: Cloud Run 서비스는 프록시(proxy) 역할만 수행합니다. 이들은 REST를 통해 Agent Engine으로 요청을 전달합니다. 게이트웨이(gateway)에서는 Runner 임포트(import)가 허용되지 않습니다.

"하드 모드(Hard Mode)"란 시스템이 확장됨에 따라 이 에이전트 시스템을 유지 관리 가능한 상태로 유지하기 위해 엄격한 규칙을 강제함을 의미합니다. 이 리포지토리는 **ADK/Agent Engine 사양 (ADK/Agent Engine Specification)**을 가이드 아키텍처 표준으로 따릅니다. 그 내용은 다음과 같습니다:

모든 규칙은 CI(지속적 통합)에서 강제됩니다. 위반 시 빌드가 자동으로 실패합니다.

• ✅ google-adk의 LlmAgent 사용
• ❌ LangChain, CrewAI, AutoGen 또는 커스텀 프레임워크 사용 금지

이유: 프레임워크를 혼용하면 통합 과정에서 악몽 같은 상황이 발생합니다. 하나를 선택하고 그것을 고수하십시오.

• ✅ Vertex AI Agent Engine에 배포
• ❌ 자체 호스팅 러너(self-hosted runners) 또는 Runner가 내장된 Cloud Run 사용 금지

이유: 런타임 관리는 Google에 맡기십시오. 인프라가 아닌 에이전트 로직에 집중하십시오.

• ✅ Agent Engine으로 향하는 HTTP 프록시로서의 Cloud Run 사용
• ❌ 게이트웨이 코드 내 Runner 임포트 금지

이유: 깔끔한 분리는 에이전트(Agent)에 영향을 주지 않고도 게이트웨이(Gateway)를 재시작할 수 있음을 의미합니다.

• ✅ GitHub Actions + Workload Identity Federation을 통한 모든 배포
• ❌ 수동 gcloud deploy 또는 서비스 계정 키(Service account keys) 사용 금지

이유: 재현 가능한 배포. "내 컴퓨터에서는 되는데"라는 변명 방지.

• ✅ VertexAiSessionService + VertexAiMemoryBankService
• ✅ 세션을 유지하기 위한 after_agent_callback 사용

이유: 단순한 임베딩(Embedding) 저장이 아닌, 실제 대화의 연속성 보장.

• ✅ 모든 문서는 000-docs/ 내에 NNN-CC-ABCD-name.md 형식으로 작성
• ❌ 흩어진 문서, 여러 개의 문서 폴더 또는 무작위 README 금지

이유: 예측 가능한 구조. 찾기 쉽고, 새로운 리포지토리(Repo)로 복사하기 쉬움.

• ✅ spiffe://intent.solutions/agent/bobs-brain/<env>/<region>/<version>
• ✅ AgentCard, 로그, HTTP 헤더에 전파

이유: 불변의 식별자(Immutable identity)는 추적(Tracing)과 보안 감사(Security audits)를 단순하게 만듭니다.

• ✅ CI에서 가장 먼저 실행되는 scripts/ci/check_nodrift.sh
• ❌ 대안 프레임워크, 게이트웨이 내의 Runner, 로컬 자격 증명(Local creds) 차단

이유: 코드가 커밋되기 전에 아키텍처의 변질(Architectural decay)을 방지합니다.

드리프트 체크 스크립트(scripts/ci/check_nodrift.sh)는 CI에서 다른 무엇보다 먼저 실행됩니다:

# .github/workflows/ci.yml
jobs:
drift-check:
...

만약 드리프트 체크가 실패하면 전체 파이프라인이 중단됩니다. 테스트도 실행되지 않고 배포도 이루어지지 않습니다. 위반 사항을 먼저 수정하십시오.

• Python 3.12+
• Vertex AI가 활성화된 Google Cloud 계정
• (선택 사항) 통합을 위한 Slack 워크스페이스
• (선택 사항) CI/CD를 위한 GitHub 계정

# 코드 가져오기
git clone https://github.com/intent-solutions-io/bobs-brain.git
cd bobs-brain
...

# 모든 임포트(Import)가 유효한지 확인
python3 -c "
from google.adk.agents import LlmAgent
...

옵션 A: GitHub Actions를 통한 방식 (권장)

# main 브랜치로 푸시하면 자동 배포가 트리거됩니다
git add .
git commit -m "feat: 기능 설명"
...

옵션 B: 수동 방식 (로컬 테스트 전용)

# 이는 로컬 개발 전용입니다
# 프로덕션 배포는 반드시 CI를 거쳐야 합니다
cd agents/bob
...

# 모든 로컬 리포지토리(repos) 감사
python3 scripts/run_portfolio_swe.py
# 특정 리포지토리만 감사
...

이것으로 끝입니다. 이제 코드를 감사하고, 문제를 수정하며, 문서를 생성할 수 있는 작동 가능한 AI 에이전트(AI agent)를 갖추게 되었습니다.

Bob의 초능력 중 하나는 여러 리포지토리를 동시에 감사하고 조직 전체의 지표(metrics)를 제공하는 것입니다.

• config/repos.yaml에서 리포지토리를 정의하세요:

repos:
- id: bobs-brain
  display_name: "Bob's Brain"
  ...

• 포트폴리오 오케스트레이터(portfolio orchestrator)를 실행하세요:

python3 scripts/run_portfolio_swe.py

• 집계된 결과를 확인하세요:

{
"portfolio_run_id": "c98cc8f2-...",
"timestamp": "2025-11-20T03:52:34Z",
...
}

# 기본 사용법
python3 scripts/run_portfolio_swe.py
# 특정 리포지토리만 대상
...

포트폴리오 감사(portfolio audit)는 GitHub Actions를 통해 매일 밤 실행됩니다:

# 수동 트리거
gh workflow run portfolio-swe.yml \
--ref main \
...

주요 기능:

• ✅ 멀티 리포지토리 (Multi-repo) ARV 체크
• ✅ 자동 감사 (매일 밤 UTC 기준 오전 2시)
• ✅ JSON/Markdown 내보내기
• ✅ 이력 결과 저장을 위한 GCS 스토리지 (v2.1.5+)
• 📐 Slack 알림 (출시 예정)
• 📐 GitHub 이슈 생성 (출시 예정)

로드맵 (Roadmap):

LIVE1-GCS (v2.1.5): ✅ 완료 - GCS 조직 전체 스토리지
LIVE-BQ (향후 예정): BigQuery 분석 통합
LIVE2 (계획됨): Vertex AI Search RAG + Agent Engine 호출 (개발 전용)
LIVE3 (계획됨): Slack 알림 + GitHub 이슈 생성

v2.1.5 신규 기능 - 모든 포트폴리오 감사 결과가 쿼리 및 분석이 용이하도록 한 곳에 저장됩니다.

중앙 집중식 GCS 버킷 (Centralized GCS bucket) - 모든 감사 결과 저장용
수명 주기 관리 (Lifecycle management) - 리포지토리별 상세 정보에 대해 90일 보관
안정적인 폴백 (Graceful fallback) - 쓰기 작업이 파이프라인을 중단시키지 않음
환경 인식 (Environment-aware) - 개발(dev)/스테이징(staging)/운영(prod) 환경별 별도 버킷 사용

gs://intent-org-knowledge-hub-{env}/
├── portfolio/runs/{run_id}/summary.json # 포트폴리오 레벨 요약
├── portfolio/runs/{run_id}/per-repo/*.json # 리포지토리별 상세 정보
...

1. Terraform에서 활성화:

# infra/terraform/envs/dev.tfvars
org_storage_enabled = true
org_storage_bucket_name = "intent-org-knowledge-hub-dev"

2. 준비 상태 확인 (Check readiness):

python3 scripts/check_org_storage_readiness.py
python3 scripts/check_org_storage_readiness.py --write-test

3. 쓰기 활성화 (Enable writes):

export ORG_STORAGE_WRITE_ENABLED=true
export ORG_STORAGE_BUCKET=intent-org-knowledge-hub-dev

4. 감사 실행 (Run audit):

python3 scripts/run_portfolio_swe.py
# 결과가 GCS에 자동으로 기록됩니다

• ✅
  기본적으로 옵트인 (Opt-in by default)- 명시적으로 활성화하지 않는 한 아무것도 기록되지 않습니다 - ✅
  우아한 오류 처리 (Graceful errors)- GCS 실패 시 파이프라인은 계속 진행됩니다 (오류 로그만 남김) - ✅
  완전한 테스트 완료 (Fully tested)- 100% 통과율의 36개 테스트 - ✅
  IAM 보안 적용 (IAM-secured)- 서비스 계정 (Service account) 기반 액세스 제어

문서 (Documentation):

Bob's Brain은 단순한 제품이 아닙니다. 여러분의 자체 리포지토리(repos)로 복사할 수 있는 **완전한 멀티 에이전트 템플릿 (complete multi-agent template)**입니다.

Bob's Brain을 여러분의 제품(DiagnosticPro, PipelinePilot 등)으로 이식할 때:

• ✅
  멀티 에이전트 아키텍처 (Multi-agent architecture)- bob → foreman → iam-* 전문가 - ✅
  SWE 파이프라인 (SWE pipeline)- 감사(audit) → 이슈(issues) → 수정(fixes) → QA → 문서(docs) - ✅
  공유 계약 (Shared contracts)- 모든 에이전트 상호작용을 위한 JSON 스키마 (JSON schemas) - ✅
  A2A 통신 (A2A communication)- 에이전트 간 (Agent-to-Agent) 프로토콜 배선 - ✅
  ARV 체크 (ARV checks)- CI를 위한 에이전트 준비 상태 검증 (Agent Readiness Verification) - ✅
  게이트웨이 서비스 (Gateway services)- A2A 및 Slack 엔드포인트 - ✅
  Terraform 인프라 (Terraform infrastructure)- 에이전트 엔진 (Agent Engine), Cloud Run, IAM - ✅
  CI/CD 워크플로 (CI/CD workflows)- 드리프트 체크 (Drift check), 테스트, 배포 - ✅
  문서화 시스템 (Documentation system)- v4.3 분류 표준을 따르는 000-docs/ - ✅

기본 설정: 1-2일
전체 통합: 1주일
운영 환경 준비 완료 (Production-ready): 2주일 (적절한 테스트 포함)

여기서 시작하세요:

• 이식 가이드 (Porting Guide) - 단계별 지침
• 통합 체크리스트 (Integration Checklist) - 놓치는 것이 없도록 확인
• 템플릿 범위 (Template Scope) - 커스텀할 항목
• 템플릿 파일 (Template Files) - 재사용 가능한 컴포넌트

Bob's Brain은 다음을 기반으로 구축되었습니다:

이것이 기초가 되는 하드 모드 (Hard Mode) 아키텍처입니다. Bob은 이를 확장하여 완전한 멀티 에이전트 부서로 만듭니다.

Bob은 전체 CI/CD 자동화와 함께 ADK CLI를 사용하여 Vertex AI Agent Engine에 배포됩니다.

GitHub Actions (WIF)
↓
ADK CLI (adk deploy agent_engine)
...

배포하기 전에:

배포하기 전에:

• ✅ Vertex AI가 활성화된 GCP 프로젝트 (GCP project with Vertex AI enabled)
• ✅ 구성된 GitHub secrets (WIF provider, service account)
• ✅ 적용된 Terraform 인프라 (infra/terraform/)
• ✅ 생성된 Staging bucket (gs://<project-id>-adk-staging)

# main 브랜치로 push하면 자동 배포가 트리거됩니다
git push origin main
# GitHub Actions가 자동으로 수행합니다:
...

모든 인프라(Slack gateway 포함)는 오직 Terraform을 통해서만 배포됩니다:

# ⚠️ Slack Bob을 위해 절대로 수동 gcloud 명령어를 사용하지 마세요
# ❌ 잘못된 방법: gcloud run services update slack-webhook ...
# ✅ 올바른 방법: Terraform + GitHub Actions 사용
...

**로컬 Terraform 테스트 (검증 전용):