ADK 에이전트 빌더
Google의 Agent Development Kit(ADK)을 사용하여 프로덕션에 바로 투입할 수 있는 에이전트를 구축하세요: 스캐폴딩, 툴 연결, 오케스트레이션 패턴, 테스트, 선택적 Vertex AI Agent Engine 배포.
개요
- 최소한의 프로덕션 중심 ADK 스캐폴드(에이전트 진입점, 툴 레지스트리, 구성, 테스트)를 생성합니다.
- 단일 에이전트 ReAct 스타일 워크플로우와 멀티 에이전트 오케스트레이션(순차적/병렬/루프)을 지원합니다.
- CI(린트/테스트/스모크 프롬프트)에 적합한 유효성 검사 체크리스트와 선택적 Agent Engine 배포 검증을 생성합니다.
필수 조건
- 프로젝트와 호환되는 Python 런타임(주로 Python 3.10 이상)
google-adk설치 및 import 가능- 배포하는 경우: Vertex AI가 활성화된 Google Cloud 프로젝트 및 Agent Engine 런타임 배포 권한 필요
- 환경 변수 또는 비밀 관리자를 통해 시크릿 사용 가능(절대 하드코딩 금지)
지침
- 범위 확인: 로컬 전용 에이전트 스캐폴드 vs Vertex AI Agent Engine 배포.
- 아키텍처 선택:
- 적응형 툴 기반 작업을 위한 단일 에이전트(ReAct)
- 복잡한 다단계 워크플로우를 위한 멀티 에이전트 시스템(전문가 + 오케스트레이터)
- 툴 표면 정의(내장 ADK 툴 + 필요한 사용자 정의 툴) 및 필수 자격 증명.
- 프로젝트 스캐폴딩:
src/agents/,src/tools/,tests/, 의존성 파일(pyproject.toml또는requirements.txt)
- 최소 실행 가능 에이전트 및 스모크 테스트 프롬프트 구현; 툴 실패에 대한 회귀 테스트 추가.
- 배포하는 경우:
adk deploy ...명령어 및 배포 후 검증 체크리스트(AgentCard/작업 엔드포인트, 권한, 로그) 생성.
결과물
- 레포 준비 완료 ADK 스캐폴드(파일 및 디렉토리) 및 스타터 에이전트 코드
- 툴 스텁 및 연결 지점(새 툴을 안전하게 추가할 수 있는 위치)
- 테스트 및 검증 계획(단위 테스트 및 최소 스모크 프롬프트)
- 선택 사항: Agent Engine 배포 명령어 및 검증 단계
오류 처리
- 의존성/런타임 문제: 고정된 설치 명령어 제공 및 import 검증.
- 인증/권한 실패: 누락된 역할/API 식별 및 최소 권한 수정 제안.
- 툴 실패/속도 제한: 재시도/백오프 지침 추가 및 재발 방지를 위한 회귀 테스트.
예제
예제: 단일 ReAct 에이전트 스캐폴드
- 요청: "PR을 요약하고 테스트 업데이트를 제안하는 ADK 에이전트를 만들어."
- 결과: 에이전트 진입점 + 툴 레지스트리 + 로컬 검증을 위한 스모크 테스트 명령어.
예제: 멀티 에이전트 오케스트레이터
- 요청: "슈퍼바이저 + 디플로이어 + 검증자 팀을 만들고 Agent Engine에 배포해."
- 결과: 오케스트레이터 스켈레톤, 에이전트별 책임,
adk deploy ...+ 배포 후 상태 점검.
리소스
- 전체 상세 가이드(참고용):
${CLAUDE_SKILL_DIR}/references/SKILL.full.md - 레포 표준(진리의 원천):
000-docs/6767-a-SPEC-DR-STND-claude-code-plugins-standard.md000-docs/6767-b-SPEC-DR-STND-claude-skills-standard.md
- ADK / Agent Engine 문서: https://cloud.google.com/vertex-ai/docs/agent-engine