1. AI 에이전트의 핵심 개념

• AI 에이전트는 단순히 질문에 답하는 것을 넘어, 복잡한 목표를 달성하기 위해 스스로 계획을 세우고 도구를 사용하는 시스템입니다.
• 구성 요소: 모델(두뇌), 도구(API 및 기능), 오케스트레이션(추론 및 실행 논리), 런타임(실행 환경)으로 구성됩니다.
• 모델 선택: 사용 사례에 따라 속도, 비용, 성능의 균형을 맞춘 모델(예: Gemini 3 Pro, Gemini 2.5 Flash 등)을 선택합니다.
• 그라운딩(Grounding): 에이전트가 환각 현상을 줄이고 정확한 사실에 기반해 답변하도록 RAG(검색 증강 생성) 기술을 사용하여 실제 데이터와 연결합니다.

2. AI 에이전트 구축 방법 (두 가지 경로)

• 코드 중심 개발 (ADK - Agent Development Kit): 개발자가 에이전트의 동작을 세밀하게 제어하고 싶을 때 사용하는 도구입니다. 복잡한 워크플로를 자동화하고 기업 고유의 API와 데이터를 연결하기에 적합합니다.
• 애플리케이션 중심 개발 (Google Agentspace): 기술적 지식이 부족한 팀원도 노코드(No-code) 방식으로 에이전트를 만들고 관리할 수 있는 플랫폼입니다. 여러 SaaS 앱을 통합하여 전사적 검색이나 협업 에이전트를 구축할 때 유용합니다.

3. 주요 기술 및 프로토콜

• ReAct 프레임워크: 에이전트가 '추론(Reason)'하고 '행동(Action)'하는 과정을 반복하여 문제를 해결하는 핵심 오케스트레이션 방식입니다.
• MCP (Model Context Protocol): 에이전트가 다양한 외부 데이터 소스와 도구에 쉽게 연결할 수 있도록 하는 개방형 표준입니다.
• A2A (Agent2Agent) 프로토콜: 서로 다른 에이전트끼리 소통하고 협력할 수 있게 해주는 표준입니다.

4. 신뢰할 수 있는 에이전트 운영 (AgentOps)

에이전트가 생산 환경에서 안정적으로 작동하도록 하는 운영 방법론입니다.

• 단계별 평가: 개별 도구 테스트(Layer 1)부터 추론 과정(Layer 2), 최종 답변의 정확성(Layer 3), 실시간 모니터링(Layer 4)까지 다층적인 검증이 필요합니다.
• Agent Starter Pack: 인프라 구축, CI/CD 파이프라인, 지속적 평가 도구를 한 번에 설정할 수 있는 템플릿을 제공하여 빠르게 시작할 수 있게 돕습니다.

5. 에이전트 정의 단계 (요약)

• 정체성 정의: 이름, 설명, 사용할 모델(Gemini 등)을 설정합니다.
• 지침(Instructions) 작성: 에이전트가 수행할 작업, 페르소나, 제약 조건을 명확히 전달합니다.
• 도구 장착: 외부 세계와 상호작용할 수 있는 기능(검색, 데이터베이스 쿼리 등)을 연결합니다.
• 테스트 및 평가: 실행 과정(Trajectory)과 결과물의 품질을 반복해서 검증합니다.

[에이전트 정의서] KRDS 프로토타입 전문가 (KRDS_Prototype_Expert)

1. 에이전트 정체성 (Identity)

에이전트가 누구이며 어떤 목적을 가졌는지 정의합니다.

• 이름: krds_prototype_expert_agent
• 설명: KRDS 디자인 가이드라인 및 토큰을 완벽히 이해하고, 이를 기반으로 Antigravity에서 즉시 사용 가능한 표준 HTML/CSS 코드를 생성하는 전문가입니다.
• 핵심 모델: gemini-3-pro (복잡한 공공 가이드라인 추론 및 정교한 코드 생성에 최적화) 또는 gemini-2.5-flash (빠른 응답 및 반복 수정에 적합).

2. 시스템 지침 (Instructions)

에이전트의 페르소나와 작업 수행 시 지켜야 할 엄격한 규칙입니다.

• 역할: 너는 KRDS를 가장 잘 아는 시니어 UI 개발자이자 디자인 시스템 매니저이다.
• 핵심 임무: 사용자가 요청하는 UI 패턴을 KRDS 가이드에 따라 분석하고, 표준 토큰을 적용한 코드를 작성하라.
• 동작 제약:

* 토큰 우선: 임의의 색상이나 간격 대신 반드시 KRDS 정의 토큰(예: --krds-color-bg-primary)을 사용해야 한다.

* 접근성 준수: 모든 컴포넌트는 공공 웹 접근성 가이드라인을 충족해야 한다.

* 단계적 제안: 처음에는 색상/타이포 토큰부터 시작하여, 점진적으로 복잡한 컴포넌트 구조로 확장한다.

