개발 환경 선택
시작하려면 Python 3.11 이상이 설치된 Python 개발 환경이 필요합니다. 이 단계는 Google Colab에서 테스트되었습니다.
Colab Enterprise, Cloud Shell 편집기, 로컬 머신과 같은 다른 개발 환경에서 여기에 표시된 단계를 조정할 수도 있습니다.
환경이 준비되면 Agent Framework SDK를 설치할 수 있습니다.
Agent Framework SDK 설치
이제 Agent Framework SDK를 설치합니다. 비공개 프리뷰 기간에 SDK에 액세스하려면 허용 목록에 추가되어야 합니다. 아래의 다운로드 및 설치 단계를 진행하기 전에 허용 목록에 추가되었는지 확인하세요.
먼저 gcloud CLI를 사용하여 Google Cloud 계정을 인증합니다. 이 단계에서 Google Cloud 서비스에 액세스하는 데 필요한 권한을 부여받게 됩니다. 자세한 내용은 필요한 경우 gcloud 문서를 참조하세요.
gcloud auth login
gcloud CLI를 사용하여 Agent Framework SDK Python 패키지를 개발 환경에 다운로드합니다.
gcloud storage cp gs://agent_framework/latest/google_genai_agents-0.0.2.dev20250204+723246417-py3-none-any.whl .
이전 명령어에서 Agent Framework가 개발 빌드에 액세스하려면 허용 목록에 포함되어 있어야 합니다.
마지막으로 pip
를 사용하여 다운로드한 Agent Framework SDK 패키지를 설치합니다.
pip install google_genai_agents-0.0.2.dev20250204+723246417-py3-none-any.whl
Agent Framework SDK가 설치되었으므로 이제 필요한 라이브러리를 가져와서 에이전트 빌드를 시작할 수 있습니다.
필요한 라이브러리 가져오기
Agent Framework에서 이 빠른 시작을 사용하는 데 필요한 다음 Python 라이브러리를 가져옵니다.
import os
from agents import Runner, Agent
from datetime import datetime
라이브러리를 가져온 후에는 Gemini 모델에 대한 액세스를 구성해야 합니다.
Gemini API에 대한 액세스 구성
Agent Framework는 Google의 Gemini 모델을 사용하도록 구성할 수 있습니다. Google AI Studio(API 키 사용) 또는 Vertex AI(Google Cloud 프로젝트 사용)를 통해 Gemini 모델에 대한 액세스를 구성할 수 있습니다. 필요에 맞는 구성 방법을 선택하고 아래에서 해당하는 안내를 따르세요.
Google AI Studio를 사용하여 Gemini 모델에 대한 액세스를 구성하려면 다음 Python 코드를 실행합니다. YOUR_API_KEY
를 실제 Google AI Studio API 키로 바꿉니다.
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "0"
os.environ["GOOGLE_API_KEY"] = "YOUR_API_KEY"
Vertex AI를 사용하여 Gemini 모델에 대한 액세스를 구성하려면 다음 Python 코드를 실행합니다. YOUR_PROJECT_ID
를 Google Cloud 프로젝트 ID로 바꿉니다. GOOGLE_CLOUD_LOCATION
이 지원되는 Vertex AI 리전으로 설정되어 있는지 확인합니다.
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "1"
os.environ["GOOGLE_CLOUD_PROJECT"] = "YOUR_PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "us-central1"
Gemini API 액세스를 구성했으므로 이제 에이전트가 사용할 도구를 정의할 수 있습니다.
에이전트의 도구 정의
에이전트는 도구를 사용하여 외부 서비스 및 데이터와 상호작용하는 경우가 많습니다. 이 단계에서는 get_exchange_rate
라는 Python 함수를 정의합니다. 이 함수는 에이전트가 외부 API에서 실시간 통화 환율을 가져오는 도구로 사용됩니다.
def get_exchange_rate(
currency_from: str,
currency_to: str,
currency_date: str,
):
"""Retrieves the exchange rate between two currencies on a specified date."""
import requests
response = requests.get(
f"https://api.frankfurter.app/{currency_date}",
params={"from": currency_from, "to": currency_to},
)
return response.json()
이제 에이전트를 위한 도구를 정의했습니다. 다음 섹션에서는 이 도구를 통합하여 에이전트 자체를 정의합니다.
에이전트 정의
이제 Agent Framework SDK를 사용하여 AI 에이전트를 정의합니다. 에이전트 정의는 사용할 모델, 안내, 액세스할 수 있는 도구, 상호작용 흐름을 지정합니다.
root_agent = Agent(
model="gemini-2.5-pro-exp-03-25",
name='currency_exchange_agent',
instruction="""
Help users retrieve exchange rates for different currencies
""",
tools=[
get_exchange_rate,
],
flow='single',
)
에이전트를 정의했으면 Agent Framework 내에서 에이전트를 초기해야 합니다.
에이전트 초기화
이 섹션에서는 에이전트를 초기화합니다. 다음 코드는 메모리 내 세션 및 아티팩트 서비스를 설정하고, 에이전트의 실행자를 인스턴스화하며, 프롬프트를 전송하는 도우미 함수를 정의합니다.
from agents.sessions.in_memory_session_service import InMemorySessionService
from agents.artifacts.in_memory_artifact_service import InMemoryArtifactService
from google.genai import types
session_service = InMemorySessionService()
artifact_service = InMemoryArtifactService()
runner = Runner(app_name="currency_exchange_agent", agent=root_agent, artifact_service=artifact_service, session_service=session_service)
session = session_service.create(app_name="currency_exchange_agent", user_id="1")
def run_prompt(new_message: str):
content = types.Content(role='user', parts=[types.Part.from_text(text=new_message)])
print (content)
for event in runner.run(
session=session,
new_message=content,
):
if event.content:
print(event.content.model_dump(exclude_none=True))
이제 에이전트가 초기화되었으며 프롬프트를 받을 수 있습니다. 다음 섹션에서는 테스트 프롬프트를 보내 실제로 작동하는지 확인합니다.
에이전트에게 프롬프트 보내기
이제 에이전트를 테스트할 차례입니다. 앞서 정의한 run_prompt 함수를 사용하여 에이전트에게 다음 프롬프트를 전송합니다.
run_prompt("What's the exchange rate from US dollars to Swedish currency today?")
제공된 입력으로 run_prompt
함수를 실행하면 에이전트가 다음과 유사한 출력을 생성해야 합니다.
parts=[Part(video_metadata=None, thought=None, code_execution_result=None, executable_code=None, file_data=None, function_call=None, function_response=None, inline_data=None, text="What's the exchange rate from US dollars to Swedish currency today?")] role='user'
{'parts': [{'function_call': {'args': {'currency_from': 'USD', 'currency_to': 'SEK', 'currency_date': '2025-02-21'}, 'name': 'get_exchange_rate'}}], 'role': 'model'}
{'parts': [{'function_response': {'name': 'get_exchange_rate', 'response': {'amount': 1.0, 'base': 'USD', 'date': '2025-02-21', 'rates': {'SEK': 10.6474}}}}], 'role': 'user'}
{'parts': [{'text': 'The exchange rate from US dollars to Swedish currency (SEK) today, 2025-02-21, is 1 USD to 10.6474 SEK.\n'}], 'role': 'model'}
이 출력에는 에이전트가 실행한 함수 호출 및 최종 응답을 비롯한 에이전트의 내부 단계가 표시됩니다.
출력의 마지막 부분을 살펴봅니다. 에이전트가 get_exchange_rate
도구를 성공적으로 사용했음을 보여주는 검색된 환율이 포함된 에이전트의 메시지가 표시됩니다.
The exchange rate from US dollars to Swedish currency (SEK) today, 2025-02-21,
is 1 USD to 10.6474 SEK.
수고하셨습니다. 에이전트에게 프롬프트를 전송하고 응답을 확인했습니다. Agent Framework를 자세히 알아보려면 다음 섹션에서 리소스와 다음 단계를 참고하세요.
다음 단계 및 리소스
수고하셨습니다. Agent Framework로 AI 에이전트를 빌드했습니다.
Agent Framework에 대해 자세히 알아보고 더 많은 고급 기능을 살펴보려면 문서의 다른 섹션, 코드 샘플 또는 노트북을 참고하세요. 이러한 리소스는 더 복잡한 에이전트를 빌드하고 애플리케이션에 통합하는 방법을 안내합니다.