ADK 에이전트 스킬 패턴: 구글의 프로그레시브 디스클로저 완전 가이드

왜 모놀리식 프롬프트는 한계가 있을까요?

대부분의 AI 에이전트는 시스템 프롬프트 하나에 모든 도메인 지식을 몰아넣는 방식으로 동작해요. 컴플라이언스 규칙, 스타일 가이드, API 레퍼런스, 트러블슈팅 절차까지 하나의 거대한 문자열로 연결하는 거죠. 태스크가 두세 개일 땐 문제없지만, 열 개 이상으로 늘어나면 매 LLM 호출마다 수천 토큰을 소비하게 돼요 — 사용자의 쿼리가 그 지식을 전혀 필요로 하지 않더라도요.

Google의 ADK(Agent Development Kit)는 이 문제를 프로그레시브 디스클로저(Progressive Disclosure)라는 아키텍처 패턴으로 풀어요. 필요한 컨텍스트를 필요한 시점에만 로드하는 구조인데, 이 글에서는 ADK의 SkillToolset을 활용한 4가지 실전 스킬 패턴을 단계별로 살펴볼게요.

ADK 에이전트 스킬 패턴 개요

ADK 스킬 스펙: 3단계 지식 로딩 구조

ADK 에이전트 스킬의 핵심은 지식을 세 단계로 분리하는 데 있어요.

L1 메타데이터 (~100 토큰/스킬)

스킬 이름과 설명만 포함하는 최소 정보예요. 에이전트가 시작될 때 모든 스킬의 L1을 로드해서, 어떤 스킬이 현재 쿼리에 관련 있는지 판단하는 메뉴 역할을 해요.

L2 인스트럭션 (<5,000 토큰)

스킬의 전체 본문이에요. 에이전트가 특정 스킬을 명시적으로 활성화할 때만 API를 통해 로드돼요.

L3 리소스 (필요 시)

스타일 가이드나 API 스펙 같은 외부 참조 파일이에요. 스킬의 인스트럭션이 요구할 때만 로드되죠.

이 구조 덕분에 10개 스킬을 가진 에이전트가 매 호출 시 약 1,000 토큰의 L1 메타데이터만 사용해요. 모놀리식 프롬프트 대비 약 90%의 컨텍스트 사용량 절감이 가능한 거예요. SkillToolset 클래스가 activate_skill, deactivate_skill, list_skills 세 가지 도구를 자동 생성해서 이 흐름을 관리해 줘요.

프로그레시브 디스클로저 아키텍처

4가지 스킬 패턴 구현하기

패턴 1: 인라인 스킬 — 가장 단순한 시작점

파이썬 객체로 직접 정의하는 방식이에요. 변경 빈도가 낮고 규모가 작은 규칙에 적합해요.

# Pattern 1: Inline Skill
seo_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="seo-checklist",
        description="SEO optimization checklist for blog posts.",
    ),
    instructions=(
        "When optimizing a blog post for SEO, check each item:\n"
        "1. Title: 50-60 chars, primary keyword near the start\n"
        "2. Meta description: 150-160 chars, includes a call-to-action\n"
        "3. Headings: H2/H3 hierarchy, keywords in 2-3 headings\n"
        "4. First paragraph: Primary keyword in first 100 words\n"
        "5. Images: Alt text with keywords, compressed\n"
    ),
)

frontmatter의 name과 description이 L1 메타데이터가 되고, instructions가 L2로 동작해요. "내 블로그 글 SEO 리뷰해줘"라고 요청하면 에이전트가 이 스킬을 로드해서 체계적으로 각 항목을 점검하게 돼요.

패턴 2: 파일 기반 스킬 — 레퍼런스가 필요할 때

인라인 스킬로는 스타일 가이드나 API 스펙 같은 참조 문서를 포함하기 어려워요. 파일 기반 스킬은 디렉터리 구조를 활용해요.

skills/blog-writer/
├── SKILL.md           # L2: 인스트럭션
└── references/
    └── style-guide.md # L3: 필요 시 로드
# Pattern 2: File-Based Skill
blog_writer_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "blog-writer"
)

SKILL.md가 YAML 프론트매터로 시작하고 마크다운 인스트럭션이 이어지는 구조예요. L2 인스트럭션이 "스타일 가이드를 참조하라"고 지시하면 그때 L3 리소스가 로드되는 거죠.

패턴 3: 외부 스킬 — 커뮤니티 저장소 활용

코드는 패턴 2와 동일해요. 차이점은 SKILL.md를 직접 작성하는 대신 커뮤니티 저장소에서 가져온다는 것뿐이에요.

# Pattern 3: External Skill
content_researcher_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "content-research-writer"
)

ADK 에이전트 스킬 스펙이 범용 디렉터리 포맷을 정의하기 때문에 load_skill_from_dir은 스킬의 출처를 신경 쓰지 않아요. Google이 공식 ADK 개발 스킬을 같은 포맷으로 제공하며, npx skills add google/adk-docs -y -g 명령으로 설치할 수 있어요.

