Next ‘26 개발자 기조연설: 대규모 에이전트 디버깅

1. 소개

이 Codelab에서는 Google Cloud에서 실행되는 AI 에이전트를 디버깅하는 방법을 알아봅니다. 시뮬레이터 에이전트를 에이전트 런타임에 배포하고, Cloud Observability를 사용하여 문제를 감지하고, Gemini Cloud Assist 및 Antigravity IDE를 사용하여 실시간으로 오류의 근본 원인을 파악하고 수정합니다.

이 데모의 전제는 시뮬레이터 에이전트에 ADK EventCompaction을 추가했다는 것입니다. 이를 통해 시뮬레이터는 Gemini를 사용하여 워크플로를 주기적으로 요약할 수 있으므로 각 턴에서 모델로 전송되는 총 컨텍스트가 줄어들어 응답 품질이 개선되고 총비용이 절감됩니다. 하지만 EventCompactionConfig에 버그가 있어 에이전트에 오류가 발생한다는 것을 알게 됩니다. 이 Codelab에서는 이러한 종류의 문제를 찾아 신속하게 해결하는 방법을 설명합니다.

실습할 내용

• 마라톤 시뮬레이터 에이전트를 Agent Runtime에 배포합니다.
• Cloud Monitoring 알림을 설정하여 에이전트 오류를 감지합니다.
• Cloud Trace 및 Gemini Cloud Assist를 사용하여 오류를 조사합니다.
• Antigravity 및 MCP를 사용하여 에이전트의 근본 원인을 파악하고 패치를 적용합니다.

참고: Gemini Cloud Assist는 현재 비공개 프리뷰로 제공됩니다. 이 Codelab을 실행하기 위해 Cloud Assist가 허용 목록에 추가될 필요는 없습니다. 모든 Cloud Assist 단계는 #8 (선택사항): Cloud Assist 조사 사용에 격리되어 있습니다. 아직 Cloud Assist에 액세스할 수 없는 경우 이 페이지를 건너뛰세요.

필요한 항목

• 웹브라우저(예: Chrome)
• Google 계정
• Antigravity (Mac, Linux, Windows 지원)
• Python 3.13 이상
• uv (Python 패키지 관리자)

예상 소요 시간: 45분

예상 비용: 5달러 미만

2. 시작하기 전에

Google Cloud 프로젝트 만들기

1. Google Cloud 콘솔에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
2. Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

환경 설정

Antigravity를 열고 로그인합니다. 그런 다음 cmd-shift-P (또는 ctrl-shift-P)을 누르고 '새 터미널 만들기'를 입력하여 터미널을 엽니다.

1. 터미널에서 Google Cloud로 인증합니다.

gcloud auth login
gcloud auth application-default login

2. 프로젝트 ID를 설정합니다.

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

API 사용 설정

다음 명령어를 실행하여 필요한 Google Cloud API를 사용 설정합니다.

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

Gemini Cloud Assist (비공개 프리뷰)에 허용 목록으로 등록된 경우 다음 추가 API를 사용 설정합니다.

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. 시뮬레이터 에이전트 설정

이 단계에서는 데모 저장소를 클론하고 시뮬레이터 에이전트의 환경 변수를 구성합니다.

저장소 클론

next-26-keynotes 저장소를 클론하고 데모 디렉터리로 이동합니다.

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

환경 변수 구성

시뮬레이터 에이전트는 구성을 위해 .env 파일을 사용합니다.

Antigravity 창 (탐색기)의 왼쪽에 있는 sample.env 파일을 찾습니다.

sample.env를 열고 GCP_PROJECT_ID 필드를 실제 Google Cloud 프로젝트 ID로 업데이트합니다. 파일은 다음과 비슷하게 표시됩니다.

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

OpenTelemetry 통합을 사용 설정하여 에이전트의 도구 호출 및 추론 흐름에 관한 세부 trace를 캡처합니다.

4. 시뮬레이터 에이전트를 Agent Runtime에 배포

이제 에이전트 개발 키트 (ADK)를 사용하여 에이전트를 에이전트 런타임에 배포합니다.

종속 항목 설치

uv sync

Agent Runtime에 배포

1. adk deploy 명령어를 실행합니다. 이 단계에서는 에이전트를 패키징하고 Google Cloud (에이전트 런타임)에 배포합니다.

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

실행하는 데 최대 5분이 걸릴 수 있습니다. 결국 다음과 같은 출력이 표시됩니다.

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

생성된 에이전트 런타임 ID를 기록해 둡니다. 이 값은 나중에 필요합니다.

2. 웹브라우저에서 에이전트 런타임 콘솔을 엽니다. 원격 분석 수집이 사용 설정된 상태로 에이전트 런타임에서 simulator_agent이 실행됩니다.

5. 알림 정책 설정

에이전트 런타임 오류를 자동으로 감지하려면 Google Cloud 콘솔에서 로그 기반 알림을 만듭니다.

1. Cloud Monitoring - 알림 콘솔로 이동합니다.

2. 알림 채널 수정을 클릭합니다. 이메일 유형으로 스크롤한 다음 개인 이메일로 전송할 이메일 알림 채널을 만듭니다. 저장을 클릭합니다.

