MongoDB Google ADK와 통합하여 에이전트 검색 도구와 지속적인 대화 기록을 구성할 수 있으며, 둘 다 MongoDB 에서 지원합니다. 이 튜토리얼에서는 MongoDbToolset 클래스를 사용하여 Google ADK 에이전트 펭귄 데이터가 포함된 컬렉션 검색 할 활성화 . 그런 다음 튜토리얼에서는 MongoDbSessionService 클래스를 사용하여 에이전트 대화의 이전 차례에 액세스 수 있도록 합니다.
이 튜토리얼에서는 다음 작업을 수행합니다.
환경을 설정합니다.
컬렉션 과 벡터 검색 인덱스 만듭니다.
컬렉션 검색하는 에이전트 를 빌드합니다.
에이전트 이전 차례를 기억할 수 있도록 영구 세션을 추가합니다.
파일을 실행하고 출력을 검토하세요.
배경
Google ADK는 AI 에이전트 구축을 위한 오픈 소스 Python 프레임워크 입니다. 이 튜토리얼에서는 다음 Google ADK 구성 요소를 사용하여 에이전트 구성하고 MongoDB 액세스 활성화 .
MongoDbToolset: MongoDB database 에서 MongoDB Vector Search 및 하이브리드 검색 도구를 제공합니다.MongoDbSessionService: MongoDB 에서 에이전트 세션, 이벤트 및 상태 유지합니다.
이 튜토리얼에서는 별도의 임베딩 모델이나 Google 자격 증명 없이 저장된 문서와 검색 쿼리를 모두 임베딩하는 Atlas 자동 임베딩을 사용하도록 MongoDbToolset 클래스를 구성합니다.
전제 조건
이 튜토리얼을 완료하려면 다음 리소스가 있어야 합니다:
다음 MongoDB cluster 유형 중 하나입니다.
MongoDB 버전 6.0.11을 실행하는 Atlas 클러스터, 7.0.2 이상. 당신의 IP 주소가 Atlas 프로젝트의 액세스 목록에 포함되어 있는지 확인하세요.
Python과 Docker를 사용하여 만든 로컬 Atlas 배포서버입니다.
atlas-local-lib-py(pip install atlas-local-lib-py)를 설치하여 로컬 배포서버를 프로그래밍으로 만들고 관리할 수 있습니다. 자세한 내용은 atlas-local-lib-py 리포지토리를 참조하십시오.검색 및 벡터 검색이 설치된 MongoDB Community 클러스터.
Gemini API 키입니다. 이 튜토리얼에서는 Gemini 모델을 사용하지만, 지원되는 모든 제공자 사용할 수 있습니다. 자세히 학습 Google ADK 문서에서 모델을 참조하세요.
Python v3.11 이상.
환경 설정
이 섹션에서는 필요한 종속성을 설치하고, 환경 변수를 설정하고, 프로젝트 파일 만들어 환경을 준비합니다.
환경 변수를 설정합니다.
google-adk-mongodb-project 디렉토리에서 .env 파일을 만들고 다음 코드를 추가합니다.
GOOGLE_API_KEY="<gemini-api-key>"MONGODB_URI="<connection-string>"<connection-string>을 Atlas 클러스터 또는 로컬 Atlas 배포서버의 연결 문자열로 교체합니다.
연결 문자열은 다음 형식을 사용해야 합니다.
mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net중요한: 연결 문자열 에 데이터베이스 사용자의 자격 증명 포함되어 있는지 확인하세요. 연결 문자열 찾는 방법에 대해 자세히 학습하려면 클라이언트 라이브러리를 통해 클러스터에 연결하기를 참조하세요.
연결 문자열은 다음 형식을 사용해야 합니다.
mongodb://localhost:<port-number>/?directConnection=true학습 내용은 연결 문자열을 참조하세요.
프로젝트 파일 만들기
google-adk-mongodb-project 디렉토리 에서 main.py이라는 파일 생성합니다. 이 파일 에 다음 코드를 추가하여 환경 변수를 로드하고 필요한 모듈을 가져옵니다.
import osimport timeimport asynciofrom dotenv import load_dotenvfrom pymongo import MongoClientfrom pymongo.operations import SearchIndexModelfrom google.adk.agents import Agentfrom google.adk.integrations.mongodb import ( MongoDbToolset, MongoDbToolSettings, MongoDbSessionService,)from google.adk.runners import Runnerfrom google.genai import types
load_dotenv()이후 단계에서는 이 파일 에 코드를 추가하여 컬렉션 만들고, 에이전트 빌드 , 실행 .
컬렉션 및 인덱스 만들기
이 섹션에서는 MongoDB 컬렉션 에 펭귄에 대한 샘플 문서를 삽입하고 Atlas 자동 임베딩에 필요한 MongoDB Vector Search 인덱스 생성합니다.
샘플 문서를 삽입합니다.
main.py 파일 에 다음 코드를 추가하여 컬렉션 에 Penguin을 설명하는 문서 5개를 삽입합니다. embeddings 필드 Atlas 자동으로 임베딩하는 텍스트를 저장합니다.
collection.insert_many( [ { "title": "Emperor Penguins", "embeddings": "Emperor penguins are the tallest and heaviest of all penguin species, standing up to 4 feet.", }, { "title": "Penguin Habitats", "embeddings": "Penguins are flightless seabirds that live almost exclusively below the equator. Some island-dwellers can be found in warmer climates.", }, { "title": "Penguins of Patagonia", "embeddings": "Patagonia is home to five penguin species: Magellanic, Humboldt, Gentoo, Southern Rockhopper, and King.", }, { "title": "Penguin Diving Depths", "embeddings": "Emperor penguins can dive deeper than any other bird, reaching depths of over 500 meters.", }, { "title": "Penguin Nesting Habits", "embeddings": "Some penguin species mate for life and return to the same nesting site every year.", }, ])Atlas 자동 임베딩 인덱스 생성합니다.
main.py 파일 에 다음 코드를 추가하여 embeddings 필드 에 MongoDB Vector Search 인덱스 생성합니다. autoEmbed 필드 유형은 Atlas 이 필드 에 대한 임베딩을 자동으로 생성하고 저장 하도록 지시합니다.
search_index_model = SearchIndexModel( definition={ "fields": [ { "type": "autoEmbed", "path": "embeddings", "model": "voyage-4", "modality": "text", } ] }, name="autoembed_index", type="vectorSearch",)
collection.create_search_index(model=search_index_model)
# Index build time varies with collection size and cluster typeprint("Waiting for the MongoDB Vector Search index to finish building...")time.sleep(60)
client.close()인덱스 빌드 데 약 1분 정도 소요됩니다. 빌드되는 동안 인덱스는 초기 동기화 상태입니다. 빌드가 완료되면 컬렉션 의 데이터 쿼리를 시작할 수 있습니다.
에이전트 도구 및 세션 구성
이 섹션에서는 MongoDbToolset 클래스를 사용하여 컬렉션 검색 하는 에이전트 를 빌드 . 그런 다음 에이전트의 대화 기록을 MongoDB 에 유지하도록 MongoDbSessionService 클래스를 구성합니다.
도구 세트를 구성합니다.
main.py 파일 에 다음 코드를 추가하여 MongoDbToolset을 데이터베이스 에 바인딩하고 Atlas 자동 임베딩을 사용하도록 구성합니다.
toolset = MongoDbToolset( connection_string=os.environ["MONGODB_URI"], database_name="google_adk_tutorial", settings=MongoDbToolSettings( use_mongodb_auto_embedding=True, default_embedding_field="embeddings", default_vector_index_name="autoembed_index", ),)use_mongodb_auto_embedding 옵션이 True로 설정하다 있기 때문에 도구 세트는 Google 임베딩 모델을 호출하는 대신 쿼리 텍스트를 Atlas 에 일반 텍스트로 전송합니다.
에이전트 정의합니다.
main.py 파일 에 다음 코드를 추가하여 Gemini 모델과 도구 세트를 사용하는 에이전트 생성합니다.
root_agent = Agent( model="gemini-2.5-flash", name="penguin_facts_agent", description="Answers questions about penguins.", instruction=( "Search the penguins collection with your MongoDB" " tools to answer questions about penguins. Remember" " what the user has told you earlier in the" " conversation." ), tools=[toolset],)세션 서비스 및 러너를 구성합니다.
main.py 파일 에 다음 코드를 추가하여 MongoDbSessionService 클래스를 구성하고 이를 에이전트 와 함께 Runner 객체 에 전달합니다.
session_service = MongoDbSessionService( connection_string=os.environ["MONGODB_URI"], database_name="google_adk_tutorial",)
runner = Runner( agent=root_agent, app_name="google_adk_tutorial", session_service=session_service,)기본값 으로 MongoDbSessionService은(는) ensure_indexes 매개변수를 False(으)로 설정하다 하지 않는 한 사용에 권장되는 인덱스를 생성합니다. 자세한 학습 은 Google ADK 참조에서 인덱스 가이드라인을 참조하세요.
두 번의 대화 차례에 걸쳐 에이전트 를 실행합니다.
main.py 파일 에 다음 코드를 추가하여 세션을 생성한 다음, 해당 세션을 통해 에이전트 에게 두 개의 메시지를 보냅니다.
async def ask(runner, session_id, text): content = types.Content(role="user", parts=[types.Part(text=text)]) async for event in runner.run_async( user_id="tutorial_user", session_id=session_id, new_message=content, ): if event.is_final_response() and event.content: print(f"\n[user]: {text}") print(f"[agent]: {event.content.parts[0].text}")
async def main(): session = await session_service.create_session( app_name="google_adk_tutorial", user_id="tutorial_user", )
await ask( runner, session.id, "How deep can emperor penguins dive?" ) await ask( runner, session.id, "What was the first thing I asked you?" )
asyncio.run(main())두 호출 모두 동일한 session_id 값을 사용하기 때문에, MongoDbSessionService은 에이전트 두 번째 메시지에 응답하기 전에 첫 번째 차례의 이벤트를 로드합니다. 두 번째 통화에 대해 새 세션을 생성하는 경우 에이전트 첫 번째 통화에 대한 기록 보유하지 않습니다.
파일 실행
main.py 파일을 실행하려면 google-adk-mongodb-project 디렉토리에서 다음 명령을 실행하세요:
python main.py명령이 성공적으로 실행되면 출력은 다음과 유사합니다.
Waiting for the MongoDB Vector Search index to finish building...
[user]: How deep can emperor penguins dive?[agent]: Emperor penguins can dive deeper than any other bird,reaching depths of over 500 meters.
[user]: What was the first thing I asked you?[agent]: The first thing you asked me was about how deep emperorpenguins can dive.다음 단계
전체 매개변수 및 메서드 참조를 포함하여 MongoDbToolset, MongoDbSessionService 및 MongoDbMemoryService에 대해 자세히 학습 보려면 MongoDB 와 Google ADK 통합을 참조하세요.
Google ADK에 대해 자세히 학습 adk-python GitHub 리포지토리 참조하세요.