패턴 4: 스킬 팩토리 — 스스로 확장하는 메타 스킬

가장 강력한 패턴이에요. 메타 스킬은 새로운 SKILL.md 파일을 생성하는 것이 목적인 스킬이에요. 이 스킬을 장착한 에이전트는 런타임에 새로운 스킬 정의를 작성하고 로드할 수 있어서, 사람의 개입 없이 자체적으로 역량을 확장해요.

보안 리뷰 체크리스트, 컴플라이언스 감사, 데이터 파이프라인 검증기 등 — 필요한 전문성을 그때그때 생성하고 로드해서 사용하는 워크플로우가 가능해지는 거예요. 패턴 1~3이 이미 존재하는 스킬을 다뤘다면, 패턴 4는 에이전트가 스스로 새로운 스킬을 만들어내는 루프를 완성해요.

ADK 에이전트 스킬 아키텍처 상세

실전 적용 시 고려할 점

ADK 에이전트 스킬 패턴을 프로덕션에 도입할 때 몇 가지 트레이드오프를 고려해야 해요.

  • L1 메타데이터의 description 품질이 스킬 선택 정확도를 좌우해요. 모호한 설명은 에이전트가 잘못된 스킬을 활성화하는 원인이 돼요.
  • L2 인스트럭션은 5,000 토큰 이하로 유지하는 게 권장돼요. 이를 초과하면 L3 리소스로 분리하는 편이 효율적이에요.
  • 패턴 4(메타 스킬)를 사용할 땐 생성된 스킬의 품질 검증 로직을 반드시 포함해야 해요. 에이전트가 잘못된 인스트럭션을 생성하면 다운스트림에 영향이 커질 수 있어요.
  • 외부 스킬을 로드할 때는 소스의 신뢰성을 확인하세요. SKILL.md에 임의 코드 실행 인스트럭션이 포함될 수 있으므로 샌드박싱을 고려해야 해요.

마무리

ADK의 프로그레시브 디스클로저 패턴은 모놀리식 프롬프트의 토큰 낭비 문제를 구조적으로 해결해요. 인라인 → 파일 기반 → 외부 → 메타 스킬로 이어지는 4단계 패턴을 통해 에이전트의 확장성과 효율성을 동시에 잡을 수 있어요. 특히 패턴 4의 자기 확장 구조는 에이전트가 새로운 도메인에 자율적으로 적응할 수 있는 가능성을 열어주므로, 복잡한 엔터프라이즈 시나리오에서 주목할 만한 접근이에요.

이 블로그의 인기 게시물

TorchTPU: PyTorch를 TPU에서 네이티브로 실행하는 구글의 전략

이미지
PyTorch + TPU, 왜 지금 중요한가 대규모 AI 모델 학습의 시대가 본격화되면서, 수천~수만 개의 가속기를 효율적으로 활용하는 소프트웨어 스택의 중요성이 급격히 커지고 있어요. Google의 TPU(Tensor Processing Unit)는 Gemini, Veo 같은 자체 AI 플랫폼은 물론 Cloud 고객의 대규모 워크로드를 처리하는 핵심 인프라인데요. 문제는 ML 커뮤니티의 상당수가 PyTorch 생태계에 익숙하다는 점이에요. TorchTPU 는 바로 이 간극을 메우기 위해 설계된 스택으로, 기존 PyTorch 코드를 최소한의 변경만으로 TPU에서 네이티브로 실행할 수 있게 해줘요. 이 글에서는 TorchTPU의 핵심 아키텍처, Eager 모드 전략, 정적 컴파일 파이프라인, 그리고 2026년 로드맵까지 개발자 관점에서 깊이 살펴볼게요. TPU 하드웨어 아키텍처 이해하기 TorchTPU 를 제대로 이해하려면 먼저 TPU의 하드웨어 구조를 알아야 해요. TPU는 단순한 칩이 아니라 통합 네트워크 시스템이에요. ICI와 토러스 토폴로지 각 호스트에는 여러 개의 TPU 칩이 연결되어 있고, 칩들은 Inter-Chip Interconnect(ICI)를 통해 2D 또는 3D 토러스(Torus) 토폴로지로 연결돼요. 이 구조 덕분에 전통적인 네트워크 병목 없이 대규모 스케일업이 가능해요. GPU 클러스터에서 InfiniBand나 NVLink에 의존하는 것과는 근본적으로 다른 접근이에요. TensorCore와 SparseCore 칩 내부 실행은 TensorCore와 SparseCore로 나뉘어요. TensorCore : 단일 스레드 유닛으로 밀집 행렬 연산(dense matrix math)에 특화 SparseCore : 임베딩, gather/scatter 같은 불규칙 메모리 접근 패턴과 collective 오프로딩 처리 이 이중 구조가 TPU의 핵심 강점이고, TorchTPU는 이 두 코어를 모두 활용할 수 있도록 설계되었어요. Eager First 철학: ...
자세한 내용 보기