3. 알림 대시보드로 돌아가 정책 만들기를 클릭합니다.
4. 화면 오른쪽에 있는 로그 기반 알림 만들기를 클릭합니다.

5. 로그 탐색기로 리디렉션됩니다. 다음 로그 쿼리를 붙여넣고 를 프로젝트 ID로 바꿉니다.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

이 로그 쿼리는 에이전트 런타임 내에서 Error 로그를 찾습니다. 여기서 ReasoningEngine은 에이전트 런타임의 기본 API 이름입니다.

6. 쿼리 실행을 클릭합니다. 아직 로그가 표시되지 않습니다. 이는 예상된 동작입니다.
7. 결과 툴바에서 작업을 클릭한 다음 로그 알림 만들기를 클릭합니다.

8. 로그 기반 알림을 구성합니다. 알림에 이름을 지정한 다음 심각도 수준을 오류로 설정합니다.

9. '알림 빈도 설정' 섹션에서 다음을 클릭합니다 (기본값 유지).

10. 알림 수신 대상에서 방금 설정한 이메일 알림 채널 (예: My Email))를 제공합니다.
11. 저장을 클릭합니다.

6. 인시던트 트리거

이제 에이전트가 배포되고 모니터링되므로 오류가 발생하는 방식으로 마라톤 시뮬레이션을 호출해 보겠습니다.

1. Google Cloud 콘솔에서 에이전트 런타임 콘솔로 이동합니다.
2. simulator_agent 아이콘을 클릭합니다.
3. 상단 툴바에서 Playground를 클릭합니다. 이렇게 하면 ADK 에이전트와의 새 세션이 시작됩니다.

4. 세션 채팅 창에서 Test Simulation를 입력하고 Enter 키를 눌러 프롬프트를 보냅니다.

이렇게 하면 마라톤 시뮬레이션이 시작되어 계획된 경로를 따라 수천 명의 시뮬레이션된 러너를 추적합니다. 시뮬레이션에서 레이스의 여러 '구간'을 평가하므로 get_runner_telemetry 및 analyze_medical_risk에 대한 여러 도구 호출이 표시됩니다.

몇 분 후 에이전트가 실행 중지되고 응답 없음이 반환됩니다.

5. 1분 이내에 받은편지함에 이메일이 도착하여 에이전트 내의 새 인시던트를 알립니다.

사고 보기를 클릭하여 Cloud Monitoring 콘솔을 엽니다. 다음 페이지로 이동하여 콘솔에서 문제를 조사합니다.

7. 콘솔에서 사고 조사

1. Cloud Monitoring 콘솔에서 인시던트를 확인합니다. 시뮬레이터 에이전트에서 발생하는 오류 로그가 표시됩니다.

이 뷰에서는 에이전트가 정확히 언제 실패했는지 확인하기 어렵습니다. 에이전트의 기본 도구 호출 및 추론 흐름을 확인하려면 에이전트의 트레이스를 검사합니다.

2. 에이전트 런타임 콘솔을 다시 엽니다. simulator_agent를 클릭한 다음 트레이스 탭을 엽니다.

3. 목록에서 가장 최근의 트레이스를 클릭합니다. 그런 다음 오른쪽 상단에서 타임라인을 클릭합니다. 개별 '스팬'이 포함된 트레이스 뷰가 표시됩니다. 하나의 스팬은 에이전트의 워크플로 내에서 모델 또는 도구 호출을 나타냅니다.

4. 추적 보기에서 마지막 스팬을 클릭합니다. 빨간색이어야 합니다.
5. Stacktrace를 클릭합니다. Gemini API 모델 호출과 관련된 오류 로그가 표시됩니다. 구체적으로는 400: Invalid Argument 오류입니다. 이는 시뮬레이터 에이전트가 Gemini API에 전송한 페이로드에 요청 수준 문제가 있음을 나타냅니다.

8. [선택사항] Cloud Assist 조사를 사용하여 디버깅

Gemini Cloud Assist (비공개 프리뷰)에 허용 목록으로 추가된 경우에만 다음 단계를 따르세요. 그렇지 않으면 다음 페이지로 이동합니다.

1. 실패한 스팬 내에서 로그 및 이벤트를 클릭합니다. 반짝이는 버튼이 옆에 있는 '예외' 로그를 찾습니다. 그런 다음 로그 조사를 클릭합니다.

2. 그러면 화면 오른쪽의 사이드바에서 Cloud Assist 조사가 시작됩니다. 로딩하는 데 3~5분 정도 걸립니다.

3. 완료되면 조사를 엽니다.

4. 조사 요약을 확인합니다.

5. 아래로 스크롤하여 가설을 확인합니다. Gemini Cloud Assist는 Gemini API 400 오류를 발생시키는 시뮬레이터 에이전트의 agent.py 파일의 특정 행을 식별해야 합니다.

에이전트의 소스 코드를 열고 Antigravity를 사용하여 문제의 근본 원인을 찾아보겠습니다. 다음 페이지로 이동합니다.

9. Antigravity를 사용하여 문제의 근본 원인을 파악하고 패치하기

