1. 개요
이 Codelab에서는 Agents CLI를 사용하여 AI 에이전트의 전체 로컬 개발 수명 주기를 관리하는 방법을 알아봅니다. 기존 Gemini 모델을 래핑하든 에이전트 개발 키트 (ADK 2.0)로 맞춤 에이전트를 처음부터 빌드하든 Agents CLI는 에이전트를 로컬에서 스캐폴딩, 빌드, 린트, 테스트하는 도구를 제공합니다.
학습할 내용
agents-cli및 관련 기술을 설치하고 설정하는 방법- 새 에이전트 프로젝트를 스캐폴딩하는 방법
- ADK 2.0 그래프 워크플로 에이전트 프로젝트의 구조 및 주요 파일
- 자동 린트 및 코드 정리 실행 방법
- 자동 다시 로드를 사용하여 대화형 테스트를 위한 로컬 웹 플레이그라운드를 실행하고 사용하는 방법
필요한 항목
- Python 3.11 이상
- uv 패키지 관리자
- Node.js 18+ (코딩 에이전트 기술을 사용하는 경우)
- Antigravity IDE (Google Antigravity에서 설치 및 구성)
기본 요건
이 Codelab에서는 다음을 잘 알고 있다고 가정합니다.
- 터미널 및 명령줄 사용
AI 에이전트 또는 ADK 2.0에 대한 사전 경험은 필요하지 않습니다.
2. 인증 및 환경 설정
에이전트가 Gemini 모델을 호출할 수 있도록 인증 사용자 인증 정보를 제공합니다.
옵션 1: Gemini API 키 (Google AI Studio)
표준 Gemini API 키 (Google AI Studio에서 가져올 수 있음)를 사용하는 경우 IDE 터미널 세션에서 내보냅니다.
export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE
옵션 2: Google Cloud 애플리케이션 기본 사용자 인증 정보
Google Cloud에서 Vertex AI를 사용하는 경우 Google Cloud 애플리케이션 기본 사용자 인증 정보 (ADC)로 인증하고 활성 Google Cloud 프로젝트를 설정합니다.
gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location
3. Agents CLI 및 기술 설정
첫 번째 단계는 agents-cli 도구를 설치하는 것입니다. 이 도구는 에이전트 프로젝트 관리의 어려운 작업을 처리합니다.
Antigravity가 설치된 상태에서 터미널에서 직접 설정 명령어를 실행합니다.
👉 터미널을 열고 다음을 실행합니다.
uvx google-agents-cli setup
이 명령어는 다음을 자동으로 설치합니다.
- 시스템에 Agents CLI 도구를 전역적으로 설치합니다.
- Antigravity가 에이전트를 빌드, 스캐폴딩, 평가, 배포하는 데 사용할 수 있는 7가지 도메인별 코딩 어시스턴트 기술 입니다. 이러한 기술은
~/.agents/skills/에 전역적으로 한 번 설치되며 Antigravity에서 자동으로 검색됩니다.
참고: 기술은 ~/.agents/skills/에 설치되며 Antigravity에서 자동으로 선택됩니다. /skills 명령어 또는 Antigravity 설정을 사용하여 이를 확인할 수 있습니다.
예상 출력 (잘림):
█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`
`Your coding agent just got an upgrade.`
`1. Authentication`
`─────────────────`
`✓ Authenticated with Google Cloud`
`2. CLI Installation`
`───────────────────`
`▸ uv tool install google-agents-cli`
`✓ Installed google-agents-cli`
`3. Skills Installation`
`──────────────────────`
`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`
`◇ Found 7 skills`
`~/.agents/skills/google-agents-cli-adk-code`
`~/.agents/skills/google-agents-cli-deploy`
`~/.agents/skills/google-agents-cli-eval`
`~/.agents/skills/google-agents-cli-observability`
`~/.agents/skills/google-agents-cli-publish`
`~/.agents/skills/google-agents-cli-scaffold`
`~/.agents/skills/google-agents-cli-workflow`
4. 에이전트 프로젝트 만들기
이 섹션에서는 프로토타입 템플릿을 사용하여 완전히 구조화된 프로젝트 디렉터리를 만듭니다.
👉 Antigravity에 프롬프트 표시:
Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.
Antigravity는 스캐폴딩 명령어 (agents-cli scaffold create customer-support-agent --prototype --yes)를 자동으로 실행하고 프로젝트 파일을 설정합니다.
5. 에이전트 코드 살펴보기
👉 Antigravity에 생성된 코드를 설명해 달라고 요청합니다.
Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.
Antigravity IDE에서 새로 만든 프로젝트 파일 및 아티팩트는 보조 창 (왼쪽)에 직접 표시됩니다. 여기에서 app/agent.py를 보거나 IDE 파일 탐색기에서 열어 스캐폴딩된 코드를 살펴볼 수 있습니다.
# app/agent.py
from __future__ import annotations
from typing import Any, Literal
from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field
class InquiryCategory(BaseModel):
category: Literal['shipping', 'unrelated'] = Field(
description=(
'Determine if the user query is related to shipping (rates, tracking,'
' delivery times, returns) or unrelated.'
)
)
def save_query(node_input: str):
"""Saves user query in state for downstream nodes."""
yield Event(data=node_input, state={'user_query': node_input})
categorize_agent = LlmAgent(
name='categorize',
model='gemini-3.1-flash-lite',
instruction='You are an expert classifier. Categorize the user query.',
output_key='inquiry_category',
output_schema=InquiryCategory,
)
@node
def route_inquiry(ctx: Context, node_input: Any):
"""Routes the workflow based on the classified category."""
category_data = ctx.state.get('inquiry_category', {})
category = category_data.get('category', 'unrelated')
query = ctx.state.get('user_query', '')
yield Event(data=query, route=category)
faq_agent = LlmAgent(
name='shipping_faq',
model='gemini-3.1-flash-lite'',
instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
SHIPPING FAQ:
- Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
over $50 qualify for free standard shipping.
- Tracking: You can track your order by entering your tracking number on
our website's tracking page.
- Delivery Times: Standard delivery takes 3-5 business days. Express
delivery takes 1-2 business days.
- Returns: We offer free returns within 30 days of delivery. Please make
sure the item is in its original condition.
""",
)
@node
def handle_unrelated(ctx: Context, node_input: Any):
"""Handles unrelated inquiries politely."""
yield Event(
data=(
'I am sorry, I am a shipping customer support assistant and can only'
' answer questions related to our shipping FAQ.'
)
)
root_agent = Workflow(
name='customer_support_workflow',
edges=[
*Edge.chain('START', save_query, categorize_agent, route_inquiry),
(route_inquiry, faq_agent, 'shipping'),
(route_inquiry, handle_unrelated, 'unrelated'),
],
)
app = App(
name='customer_support_agent',
root_agent=root_agent,
)
주요 개념
- 워크플로 및 엣지: ADK 2.0에서 에이전트 애플리케이션은
Workflow를 사용하여 그래프로 조정됩니다.edges목록은 실행 흐름을 정의하고START에서 노드를 함께 연결하며 경로를 기반으로 조건부 분기 (예:"shipping"에서faq_agent로 라우팅하거나"unrelated"에서handle_unrelated로 라우팅)를 사용 설정합니다. - LlmAgent: 특정 안내, 모델, 구조화된 출력 (
output_schema)으로 LLM 기반 작업을 정의하는 선언적 노드입니다. - 노드 및 컨텍스트:
@node로 데코레이팅된 Python 함수 (또는 표준 함수)로, 로직을 실행하고Context를 통해 실행 상태에 액세스하며Event객체를 생성하여 그래프를 따라 데이터 및 라우팅 신호를 전달합니다. - 모델: `gemini-3.1-flash-lite'가 기본 빠른 추론 모델로 사용됩니다.
- 앱 래퍼: 최상위
App객체는 루트 워크플로를 래핑합니다. 로컬 플레이그라운드, ADK 평가 하니스, 에이전트 런타임과 같은 외부 도구는 이 표준화된app인터페이스를 통해 워크플로를 검색하고 실행합니다.
6. 자동 린트
에이전트를 실행하거나 테스트하기 전에 코드가 정리되고 올바르게 형식이 지정되었는지 확인하는 것이 좋습니다.
👉 Antigravity에 프롬프트 표시:
Run linting on my agent project to verify its health.
Antigravity는 백그라운드에서 agents-cli lint를 실행하여 미리 구성된 검사를 실행하고 파일 전반에서 가져오기, 구문, 형식 일관성을 확인합니다.
7. 플레이그라운드를 사용한 대화형 테스트
로컬 웹 플레이그라운드는 에이전트의 동작을 확인하는 가장 빠른 방법입니다. 에이전트와 채팅하고 도구 실행을 실시간으로 검사할 수 있는 대화형 채팅 인터페이스를 제공합니다.
👉 Antigravity에 프롬프트 표시:
Launch the local development playground for my agent.
Antigravity는 로컬 개발 서버 (agents-cli playground)를 시작합니다. 웹브라우저에서 제공된 URL (일반적으로 http://127.0.0.1:8080/dev-ui/?app=app)을 열고 드롭다운에서 폴더 app를 선택하여 에이전트와 채팅을 시작합니다.
웹 인터페이스에서 에이전트와 채팅을 시작합니다. 배송 관련 질문을 해 보세요.
How much is standard shipping?
워크플로가 답변을 위해 faq_agent로 성공적으로 분류하고 라우팅하는 방법을 확인합니다. 또한 워크플로가 handle_unrelated로 라우팅되고 답변을 올바르게 거부하는지 확인하기 위해 관련 없는 질문을 해 보세요.
What is the weather like?
실시간 자동 다시 로드 테스트
에이전트에 대한 실시간 수정사항이 플레이그라운드에 반영되는 방식을 확인할 수 있습니다.
- Antigravity에 요청하여
app/agent.py의faq_agent안내를 수정합니다.Modify the faq_agent instruction in app/agent.py to make the shipping rates response more playful and enthusiastic. Add some emojis and highlight the free shipping threshold. - 플레이그라운드에서 에이전트에 새 메시지를 보내 자동 다시 로드를 테스트합니다.
How much is standard shipping?
8. 명령줄 실행
빠른 테스트, 자동화 또는 스크립팅을 위해 Antigravity에 터미널에서 직접 에이전트를 실행해 달라고 요청할 수 있습니다.
👉 Antigravity에 프롬프트 표시:
Run a CLI query asking my agent how long standard delivery takes.
Antigravity는 쿼리 명령어 (agents-cli run "How long does standard delivery take?")를 실행합니다. 이렇게 하면 빠른 단일 턴 추론이 실행되고 도구 실행 세부정보와 함께 에이전트의 최종 대답이 출력됩니다.
9. 정리
로컬 환경에 원치 않는 리소스가 남지 않도록 하려면 다음 정리 단계를 따르세요.
- 로컬 서버 중지:
agents-cli playground서버가 아직 실행 중인 경우 터미널에서Ctrl + C를 눌러 중지합니다. - 로컬 프로젝트 파일 삭제: 스캐폴딩된 에이전트 프로젝트 디렉터리를 로컬 머신에서 삭제합니다.
rm -rf customer-support-agent
10. 요약 및 다음 단계
축하합니다. Agents CLI 및 ADK 2.0 을 사용하여 AI 에이전트의 엔드 투 엔드 로컬 개발 수명 주기를 성공적으로 관리했습니다.
학습한 내용
- 도구 설정: Agents CLI를 설치하고 Antigravity의 도메인별 워크플로 기술을 구성했습니다.
- 프로젝트 스캐폴딩: 표준화된 템플릿을 사용하여 완전히 구조화된
customer-support-agent프로젝트를 만들었습니다. - ADK 2.0 구조 분석: 그래프 워크플로, LLM 에이전트, 노드, 엣지, 조건부 라우팅을 살펴봤습니다.
- 로컬 상태 관리:
agents-cli lint를 사용하여 자동 코드 품질 검사를 실행했습니다. - 동작 확인: 플레이그라운드를 통해 실시간 핫 리로드를 사용하여 에이전트를 대화형으로 테스트하고 명령줄에서 빠른 테스트를 실행했습니다.
다음 단계
이제 로컬 개발 루프를 마스터했으므로 에이전트를 확장하고 프로덕션화하는 방법은 다음과 같습니다.
- 평가: evalset에 대해 에이전트의 점수를 매겨 정확도를 측정하고 회귀를 찾습니다.
agents-cli eval run - 엔터프라이즈 클라우드 규모: 배포 & 관측 가능성:
agents-cli deploy를 사용하여 에이전트를 에이전트 런타임 또는 Cloud Run과 같은 프로덕션 환경에 패키징하고 배포합니다. 로그 및 실행 추적을 Cloud Trace 및 BigQuery로 스트리밍하도록 프로덕션 원격 분석을 설정합니다.