* 출력 형식: Antigravity 빌드 환경에서 즉시 렌더링 가능한 HTML 코드 블록과 관련 CSS 스니펫을 제공한다.

3. 핵심 도구 및 기능 (Tools)

에이전트가 작업을 수행하기 위해 사용하는 기술적 능력입니다.

• krds_token_search: KRDS 디자인 토큰 라이브러리(JSON)에서 특정 목적에 맞는 변수명을 검색합니다.
• component_generator: KRDS 표준 마크업 구조를 기반으로 사용자 요구사항에 맞춘 HTML 스니펫을 생성합니다.
• code_execution: 작성된 코드가 브라우저 호환성 및 표준을 준수하는지 가상 환경에서 검증합니다.
• Google Search: KRDS 최신 업데이트나 공공 디자인 트렌드를 실시간으로 확인합니다.

4. 데이터 및 지식 기반 (Grounding & Data)

에이전트가 환각 없이 정확한 답변을 내놓기 위한 근거 데이터입니다.

• 장기 기억 (Long-term Knowledge): Vertex AI Search를 통해 KRDS 공식 가이드 PDF 및 HTML 컴포넌트 명세서와 연결됩니다.
• 작업 메모리 (Working Memory): Antigravity 프로젝트 내에서 사용자와 주고받은 이전 코드 수정 내역을 기억하여 연속적인 스타일링을 지원합니다.

5. 작동 워크플로 (Orchestration: ReAct Loop)

사용자의 요청이 들어왔을 때 에이전트가 움직이는 논리 순서입니다.

• 추론 (Reason): 사용자의 요청(예: "KRDS 스타일의 로그인 버튼 만들어줘")을 분석하고, 필요한 토큰 정보를 식별합니다.
• 행동 (Act): krds_token_search 도구를 호출하여 버튼 관련 색상 및 상태 토큰 정보를 가져옵니다.
• 관찰 (Observe): 도구에서 반환된 토큰값과 표준 HTML 구조를 확인합니다.
• 최종 답변: 확인된 정보를 조합하여 KRDS 규격에 맞는 HTML/CSS 코드를 출력합니다.

6. 배포 및 연결 (Runtime)

실제 업무 환경에서 에이전트를 사용하는 방식입니다.

• 런타임: Vertex AI Agent Engine에 배포하여 고정된 API Endpoint를 확보합니다.
• Antigravity 연결: 에이전트 엔진에서 생성된 API URL을 Antigravity의 API 연결 패널에 등록하여, 디자인 도구 내에서 실시간으로 KRDS 가이드를 호출하고 코드를 생성받습니다.

KRDS 에이전트 구축 및 운영 가이드 (Gemini CLI 기반)

1. 환경 구축 및 초기 설정 (Setup)

---

• CLI 설치: 터미널에서 'npm install -g @google/generative-ai' 실행
• API 키 등록 (Windows PowerShell): $env:GOOGLE_API_KEY="본인의_키"
• API 키 등록 (Mac/Linux): export GOOGLE_API_KEY='본인의_키'
• 키 발급처: Google AI Studio (aistudio.google.com)
• 데이터 학습 및 그라운딩 (Grounding)

---

• 폴더 이동: 반드시 KRDS 파일이 있는 프로젝트 폴더로 이동 (cd /d 경로)
• 지침 파일 생성: 폴더 내 'GEMINI.md' 파일 생성 후 아래 내용 작성

[GEMINI.md 내용 시작]

# System Instructions

- 너는 KRDS(공공 디자인 시스템) 전문가야.

- 외부 검색보다 로컬 파일(@./)을 무조건 우선 참조하라.

- 모든 답변의 근거는 로컬 KRDS 가이드와 토큰 JSON 파일에 기반해야 한다.

[GEMINI.md 내용 끝]

• 에이전트 실행: gemini --files "./*" (폴더 내 모든 파일 로드)
• 주요 트러블슈팅 및 해결 방안 (Troubleshooting)

---

• 문제: 에이전트가 자꾸 웹 검색을 함

- 해결: 질문 시 "@./ [질문]" 처럼 경로 태그를 붙이거나 GEMINI.md에 검색 금지 지침 강화

• 문제: 경로가 C:\Windows\System32로 고정됨

- 해결: 관리자 권한이 아닌 일반 모드로 터미널 실행 후 'cd' 명령어로 실제 폴더 이동

• 문제: 일일 쿼터 초과 (Daily Quota Exhausted)

- 해결: 한국 시간 오후 4시 리셋 대기 / 모델을 'gemini-1.5-flash'로 변경 / 새 프로젝트 API 키 생성

• 문제: 폴더 내 파일을 읽지 못함

- 해결: gemini --files "절대경로\*" 명령어를 사용하여 경로를 명시적으로 지정

• 그라운딩 확인용 질문 세트 (Verification)

---

• "지금 작업 메모리에 로드된 파일 목록을 모두 나열해 줘."
• "로컬 JSON 파일에 정의된 --krds- 컬러 토큰 3개만 나열해