1. Antigravity를 다시 엽니다.
2. 화면 오른쪽 상단에서 에이전트 관리자를 엽니다.

3. 모델이 Gemini 3 Flash 및 계획 모드로 설정되어 있는지 확인합니다.

4. 다음 프롬프트를 입력하고 Enter 키를 누릅니다.

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.    

agent.py에서 코드를 검사하고 GitHub에서 관련 문제를 검색하는 Antigravity가 표시됩니다.

Gemini API 400 오류의 근본 원인은 Gemini 3 Flash의 입력 컨텍스트 토큰 한도인 약 1백만 개를 초과하기 때문입니다. 이 문제가 발생하는 이유는 시뮬레이터 에이전트 도구 호출의 대규모 응답을 효과적으로 요약하기 위해 EventCompaction을 충분히 자주 트리거하지 않기 때문입니다.

이 문제를 해결하기 위해 Antigravity는 특정 토큰 수에 도달하면 EventsCompactionConfig에 token_threshold 매개변수를 추가하여 각 호출 내에서 컨텍스트를 주기적으로 압축하도록 제안해야 합니다.

이는 이 GitHub 문제에서 제안된 수정사항과 일치합니다.

agent.py.에 수정사항 적용

다음과 비슷한 내용이 표시되는지 확인합니다.

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

중요한 점은 token_threshold 및 event_retention_size를 설정해야 한다는 것입니다.

10. 수정사항 재배포 및 검증

이제 ADK 에이전트의 EventCompactionConfig에 token_threshold 수정사항을 적용했으므로 시뮬레이터 에이전트를 에이전트 런타임에 다시 배포할 수 있습니다.

1. Antigravity –> New Terminal을 엽니다.
2. 환경 변수를 설정합니다. AGENT_RUNTIME_ID은 simulator_agent의 전체 리소스 이름이어야 합니다. 에이전트 런타임 콘솔의 에이전트 목록에서 확인할 수 있습니다.

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

3. 에이전트를 다시 배포합니다.

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

실행되기까지 몇 분 정도 걸립니다. 성공하면 다음이 표시됩니다.

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

4. 에이전트 런타임 콘솔을 엽니다. simulator_agent을 다시 엽니다. Playground를 클릭합니다.
5. 동일한 프롬프트(Test Simulation)를 입력한 다음 Enter 키를 누릅니다.
6. 전체 백엔드 마라톤 시뮬레이션을 실행하는 데 몇 분 정도 걸립니다. 여러 도구 호출이 표시됩니다. 결국 다음과 같은 응답이 표시됩니다.

이는 시뮬레이터가 성공적으로 실행되었음을 나타냅니다. ✅

7. 해당 ADK 세션의 트레이스 뷰를 엽니다.
8. 빨간색 오류 없이 모든 '파란색' 스팬이 표시됩니다. 세션의 총 토큰 수가 Gemini API의 1백만 컨텍스트 토큰 한도를 초과하는 것을 확인할 수 있습니다. 이제 EventCompaction가 각 호출 내에서 충분히 자주 실행되어 개별 모델 호출의 전체 컨텍스트 한도에 도달하지 않으므로 괜찮습니다.

🎊 축하합니다! 시뮬레이터 에이전트의 오류가 수정되었습니다.

11. 삭제

Google Cloud 계정에 비용이 청구되지 않도록 하려면 이 Codelab 중에 만든 리소스를 삭제합니다.

에이전트 런타임 앱 삭제

콘솔을 통해 또는 gcloud 명령어를 사용하여 추론 엔진 인스턴스를 삭제할 수 있습니다 (리소스 이름이 있는 경우). 간단하게 콘솔을 사용하세요.

1. Agent Runtime 페이지로 이동합니다.
2. simulator_agent를 선택하고 오른쪽의 점 3개 버튼을 클릭합니다.
3. 삭제를 클릭합니다.

Cloud Monitoring 정책 삭제

1. Cloud Monitoring 콘솔 -> 알림으로 이동합니다.
2. 정책까지 아래로 스크롤한 다음 점 3개 버튼을 클릭하여 정책을 삭제합니다.

12. 🎊 수고하셨습니다.

축하합니다. Google Cloud에서 AI 에이전트를 성공적으로 디버그했습니다.

학습한 내용

• Agent Runtime에 에이전트를 배포하는 방법
• Cloud Monitoring 알림을 사용하여 오류를 감지하는 방법
• Cloud Logging 및 에이전트 런타임의 추적 보기를 사용하여 활성 인시던트를 탐색하는 방법
• Gemini Cloud Assist를 사용하여 실패를 조사하는 방법
• Antigravity를 사용하여 에이전트 버그의 근본 원인을 파악하고 패치를 적용하는 방법
• ADK 이벤트 압축을 미세 조정하여 장기 실행되고 도구가 많은 에이전트 턴을 처리하는 방법

다음 단계

• Agent Runtime에 대해 자세히 알아보세요.
• 에이전트 개발 키트에 대해 자세히 알아보세요.
• Cloud Monitoring의 알림에 대해 자세히 알아보세요.
• Gemini Cloud Assist 자세히 알아보기