Agent Platform에서 ADK 및 Agents CLI로 에이전트 빌드

이 문서에서는 에이전트 플랫폼에서 Agents CLI와 함께 에이전트 개발 키트 (ADK)를 사용하여 프로토타입 AI 에이전트를 빌드, 평가, 배포하는 방법을 보여줍니다. ADK는 정교한 AI 에이전트를 빌드하기 위한 오픈소스 코드 중심 프레임워크입니다. 에이전트 CLI는 AI 개발 도구가 ADK와 상호작용할 수 있는 통합된 머신 리더블 인터페이스를 제공하여 엔드 투 엔드 에이전트 수명 주기 관리를 지원합니다. ADK, 에이전트 평가, Google Cloud배포에 관한 전문가 지식을 캡슐화하여 AI 개발 도구가 자연어 프롬프트에서 복잡한 작업을 실행할 수 있도록 지원합니다.

Gemini CLI, Claude Code, Codex와 같은 선호하는 AI 기반 개발 도구와 함께 Agents CLI를 사용하면 자연어 프롬프트를 사용하여 프로토타입 에이전트를 정의하고, 로컬에서 테스트하고,Google Cloud 런타임에 배포할 수 있습니다.

이 튜토리얼에서는 원시인에서 영감을 받아 장황한 텍스트를 간결한 요약으로 변환하는 '원시인 컴프레서' 에이전트를 만드는 방법을 안내합니다.

시작하기 전에

다음 기본 요건을 완료합니다.

  1. Google Cloud 프로젝트가 있고 Agent Platform API를 사용 설정했는지 확인합니다. 그렇지 않은 경우 다음 빠른 시작 중 하나를 완료하세요.

  2. Antigravity, Gemini CLI, Claude Code, Codex와 같은 AI 기반 개발 도구를 설치합니다. 이 도구는 Agents CLI와 상호작용하는 데 필요합니다.

설정

  1. Python 패키지 설치 프로그램인 uv를 설치합니다. 자세한 내용은 uv 설치 가이드를 참고하세요.

  2. uvx (uv에 포함됨)를 사용하여 Agents CLI 설정 명령어를 실행합니다. 이는 직접 실행하는 유일한 Agents CLI 명령어입니다.

    uvx google-agents-cli setup

  3. Antigravity와 같은 AI 개발 도구를 엽니다.

스캐폴드 프로젝트

다음 프롬프트로 AI 개발 도구에 지시합니다.

Use agents-cli to build an agent that compresses verbose text into concise, caveman-style summaries.

AI 개발 도구가 google-agents-cli-workflow 및 google-agents-cli-scaffold 기술을 활성화합니다. 다음 작업을 수행합니다.

  • 배포 타겟, 안전 제약 조건과 같은 명확한 질문을 합니다.
  • 에이전트의 목적을 캡처하는 DESIGN_SPEC.md 파일을 작성합니다.

  • 프로젝트를 스캐폴딩합니다.

    agents-cli create caveman-agent --prototype --yes
cd caveman-agent && agents-cli install

이 프로세스는 상용구 에이전트 코드, 테스트, 평가 세트가 포함된 프로젝트를 만듭니다.

에이전트 빌드

AI 개발 도구는 app/agent.py을 수정하여 기본 에이전트를 동굴인 압축기 로직으로 대체합니다. ADK 디자인 패턴에 google-agents-cli-adk-code 스킬을 활용합니다.

결과 에이전트 정의는 다음과 유사합니다.

root_agent = Agent(
   name="caveman_agent",
   model=Gemini(model="gemini-flash-latest"),
   instruction="""You are a text compressor. Convert verbose input text into short, simple summaries with a caveman-like tone. Rules:
   - Omit articles, filler words, and politeness.
   - Use short sentences and simple words.
   - Preserve technical terms.
   - The tone should be abrupt and funny, but the core meaning must be retained.

   Example input:  "I would like to deploy the application to production environment."
   Example output: "Me deploy. Production. Now."
   """,
)

그러면 AI 개발 도구가 기본 기능 테스트를 실행합니다.

agents-cli run "Please help me understand the deployment options available for my project"

