ADK를 사용하여 Live API 시작하기

이 튜토리얼에서는 에이전트를 만들고 에이전트 개발 키트(ADK) 스트리밍을 사용하여 음성 및 영상 커뮤니케이션을 사용 설정하는 방법을 보여줍니다. ADK를 설치하고, Google 검색을 사용하는 기본 에이전트를 설정하고, adk web 도구로 에이전트를 실행합니다.

시작하기 전에

이 가이드에서는 Windows, macOS 또는 Linux 환경에서 터미널을 사용한 경험이 있다고 가정합니다.

환경 설정 및 ADK 설치

이 섹션에서는 로컬 환경을 준비하는 방법을 보여줍니다.

  1. 가상 환경을 만들고 활성화합니다. 가상 환경을 사용하는 것이 좋습니다.

    # Create the environment
python -m venv .venv

# Activate the environment in each new terminal
# For macOS or Linux:
source .venv/bin/activate
# For Windows CMD:
.venv\Scripts\activate.bat
# For Windows PowerShell:
.venv\Scripts\Activate.ps1

  2. ADK를 설치합니다.

    pip install google-adk

프로젝트 구조 만들기

에이전트에 필요한 디렉터리와 파일을 만듭니다.

  1. 빈 파일로 다음 폴더 구조를 만듭니다.

    프로젝트 구조 다이어그램: adk-streaming 폴더에는 app 폴더가 포함되어 있고, app 폴더에는 .env 파일과 google_search_agent 폴더가 포함되어 있으며, google_search_agent 폴더에는 __init__.py 및 agent.py 파일이 포함되어 있습니다.

  2. 다음 코드를 app/google_search_agent/agent.py 파일에 추가합니다. 이 파일은 에이전트의 로직을 정의합니다. root_agent를 정의해야 합니다.

    from google.adk.agents import Agent
from google.adk.tools import google_search  # Import the tool

root_agent = Agent(
  # A unique name for the agent.
  name="basic_search_agent",
  # The Large Language Model (LLM) that agent will use.
  # Please fill in the latest model id that supports live from
  # https://google.github.io/adk-docs/get-started/streaming/quickstart-streaming/#supported-models
  model="...",  # for example: model="gemini-live-2.5-flash-preview-native-audio-09-2025"
  # A short description of the agent's purpose.
  description="Agent to answer questions using Google Search.",
  # Instructions to set the agent's behavior.
  instruction="You are an expert researcher. You always stick to the facts.",
  # Add google_search tool to perform grounding with Google search.
  tools=[google_search]
)

  3. 다음 코드를 app/google_search_agent/__init__.py 파일에 추가합니다.

    from . import agent

플랫폼 설정

에이전트를 실행하려면 Google Cloud Vertex AI를 사용하도록 구성하세요.

  1. app/ 디렉터리에 있는 .env 파일을 엽니다.

  2. 파일에 다음 콘텐츠를 추가합니다. PROJECT_ID를 Google Cloud 프로젝트 ID로 바꾸고 LOCATION를 Google Cloud 위치로 바꿉니다.

    GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=LOCATION
GOOGLE_GENAI_USE_VERTEXAI=True

개발 UI로 에이전트 실행

개발 사용자 인터페이스를 실행하여 에이전트와 상호작용합니다.

  1. 현재 디렉터리를 app로 변경합니다.

    cd app

  2. SSL_CERT_FILE 환경 변수를 설정합니다. 이 단계는 음성 및 동영상 테스트에 필요합니다.

    macOS/Linux

    export SSL_CERT_FILE=$(python -m certifi)

    Windows

    $env:SSL_CERT_FILE = (python -m certifi)

  3. 개발 UI를 실행합니다.

    adk web

  4. 터미널에 제공된 URL(일반적으로 http://localhost:8000 또는 http://127.0.0.1:8000)을 엽니다.

  5. google_search_agent을 선택합니다.

다음 다이어그램은 사용자 입력이 에이전트로 흐르는 방식, 에이전트가 Google 검색 도구를 사용하는 방식, 에이전트가 응답을 반환하는 방식을 보여줍니다.

사용자 입력이 에이전트로 이동하고, 에이전트가 Google 검색 도구를 사용하여 정보를 얻고, 에이전트가 사용자에게 응답을 반환하는 것을 보여주는 다이어그램

에이전트와 상호작용

개발자 UI를 실행한 후 텍스트, 음성 또는 동영상을 사용하여 에이전트와 상호작용할 수 있습니다.

텍스트 입력 사용

UI에 다음 프롬프트를 입력하여 에이전트의 텍스트 기반 응답을 테스트합니다. 상담사는 google_search 도구를 사용하여 이러한 질문에 답할 수 있는 최신 정보를 얻습니다.

  • 뉴욕 날씨는 어때?
  • 지금 뉴욕은 몇 시야?
  • 파리 날씨는 어때?
  • 파리는 지금 몇 시야?

음성 및 영상 입력 사용

음성 입력을 사용하려면 웹브라우저를 새로고침하고 마이크 버튼을 클릭하세요. 질문하면 실시간으로 대답을 들을 수 있습니다.

동영상 입력을 사용하려면 웹브라우저를 새로고침하고 카메라 버튼을 클릭합니다. '무엇이 보이나요?'와 같은 질문을 하면 에이전트가 동영상 입력에서 보이는 내용을 설명합니다.

개발 UI 중지

adk web 도구를 중지하려면 실행 중인 터미널에서 Ctrl+C를 누릅니다.

다음 단계