1. 학습할 내용
ADK 마스터 클래스에 오신 것을 환영합니다. 멀티 에이전트 시스템 여정을 시작하세요.
이제 흥미로운 AI 에이전트의 세계로 들어가 보겠습니다. 질문에만 답하는 단순한 챗봇은 잊으세요. Google은 Agent Development Kit (ADK)를 심층적으로 연구하여 복잡한 작업을 수행하기 위해 추론하고, 계획하고, 도구를 사용할 수 있는 정교한 자율 시스템을 구축하고 있습니다.
이 튜토리얼을 마치면 다음을 할 수 있습니다.
- 첫 번째 AI 에이전트 빌드: 사용자의 요구사항을 이해하고, Google 검색과 같은 도구를 사용하고, 자세하고 유용한 대답을 생성할 수 있는 완전한 기능을 갖춘 에이전트를 처음부터 빌드합니다.
- 맞춤 도구 마스터하기: 에이전트를 자체 맞춤 함수 및 API에 연결하여 에이전트의 진정한 힘을 발휘하세요. 상담사에게 실시간 날씨 예보와 같은 실시간 데이터를 가져오도록 가르칩니다.
- 멀티 에이전트 시스템 구성: 에이전트가 다른 전문 에이전트에게 작업을 위임하여 함께 작동하는 AI 전문가 팀을 만드는 혁신적인 개념인 '도구로서의 에이전트' 패턴을 알아봅니다.
- 복잡한 워크플로 오케스트레이션: 단순한 위임을 넘어 라우터, 순차적 체인, 루프, 병렬 실행과 같은 고급 패턴을 마스터하여 거의 모든 요청을 처리할 수 있는 강력하고 효율적이며 지능적인 애플리케이션을 빌드하세요.
- 에이전트에게 메모리 제공: 대화 메모리의 중요한 역할을 이해하여 에이전트가 후속 질문을 처리하고, 피드백에서 학습하고, 다단계 작업을 원활하게 관리할 수 있도록 지원합니다.
지금 시작해 보세요. 🚀
2. GCP 및 Gemini API 키 설정
GCP 프로젝트 및 Gemini API 키 설정
AI 에이전트를 지원하려면 기반을 제공하는 Google Cloud 프로젝트와 Google의 강력한 모델에 액세스할 수 있는 Gemini API 키가 필요합니다.
1단계: 결제 계정 사용 설정하기
- 배포에 필요한 5달러 크레딧으로 결제 계정을 청구합니다. Gmail 계정으로 로그인해야 합니다.
2단계: 새 GCP 프로젝트 만들기
- Google Cloud 콘솔로 이동하여 새 프로젝트를 만듭니다.
- Google Cloud 콘솔로 이동하여 새 프로젝트를 만듭니다.
- 왼쪽 패널을 열고
Billing을 클릭하여 결제 계정이 이 GCP 계정에 연결되어 있는지 확인합니다.
이 페이지가 표시되면 manage billing account을 확인하고 Google Cloud 무료 체험판을 선택하여 연결합니다.
3단계: Gemini API 키 생성하기
키를 보호하려면 키가 있어야 합니다.
- Google AI Studio(https://aistudio.google.com/)로 이동합니다.
- Gmail 계정으로 로그인합니다.
- 'API 키 가져오기' 버튼을 클릭합니다. 이 버튼은 일반적으로 왼쪽 탐색 창이나 오른쪽 상단에 있습니다.
- 'API 키' 대화상자에서 '새 프로젝트에 API 키 만들기'를 클릭합니다.
- 결제 계정이 설정된 새로 만든 프로젝트를 선택합니다.
- 새 API 키가 생성됩니다. 이 키를 즉시 복사하여 비밀번호 관리자나 보안 메모와 같은 안전한 곳에 임시로 저장합니다. 다음 단계에서 사용할 값입니다.
3. 세션 1: 러너를 사용한 첫 번째 에이전트
기본부터 시작해 보겠습니다. 여기서는 첫 번째 간단한 에이전트인 day_trip_agent를 만듭니다. 이 에이전트의 목적은 예산 고려사항을 포함하여 사용자의 요청에 따라 하루 종일 여행 일정을 생성하는 것입니다. 이 예에서는 ADK에서 에이전트 상호작용의 세 가지 핵심 구성요소를 소개합니다.
- 에이전트: 작업의 핵심 두뇌입니다. 프롬프트는 지침 (성격과 미션), 사용하는 AI 모델 (예: Gemini), 액세스할 수 있는 도구로 정의됩니다.
- 세션: 대화의 메모리입니다. 상호작용 기록 (사용자 메시지 및 에이전트 응답)을 저장하여 연속적인 대화를 지원합니다.
- 러너: 작업을 실행하는 엔진입니다. 에이전트와 세션을 가져와 새 사용자 쿼리를 처리하고 응답을 생성하는 단계를 오케스트레이션합니다.
➡️ 노트북에서 찾을 수 있는 위치
👉 이는 1부: 첫 번째 에이전트 - 당일치기 여행 지니 🧞의 셀에 해당합니다.🌟
- 에이전트 정의:
create_day_trip_agent()함수를 찾습니다. 여기에서 에이전트가 정의됩니다. 자세한 지침 문자열을 확인하세요. 이는 에이전트의 행동 방식을 알려주는 프롬프트입니다. 또한 Google 검색이라는 첫 번째 도구를 제공합니다. - 도우미 함수:
run_agent_query()도우미 함수가 여기에 정의되어 있습니다. 이 유틸리티는 노트북 전체에서 쿼리 실행을 간소화하는 데 사용됩니다. - 테스트 실행:
run_day_trip_genie()함수는 사용자가 '저렴한' '편안한' 당일치기 여행을 요청하는 것을 시뮬레이션합니다. 에이전트는 안내와 Google 검색 도구를 사용하여 적합한 위치를 찾고 마크다운 형식의 여행 일정을 만듭니다.
➡️ 작업: day_trip_agent의 안내 프롬프트를 검토합니다. 테스트 질문의 '저렴한' 여행 요청이 '예산 인식'이라는 에이전트 가이드라인과 어떻게 직접적으로 관련되는지 확인하세요.
4. 세션 2: 맞춤 도구 🛠️
Google 검색은 강력하지만 AI 에이전트의 진정한 잠재력은 고유한 데이터 소스, API 또는 맞춤 로직에 연결할 때 발휘됩니다. 이 섹션에서는 간단한 Python 함수에서 맞춤 도구를 만듭니다.
함수 도구에서 가장 중요한 부분은 docstring입니다. ADK는 docstring을 자동으로 파싱하여 도구의 기능, 허용되는 매개변수 (Args), 반환되는 항목 (Returns)을 이해합니다. 대규모 언어 모델 (LLM)은 이 설명을 읽고 도구를 사용할 시기와 방법을 결정합니다.
➡️ 노트북에서 찾을 수 있는 위치
👉 2.1 간단한 함수 도구: 실시간 날씨 API 호출의 셀에 해당합니다. 🌟
- 도구 정의:
get_live_weather_forecast(location: str)함수는 맞춤 도구의 핵심입니다. 도시 이름을 가져와 공개 국립 기상청 API를 호출하고 온도와 일기 예보가 포함된 딕셔너리를 반환합니다. - 에이전트 정의: weather_agent가 생성되고 초기화 중에
tools=[get_live_weather_forecast]를 전달하여 새로운 도구가 장착됩니다. 에이전트의 안내에는 야외 활동을 제안하기 전에 이 도구를 사용하라고 명시적으로 나와 있습니다. - 테스트 실행: '타호 호수 근처에서 하이킹을 하고 싶은데 날씨가 어때?'라는 질문은 안내에 따라 에이전트가
get_live_weather_forecast도구를 사용하도록 직접 트리거합니다.
➡️ 작업: get_live_weather_forecast 함수의 독스트링과 weather_agent의 안내를 읽습니다. 이 둘 사이의 직접적인 관계를 참고하세요.
5. 세션 3: 도구로서의 상담사 🧑🍳
전문가 팀을 만들 수 있는데 왜 단일 모놀리식 에이전트를 빌드해야 할까요? Agent-as-a-Tool 패턴은 오케스트레이터 또는 라우터라고도 하는 기본 에이전트가 더 집중된 다른 에이전트에게 작업을 위임하는 복잡한 시스템을 구축하는 강력한 방법입니다.
이 패턴을 사용하면 재사용 가능한 모듈식 에이전트를 만들 수 있습니다. 예를 들어 데이터베이스 쿼리에 능숙한 에이전트, 창작에 능숙한 에이전트, 친절한 컨시어지 역할을 하는 에이전트가 있을 수 있습니다. 오케스트레이터의 역할은 사용자의 요청을 이해하고 올바른 전문가에게 라우팅하는 것입니다.
➡️ 노트북에서 찾을 수 있는 위치
👉 이는 2.2 상담사를 도구로 활용: 전문가 컨설트 🧑🍳의 셀에 해당합니다.🌟
이 예시에서는 정교한 다층 에이전트 시스템을 빌드합니다.
- 전문가:
- food_critic_agent: 음식점 추천만 제공하는 고도로 전문화된 에이전트입니다.
- db_agent: 호텔 정보를 데이터베이스에서 쿼리하는 척하는 모의 에이전트입니다.
- concierge_agent: 공손한 컨시어지 역할을 하는 중간 수준 상담사입니다. 중요한 점은
food_critic_agent가 자체 도구로 있다는 것입니다.
- 오케스트레이터 (
trip_data_concierge_agent): 사용자가 상호작용하는 최상위 에이전트입니다. 이 모델의 안내는 이 모델을 '마스터 여행 계획 도구'로 만들고 다른 에이전트를 호출하는 두 가지 도구가 제공됩니다.- call_db_agent:
db_agent를 호출하는 함수입니다. - call_concierge_agent:
concierge_agent를 호출하는 함수입니다.
- call_db_agent:
- 흐름:
run_trip_data_concierge()에서 실행되는 테스트는 전체 위임 체인을 보여줍니다.- 사용자가 오케스트레이터에게 호텔과 인근 식당을 요청합니다.
- 오케스트레이터의 지침에 따라 먼저
call_db_agent도구를 사용하여 호텔 데이터를 가져옵니다. - 그런 다음 오케스트레이터가
call_concierge_agent도구를 사용하여 추천을 가져옵니다. concierge_agent는 요청을 받으면 자체 도구인food_critic_agent를 사용하여 식당 아이디어를 얻습니다.
음식 평론가의 대답은 컨시어지로 다시 전달되고, 컨시어지는 이를 정중하게 포맷하여 오케스트레이터로 다시 전송합니다. 오케스트레이터는 최종적으로 이를 사용자에게 표시합니다.
➡️ 작업: run_trip_data_concierge()에서 테스트 실행의 실행 흐름을 추적합니다. TOOL CALLED 출력에 오케스트레이터에서 전문가까지의 위임 체인이 표시되는 방식을 확인합니다. 이는 순차적인 명령 체인입니다.
6. 세션 4: 에이전트 메모리 🧠
진정한 인텔리전트 에이전트는 일회성 질문에 응답하는 것 이상의 작업을 수행해야 합니다. 대화를 기억하고, 맥락을 이해하고, 피드백에 적응해야 합니다. 이는 적절한 세션 관리를 통해 달성됩니다. '루프 에이전트'는 메모리를 기반으로 지속적인 대화 루프에 참여하는 에이전트라고 생각하면 됩니다.
여러 개의 순차적 쿼리에 동일한 세션 객체를 사용하면 에이전트가 대화의 전체 기록을 '볼' 수 있습니다. 이를 통해 후속 질문을 처리하고, 피드백을 기반으로 자체적으로 수정하고, 다단계 작업을 계획할 수 있습니다.
➡️ 노트북에서 찾을 수 있는 위치
👉 3부: 메모리가 있는 에이전트 - 적응형 플래너 🗺️의 셀에 해당합니다. 🌟
- 에이전트 정의:
create_multi_day_trip_agent()함수는 여행을 점진적으로 계획하도록 설계된 에이전트를 정의합니다. 이 앱의 안내는 맥락을 기억하고, 피드백을 처리하고, 하루씩 계획하는 것을 강조합니다.
시나리오 3a: 메모리가 있는 에이전트 (✅)
이 테스트는 run_adaptive_memory_demonstration() 함수에서 실행됩니다.
- 단일
trip_session가 생성되고 연속된 세 턴 동안 재사용됩니다. - 1턴: 사용자가 2일간의 여행 계획을 시작합니다.
- 2턴: 사용자가 의견을 제공합니다 ('성에는 별로 관심이 없어'). 에이전트가 1번 대화의 기억을 가지고 있으므로 계획의 어느 부분을 변경해야 하는지 이해하고 대안을 제공합니다.
- 3번째 턴: 사용자가 변경사항을 확인하고 다음 단계를 묻습니다. 에이전트는 모든 것을 기억하고 2일차 계획을 진행합니다.
시나리오 3b: 메모리가 없는 에이전트 (❌)
이 테스트는 run_memory_failure_demonstration() 함수에서 실행됩니다.
이는 의도적으로 실수를 함으로써 세션 관리의 중요성을 보여줍니다. 턴마다 새 세션이 생성됩니다.
- 1턴: 사용자가 session_one에서 여행을 시작합니다. 상담사가 올바르게 응답합니다.
- 2번째 턴: 사용자가 2일차 계획을 요청하지만 쿼리가 완전히 새로운 session_two에서 전송됩니다. 이 새 세션에는 기록이 없으므로 상담사가 혼란스러워합니다. 기억 상실증에 걸렸어요. 계획 중인 여행을 알 수 없습니다.
작업: run_adaptive_memory_demonstration() 및 run_memory_failure_demonstration()의 에이전트 응답을 비교합니다. 이것이 노트북에서 가장 중요한 개념입니다. 하나의 연속적인 대화에는 하나의 연속적인 세션이 필요합니다.
7. 세션 5: 라우터 에이전트 🚏
한 명의 상담사가 할 수 있는 일은 제한적입니다. 정말로 복잡한 사용자 요청을 처리하려면 전문 상담사 팀이 필요합니다. 하지만 특정 질문에 어떤 에이전트를 사용해야 하는지 어떻게 알 수 있을까요? 이때 라우터 에이전트가 필요합니다.
라우터 에이전트는 '마스터' 에이전트 또는 디스패처 역할을 합니다. 이 모델의 유일한 목적은 수신되는 사용자 질문을 분석하고 작업에 가장 적합한 전문가 상담사 (또는 상담사 워크플로)를 결정하는 것입니다. 질문에 직접 답변하지 않고 올바른 다운스트림 상담사에게 라우팅합니다.
예를 들어 '최고의 스시'에 관한 질문은 foodie_agent로 전달되어야 하고 '이번 주말 콘서트'에 관한 질문은 weekend_guide_agent에서 처리해야 합니다.
➡️ 노트북에서 이 내용을 찾을 수 있는 위치:
👉 이 개념은 전체 노트북의 핵심이지만 1부: 멀티 에이전트 혼란 - 순차적 워크플로 🧠→🤖→🤖에서 처음 소개됩니다. 🌟
- 에이전트 정의: 코드 셀은 여러 전문가 에이전트 (day_trip_agent, foodie_agent, transportation_agent)와 가장 중요한 router_agent를 정의합니다. router_agent의 프롬프트에 주의하세요. 작업에 가장 적합한 에이전트의 이름만 반환하도록 명시적으로 요청합니다.
- 실행 로직: run_sequential_app 함수는 먼저 router_agent를 호출하여 결정 (chosen_route)을 가져온 다음
if/elif블록에서 해당 결정을 사용하여 적절한 전문가 에이전트를 실행하는 방법을 보여줍니다.
8. 세션 6: SequentialAgent ⛓️
일부 작업에는 특정 순서로 여러 단계가 필요합니다. 예를 들어 'Palo Alto에서 가장 맛있는 초밥집을 찾아줘. 그리고 거기 가는 방법을 알려줘.'라고 말할 수 있습니다. 이 절차는 두 단계로 이루어져 있습니다. 먼저 식당을 찾고 두 번째로 길을 찾습니다.
ADK는 SequentialAgent를 사용하여 이를 관리하는 깔끔하고 강력한 방법을 제공합니다. 이는 사전 정의된 순서로 하위 에이전트 목록을 실행하는 특수 워크플로 에이전트입니다.
마법은 공유 상태에 있습니다. 시퀀스에 있는 한 에이전트의 출력을 공유 상태 딕셔너리에 자동으로 저장한 다음 다음 에이전트의 입력으로 사용할 수 있으므로 단계 간에 정보를 전달하기 위해 복잡한 수동 코드를 사용할 필요가 없습니다.
➡️ 노트북에서 이 내용을 찾을 수 있는 위치:
👉 이 내용은 파트 2 (ADK 방식): SequentialAgent를 사용한 멀티 에이전트 혼란 🧠→⛓️→🤖에서 다룹니다. 🌟
- 에이전트 리팩터링: 이 섹션의 첫 번째 코드 셀에서
foodie_agent및transportation_agent의 주요 변경사항을 확인하세요.- 이제
foodie_agent에output_key="destination"이 있습니다. 이렇게 하면 ADK가 최종 답변을 공유 상태의destination이라는 변수에 저장합니다. - 이제
transportation_agent의 명령어 프롬프트에{destination}자리표시자가 있습니다. ADK는 공유 상태의 값을 이 자리표시자에 자동으로 삽입합니다.
- 이제
- 워크플로 정의:
find_and_navigate_agent는 SequentialAgent로 정의되며, sub_agents는 [foodie_agent,transportation_agent]로 설정되어 정확히 이 순서로 실행됩니다. - 실행 단순화: 이 섹션의
run_sequential_app함수를 살펴보세요. 복잡한if/elif로직이 사라졌습니다. 이제find_and_navigate_agent이 호출 가능한 단일 단위로 처리되며 ADK가 내부 순차 단계를 자동으로 처리합니다.
9. 세션 7: LoopAgent 🔁
모든 문제에 간단한 일회성 해결책이 있는 것은 아닙니다. 때로는 특정 제약 조건을 충족할 때까지 솔루션을 제안하고, 비판하고, 개선해야 합니다.
이를 위해 ADK는 LoopAgent를 제공합니다. 이 워크플로 에이전트는 특정 조건이 충족될 때까지 하위 에이전트 시퀀스를 반복적으로 실행합니다. 자체 작업을 계획하고 비판하고 개선할 수 있는 '완벽주의자' 에이전트를 빌드하는 데 적합합니다.
다이어그램은 Planner Agent가 먼저 계획을 만드는 것을 보여줍니다. 그런 다음 LoopAgent을 입력합니다. Critic Agent에서 요금제를 확인합니다. 결함이 있으면 Refiner Agent에서 새 버전을 만들고 루프가 반복됩니다. 계획이 적절하면 Refiner Agent가 exit_loop 도구를 호출하고 최종적으로 검증된 계획이 반환됩니다.
➡️ 노트북에서 이 내용을 찾을 수 있는 위치:
👉 자세한 내용은 LoopAgent로 아이디어 반복하기 🧠→🔁→🤖를 참고하세요. 🌟
- 핵심 에이전트: 워크플로에서
planner_agent,critic_agent,refiner_agent를 사용합니다. - 루프 정의:
refinement_loop는critic_agent,refiner_agent,sets max_iterations=3을 오케스트레이션하는 LoopAgent로 정의됩니다. - 종료 조건:
critic_agent가 계획을 승인하면 루프가 종료되어refiner_agent가 맞춤exit_loop도구를 호출합니다.
10. 세션 8: ParallelAgent ⚡️
효율성이 중요합니다. 사용자가 한 번에 관련 없는 여러 정보를 요청하는 경우 이러한 검색을 하나씩 실행하면 속도가 느립니다.
ParallelAgent이 해결 방법입니다. 이 워크플로 에이전트는 하위 에이전트 목록을 동시에 실행합니다. 모든 병렬 작업이 완료되면 결과를 수집하여 하나의 포괄적인 대답으로 종합할 수 있습니다.
이 다이어그램은 ParallelAgent가 단일 쿼리를 가져와 작업을 세 개의 동시 트랙으로 포크하는 것을 보여줍니다. museum_finder, concert_finder, restaurant_finder는 모두 동시에 실행됩니다. 세 가지가 모두 완료되면 개별 결과 (공유 상태에 저장됨)가 결합되어 최종 합성 에이전트에 전달되며, 이 에이전트는 결과를 하나의 답변으로 결합합니다.
➡️ 노트북에서 이 내용을 찾을 수 있는 위치:
👉 이 워크플로는 ParallelAgent를 사용한 병렬 처리 🧠→⚡️→🤖🤖🤖 섹션에 자세히 설명되어 있습니다. 🌟
- 전문가 에이전트: 고유한 output_key (예: museum_result)가 있는 전문가 에이전트 3개가 정의됩니다.
- 병렬 워크플로: parallel_research_agent는 ParallelAgent로 정의되며, 세 개의 검색 에이전트가 sub_agents로 나열됩니다.
- 합성 단계: 병렬 단계가 끝나면 최종 synthesis_agent가 자리표시자 (
{museum_result},{concert_result}등)를 사용하여 공유 상태의 모든 결과를 수집하여 깔끔한 요약을 작성합니다.
11. 부록: ADK 웹 - 🍎 Mac/Linux
이 가이드에서는 로컬 머신에서 ADK Day Trip Planning Agent를 설정하고 실행하는 방법을 안내합니다.
기본 요건
- Python 3.8 이상
- Python 3.9 이상: google-adk==1.5.0 (모든 기능을 갖춘 최신 버전)을 설치합니다.
- Python 3.8: google-adk==0.3.0 (호환 버전)을 설치합니다.
- Google AI Studio API 키
- 인터넷 연결
1단계: 저장소 클론
터미널을 열고 다음을 실행합니다.
git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic
2단계: 가상 환경 설정 및 종속 항목 설치
옵션 A: 자동 설정 (권장)
# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh
옵션 B: 수동 설정
# Create virtual environment
python3 -m venv .adk_env
# Activate virtual environment
source .adk_env/bin/activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
3단계: 🔥 중요 - 환경 변수 만들기
⚠️ 이 단계를 건너뛰지 마세요. agent/ 디렉터리에 .env 파일을 만듭니다.
# Create the .env file
touch agent/.env
# Open it in your default text editor
open agent/.env
파일에 다음 줄을 추가합니다.
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
🚨 중요: your_actual_api_key_here를 실제 API 키로 바꾸세요.
4단계: 가상 환경 활성화 (아직 활성화되지 않은 경우)
source .adk_env/bin/activate
터미널 프롬프트 시작 부분에 (.adk_env)가 표시됩니다.
5단계: ADK 웹 인터페이스 실행
adk web
6단계: 브라우저 열기
- 브라우저를 열고 터미널에 표시된 URL (일반적으로
http://localhost:8000)로 이동합니다. - 왼쪽 상단의 드롭다운에서
agent를 선택합니다. - 일일 여행 계획 에이전트와 채팅을 시작하세요.
와 같은 대화가 표시됩니다.
환경 비활성화
프로젝트 작업을 완료한 후에는 다음 단계를 따르세요.
deactivate
이 명령어는 Mac/Linux와 Windows에서 동일하게 작동합니다. 터미널 프롬프트에서 (.adk_env) 접두사가 사라집니다.
Mac 문제 해결
- Python을 찾을 수 없음:
python대신python3사용 - 권한이 거부됨: 스크립트를 실행하기 전에
chmod +x setup_venv.sh를 실행하세요.
12. 부록: ADK 웹 - 🪟 Windows 사용자용
이 가이드에서는 로컬 머신에서 ADK Day Trip Planning Agent를 설정하고 실행하는 방법을 안내합니다.
기본 요건
- Python 3.8 이상
- Python 3.9 이상: google-adk==1.5.0 (모든 기능을 갖춘 최신 버전)을 설치합니다.
- Python 3.8: google-adk==0.3.0 (호환 버전)을 설치합니다.
- Google AI Studio API 키
- 인터넷 연결
1단계: 저장소 클론
명령 프롬프트 또는 PowerShell을 열고 다음을 실행합니다.
git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic
2단계: 가상 환경 설정 및 종속 항목 설치
옵션 A: 자동 설정 (권장)
# Run the setup script in Command Prompt
setup_venv.bat
옵션 B: 수동 설정
명령 프롬프트:
# Create virtual environment
python -m venv .adk_env
# Activate virtual environment
.adk_env\Scripts\activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
PowerShell:
# Create virtual environment
python -m venv .adk_env
# Activate virtual environment
.adk_env\Scripts\Activate.ps1
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
3단계: 🔥 중요 - 환경 변수 만들기
⚠️ 이 단계를 건너뛰지 마세요. agent/ 디렉터리에 .env 파일을 만듭니다.
# Create the .env file
type nul > agent\.env
# Open it in Notepad
notepad agent\.env
파일에 다음 줄을 추가합니다.
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
🚨 중요: your_actual_api_key_here를 실제 API 키로 바꾸세요.
4단계: 가상 환경 활성화 (아직 활성화되지 않은 경우)
명령 프롬프트:
.adk_env\Scripts\activate
PowerShell:
.adk_env\Scripts\Activate.ps1
프롬프트 시작 부분에 (.adk_env)가 표시됩니다.
5단계: ADK 웹 인터페이스 실행
adk web
6단계: 브라우저 열기
- 브라우저를 열고 터미널에 표시된 URL (일반적으로
http://localhost:8000)로 이동합니다. - 왼쪽 상단의 드롭다운에서
agent를 선택합니다. - 일일 여행 계획 에이전트와 채팅을 시작하세요.
Windows 문제 해결
- PowerShell 실행 정책 오류:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser실행
와 같은 대화가 표시됩니다.
환경 비활성화
프로젝트 작업을 완료한 후에는 다음 단계를 따르세요.
deactivate
이 명령어는 Mac/Linux와 Windows에서 동일하게 작동합니다. 터미널 프롬프트에서 (.adk_env) 접두사가 사라집니다.