가상 파일시스템으로 AI 어시스턴트 비용·속도 최적화하기

이미지
RAG(검색 증강 생성) 기반 AI 어시스턴트는 분명 강력하지만, 문서 탐색에서는 뚜렷한 한계를 보여요. 쿼리와 유사한 텍스트 청크만 반환하는 방식은 답변이 여러 페이지에 걸쳐 있거나 정확한 구문 매칭이 필요한 경우 제대로 작동하지 않아요. Mintlify 팀은 에이전트가 코드베이스를 탐색하듯 문서를 직접 탐색할 수 있는 구조가 필요하다고 판단했어요. 그 결과물이 바로 가상 파일시스템(Virtual Filesystem) — ChromaFs예요. 이 글에서는 ChromaFs의 설계 배경, 핵심 구조, 그리고 성능·비용 트레이드오프를 개발자 시각에서 깊이 있게 살펴볼게요. 실제 샌드박스가 실패하는 이유 에이전트에게 실제 파일시스템을 주는 건 직관적인 해결책이에요. 격리된 샌드박스를 스핀업하고 저장소를 클론하면 되니까요. Mintlify도 비동기 백그라운드 에이전트에는 실제로 이 방식을 사용해요. 그런데 사용자가 로딩 스피너를 바라보는 프론트엔드 어시스턴트 시나리오에서는 이야기가 완전히 달라져요. 레이턴시 문제 GitHub 클론을 포함한 세션 생성의 p90 레이턴시가 약 46초 에 달했어요. 사용자 입장에서 46초는 곧장 이탈로 이어지는 숫자예요. 아무리 답변 품질이 좋아도, 기다림 자체가 UX를 망가뜨려요. 비용 문제 정적 문서 읽기를 위해 전용 마이크로-VM을 띄우는 건 인프라 비용이 상당해요. Daytona의 퍼-세컨드 샌드박스 가격(vCPU당 $0.0504/h, GiB RAM당 $0.0162/h)을 기준으로, 월 850,000건의 대화에 최소 설정(1 vCPU, 2 GiB RAM, 5분 세션)을 적용하면 연간 $70,000 이상 이 나와요. 세션 시간이 늘어나면 이 수치는 두 배로 뛰죠. 항목 실제 샌드박스 ChromaFs 세션 생성 시간 ~46초 ~수백 ms 대화당 추가 비용 ...
자세한 내용 보기

gemma4 vllm 실행 방법: 설치·최적화·멀티GPU 완전 가이드

최신 LLM을 직접 서빙하는 환경을 구축하려면 단순 실행을 넘어서 성능, 안정성, 확장성까지 고려해야 해요. 특히 gemma4 vllm 실행 방법 은 최신 모델 특성상 문서와 실제 구현 간 차이가 존재하기 때문에, 제대로 이해하지 않으면 실행은 되더라도 성능이 크게 떨어질 수 있어요. 최근 vLLM이 Gemma 4를 공식 지원하면서 OpenAI-compatible API 형태로 바로 서비스가 가능해졌고, KV cache 최적화와 PagedAttention 덕분에 높은 throughput을 확보할 수 있어요. 이 글에서는 단순 실행을 넘어 실무 환경에서 바로 적용 가능한 수준으로 상세하게 정리해볼게요. gemma4 vllm 실행을 위한 시스템 아키텍처 이해 Gemma 4는 단순 텍스트 모델이 아니라 멀티모달 + reasoning 중심 모델이에요. vLLM은 이를 효율적으로 처리하기 위해 내부적으로 다음 구조를 사용해요. vLLM 핵심 구조 PagedAttention: KV cache를 페이지 단위로 관리해 fragmentation 최소화 Continuous batching: 요청을 실시간으로 합쳐 GPU utilization 극대화 OpenAI API layer: 기존 클라이언트 그대로 사용 가능 이 구조 덕분에 gemma4 vllm 실행 방법 은 단순하지만 내부적으로는 매우 고성능 추론 파이프라인이 동작해요. 권장 하드웨어 구성 7B 이하: RTX 3090 / 4090 (24GB) 27B 이상: A100 80GB 또는 멀티 GPU NVLink 환경이면 tensor parallel 효율 상승 메모리가 부족하면 swap이 아니라 inference 자체가 실패하기 때문에 VRAM 확보가 가장 중요해요. gemma4 vllm 설치 및 빌드 전략 Gemma 4는 최신 모델이기 때문에 stable보다 nightly 사용이 사실상 필수예요. Python 환경 설치 (권장) uv venv source .venv/bin/activate uv pip install -U vll...
자세한 내용 보기