이 테스트의 예상 출력은 다음과 같습니다.

'배포 옵션: 에이전트 런타임, Cloud Run, GKE. 하나를 선택하세요. 배송'을 클릭합니다.

에이전트 평가

에이전트를 평가하려면 다음 프롬프트로 AI 개발 도구에 지시하세요.

Write evaluations for the caveman agent and run them.

AI 개발 도구가 google-agents-cli-eval 스킬을 활성화하고 다음 작업을 실행합니다.

  • 압축 품질, 기술 용어 보존, 어조를 다루는 테스트 사례로 tests/eval/evalsets/caveman.evalset.json를 만듭니다.
  • tests/eval/eval_config.json에서 LLM-as-judge 기준을 구성합니다.

  • 평가를 실행합니다.

    agents-cli eval run

테스트 사례가 실패하면 AI 개발 도구에 수정 의견을 제공하세요. 예를 들면 다음과 같습니다.

인사 테스트에 대한 대답이 너무 공손합니다. 더 간결하게 만들어 줘.

AI 개발 도구는 에이전트의 지침을 조정하고, agents-cli eval run를 다시 실행하고, 원하는 품질이 달성될 때까지 반복합니다.

에이전트 배포

Google Cloud에 에이전트를 배포하고 실행하려면 AI 개발 도구에 다음과 같이 지시하세요.

Deploy this agent to Cloud Run.

AI 개발 도구가 google-agents-cli-deploy 스킬을 활성화하고 다음을 실행합니다.

  • 필요한 배포 인프라 구성을 추가합니다.

    agents-cli scaffold enhance --deployment-target cloud_run

  • 에이전트를 배포합니다.

    agents-cli deploy

이제 에이전트가 Cloud Run에 배포됩니다. 출력에는 에이전트에 액세스하는 데 사용하는 서비스 URL이 포함됩니다.

에이전트 관찰

Cloud Trace는 기본적으로 사용 설정되어 있습니다. trace를 보려면 Google Cloud 콘솔에서 Cloud Trace 탐색기를 열고 배포된 에이전트에 요청을 보냅니다. LLM 호출 및 도구 실행의 스팬이 표시됩니다.

더 자세한 관측 가능성을 사용 설정하려면 AI 개발 도구에 다음을 지시하세요.

Set up observability infrastructure for my agent.

AI 개발 도구는 서비스 계정, Cloud Storage 버킷, BigQuery 데이터 세트를 프로비저닝하고 이러한 리소스를 사용하도록 배포된 서비스를 업데이트합니다. 자세한 내용은 모니터링 가능성 가이드를 참고하세요.

조치 요약

이 표에는 프롬프트와 AI 개발 도구에서 실행하는 해당 작업이 요약되어 있습니다.

사용자 안내 AI 개발 도구 작업
'동굴인 컴프레서 에이전트 빌드' 프로젝트를 스캐폴딩하고, 에이전트 코드를 작성하고, 로컬에서 테스트합니다.
'평가 작성 및 실행' 평가 세트를 만들고, LLM을 평가자로 구성하고, agents-cli eval run를 실행합니다.
'Cloud Run에 배포' 배포 대상 구성을 추가하고 Cloud Run에 배포합니다.
모니터링 가능성 설정 서비스 계정, Cloud Storage 버킷, BigQuery 데이터 세트를 프로비저닝합니다.

에이전트 CLI 기술은 AI 개발 도구가 적절한 ADK 패턴을 사용하고, 평가를 구조화하고, 배포를 구성하는 데 필요한 컨텍스트를 제공합니다.

다음 단계

다음 프롬프트로 더 복잡한 에이전트 설계를 살펴보세요.

  • 도구 추가: '에이전트가 최신 정보에 액세스할 수 있도록 Google 검색 도구를 통합해 줘.'
  • 멀티 에이전트 시스템: 'adk_a2a 템플릿을 사용하여 다른 에이전트와 상호작용할 수 있는 에이전트를 만들어 줘.'
  • RAG: 'agentic_rag 템플릿을 사용하여 문서에 기반해 질문에 답변하는 에이전트를 빌드해 줘.'

Agent Platform에 대해 자세히 알아보세요.