MongoDB 와 Google ADK 통합

AI 에이전트 빌드를 위한 오픈 소스 Python 프레임워크 인 Google ADK와 MongoDB 통합할 수 있습니다. 통합은 세 가지 구성 요소를 제공합니다.

에이전트에게 MongoDB Vector Search 및 하이브리드 검색 도구를 제공하는 MongoDbToolset
에이전트 세션, 이벤트 및 상태 MongoDB 에 유지하는 MongoDbSessionService
키워드 기반 장기 메모리 리콜을 위해 세션 이벤트를 MongoDB 에 저장하는MongoDbMemoryService

시작하기

MongoDB 사용하도록 Google ADK를 구성하는 튜토리얼을 완료하려면 MongoDB Google ADK 통합 시작하기를 참조하세요.

설치

Google ADK 및 MongoDB 종속성을 설치하려면 다음 명령을 실행 .

pip install "google-adk[mongodb]"

이 명령은 PyMongo 운전자 도 설치합니다. 통합을 위해서는 PyMongo v4.9 이상이 필요합니다.

사용법

이 섹션에서는 MongoDB Google ADK와 통합하는 데 사용할 수 있는 세 가지 구성 요소에 대해 설명합니다.

MongoDbToolset

MongoDbToolset 은( MongoDB database 에 액세스 할 수 있는 다음과 같은 읽기 전용 검색 도구를 포함하는 도구 세트 클래스입니다.

mongodb_vector_search: 유사성을 임베딩하여 문서 순위 지정
mongodb_hybrid_search: 해당 유사성 순위를 전체 텍스트 순위와 결합합니다.

중요

필수 인덱스

앞의 검색 도구를 사용하려면 인덱스 가이드라인 섹션에 설명된 인덱스를 생성해야 합니다.

이러한 도구 중 하나를 호출할 때 에이전트 모델은 일반 텍스트 쿼리 도구 인수로 전달합니다. 두 도구 모두 이 텍스트를 내부에 포함하므로 모델이 벡터를 생성하거나 처리하지 않습니다.

도구 세트를 MongoDB database 에 바인딩하는 예시 보려면 원하는 연결 방법에 해당하는 탭 선택합니다.

다음 예시 연결 문자열 사용하여 도구 세트를 구성하는 방법을 보여 줍니다.

from google.adk.agents import Agentfrom google.adk.integrations.mongodb import MongoDbToolset
toolset = MongoDbToolset(    connection_string="<connection_string>",    database_name="products_db",)
agent = Agent(    model="gemini-2.5-flash",    name="product_search_agent",    instruction=(        "Search the products collection with your MongoDB tools."    ),    tools=[toolset],)

연결 문자열 찾는 방법에 대해 자세히 학습 클라이언트 라이브러리를 통해 클러스터에 연결하기를 참조하세요.

다음 예시 환경 변수에 저장된 연결 문자열 사용하여 도구 세트를 구성하는 방법을 보여 줍니다.

from google.adk.agents import Agentfrom google.adk.integrations.mongodb import MongoDbToolset
toolset = MongoDbToolset(    connection_string_env_var="MONGODB_URI",    database_name="products_db",)
agent = Agent(    model="gemini-2.5-flash",    name="product_search_agent",    instruction=(        "Search the products collection with your MongoDB tools."    ),    tools=[toolset],)

Atlas Agent Engine 배포의 경우 connection_string 대신 이 매개변수를 사용하는 것이 좋습니다.

도구 세트가 노출하지 않는 연결 옵션의 경우, 연결 문자열 대신 자체 pymongo.MongoClient 인스턴스 사용할 수 있습니다. 다음 예시 클라이언트 사용하여 도구 세트를 구성하는 방법을 보여줍니다.

from pymongo import MongoClientfrom google.adk.integrations.mongodb import MongoDbToolset
client = MongoClient("<connection_string>")toolset = MongoDbToolset(database_name="products_db", mongo_client=client)
# ... Pass toolset to an agent

PyMongo 클라이언트에 대해 자세히 학습 PyMongo 문서에서 MongoClient 만들기를 참조하세요.

참고

도구 세트는 이 클라이언트 의 소유권을 갖지 않습니다. 이를 닫을 책임은 사용자에게 있습니다.

모델은 모든 호출에서 컬렉션 선택하므로 에이전트의 지침에 따라 대상 컬렉션 의 이름을 지정합니다. 도구 세트가 액세스 할 수 있는 데이터에 미치는 영향에 대해서는 컬렉션 선택 섹션을 참조하세요.

임베딩 모델의 자격 증명은 자격 증명 검색을 위한 Google Cloud의 표준 메커니즘인 애플리케이션 기본 자격 증명에서 가져옵니다. MongoDB 의 자격 증명은 연결 문자열 에서 가져옵니다.

Parameter	유형	필요성	설명
`database_name`	`str`	필수 사항	도구 세트가 검색하는 데이터베이스 의 이름입니다.
`connection_string`	`str \| None`	조건부	MongoDB deployment 대한 연결 문자열입니다. `connection_string_env_var` 또는 `mongo_client` 값을 지정하지 않는 경우 필수입니다.
`connection_string_env_var`	`str \| None`	조건부	MongoDB 연결 문자열 저장하는 환경 변수의 이름입니다. `connection_string` 또는 `mongo_client` 값을 지정하지 않는 경우 필수입니다. Agent Engine 배포서버 패키지 의 경우 `connection_string` 대신 이 매개변수를 사용하세요.
`mongo_client`	`MongoClient \| None`	조건부	기존 `pymongo.MongoClient` 인스턴스. `connection_string` 또는 `connection_string_env_var` 값을 지정하지 않는 경우 필수입니다.
`tool_filter`	`ToolPredicate \| list[str] \| None`	옵션	에이전트 가 호출할 수 있는 도구 세트의 도구를 제한하는 도구 이름 또는 조건자 함수의 목록입니다. 값을 지정하지 않으면 도구 세트는 `mongodb_vector_search` 및 `mongodb_hybrid_search` 도구를 모두 노출합니다.
`settings`	`MongoDbToolSettings \| None`	옵션	임베딩 모델, 인덱스 이름 및 검색 제한을 구성하는 설정 객체 . 값을 지정하지 않으면 도구 세트는 다음 설정 구성 섹션에 설명된 기본값 을 사용합니다.
`genai_client`	`Client \| None`	옵션	쿼리를 포함하는 데 사용되는 기존 `google.genai.Client` 인스턴스 . 값을 지정하지 않으면 도구 세트는 애플리케이션 기본 자격 증명으로 인증하는 클라이언트 생성합니다.

설정 구성

MongoDbToolSettings MongoDbToolset가 사용하는 임베딩 모델, 인덱스 이름 및 검색 제한을 구성하는 설정 클래스입니다. 다음 예시 와 같이 이 클래스의 인스턴스 MongoDbToolset의 settings 매개변수에 전달하여 기본값을 재정의합니다.

from google.adk.integrations.mongodb import MongoDbToolsetfrom google.adk.integrations.mongodb import MongoDbToolSettings
toolset = MongoDbToolset(    connection_string="<connection_string>",    database_name="products_db",    settings=MongoDbToolSettings(default_limit=8, max_results=20),)

옵션	유형	필요성	설명
`vertex_ai_embedding_model_name`	`str`	옵션	쿼리 텍스트를 포함하는 데 사용되는 꼭짓점 AI 모델입니다. 기본값은 `"text-embedding-005"`입니다.
`vertex_ai_embedding_output_dimensionality`	`int \| None`	옵션	단축을 지원 모델의 경우 쿼리 임베딩의 길이입니다. 기본값은 모델의 네이티브 길이입니다.
`use_mongodb_auto_embedding`	`bool`	옵션	쿼리 텍스트를 Atlas 로 전송하고 Vertex AI 모델을 호출하는 대신 Atlas 인덱스의 Voyage AI 모델과 함께 텍스트를 포함하도록 허용할지 여부입니다. 기본값은 `False`입니다. 자세한 학습 은 다음 임베딩 모드 섹션을 참조하세요.
`mongodb_auto_embedding_model`	`str \| None`	옵션	`"voyage-4"`와 같은 자동 내장된 쿼리를 위한 Voyage AI 모델입니다. 인덱스의 모델과 호환되어야 합니다. 기본값은 인덱스 모델입니다.
`default_vector_index_name`	`str`	옵션	모델이 이름을 지정하지 않을 때 사용되는 벡터 검색 인덱스 . 기본값은 `"vector_index"`입니다.
`default_search_index_name`	`str`	옵션	모델에 이름이 지정되지 않은 경우 하이브리드 검색 에서 사용하는 전체 텍스트 검색 인덱스 . 기본값은 `"default"`입니다.
`default_embedding_field`	`str`	옵션	저장된 벡터를 보유하는 문서 필드 . 기본값은 `"embedding"`입니다.
`default_limit`	`int`	옵션	모델이 번호를 요청하지 않을 때 반환되는 문서입니다. 기본값은 `4`입니다.
`max_results`	`int`	옵션	1개 검색 에서 반환되는 문서의 상한선입니다. 기본값은 `50`입니다.
`default_num_candidates`	`int`	옵션	가장 가까운 이웃은 벡터 검색 고려합니다. 기본값은 `100`입니다.
`timeout_ms`	`int`	옵션	단일 검색 작업에 대한 시간 제한(단위: 밀리초)입니다. 기본값은 `60000`입니다.

임베딩 모드

도구 세트는 벡터 검색 실행 전에 쿼리 텍스트를 포함합니다. Atlas Automated Embedding 탭 선택하여 Atlas 쿼리를 자동으로 임베딩하도록 허용하거나 Google embedding models 탭 선택하여 기본값 임베딩 동작을 확인합니다.

Atlas 자동 임베딩을 사용하려면 MongoDbToolSettings 구성 클래스에서 use_mongodb_auto_embedding 매개변수를 True로 설정하다 . 다음 예시 이 구성을 보여줍니다.

from google.adk.integrations.mongodb import MongoDbToolsetfrom google.adk.integrations.mongodb import MongoDbToolSettings
toolset = MongoDbToolset(    connection_string="<connection_string>",    database_name="products_db",    settings=MongoDbToolSettings(        use_mongodb_auto_embedding=True,        mongodb_auto_embedding_model="voyage-4",  # optional    ),)

이 구성을 사용하면 도구 세트가 Google 임베딩 호출을 수행하지 않습니다. 대신 벡터 검색 단계에서 쿼리 텍스트를 수신하면 Atlas 인덱스 에 구성된 Voyage AI 모델을 사용하여 임베딩을 생성합니다. 검색된 필드 autoEmbed 유형으로 인덱싱되어야 합니다.

팁

미리보기 기능

Atlas Automated Embedding은 자체 관리형 배포에서 Preview 기능 으로도 사용할 수 있습니다. 자세한 학습 은 autoEmbed 유형 정보를 참조하세요.

기본값 으로 도구 세트는 Vertex AI 임베딩 모델을 통해 쿼리 임베딩하고 결과 벡터를 $vectorSearch 집계 단계의 queryVector 필드 로 전달합니다. 다음 예시 이 기본값 구성을 보여줍니다.

from google.adk.integrations.mongodb import MongoDbToolset
toolset = MongoDbToolset(    connection_string="<connection_string>",    database_name="products_db",)

이 모드 임베딩 API 에 대한 애플리케이션 기본 자격 증명이 필요합니다. 문서에 저장된 임베딩은 vertex_ai_embedding_model_name 옵션이 설정하는 쿼리 임베딩하는 것과 동일한 Vertex AI 모델에서 가져와야 합니다.

컬렉션 선택

모델은 각 호출에서 컬렉션 선택하므로 데이터베이스 에 바인딩된 도구 세트는 검색 인덱스 있는 해당 데이터베이스 의 모든 컬렉션 에 액세스합니다. 에이전트 읽을 수 있는 데이터만 포함하는 데이터베이스 로 database_name 매개변수를 설정하고, 다른 데이터는 별도의 데이터베이스 에 저장 .

tool_filter 매개변수는 전체 도구를 선택하고 호출 인수를 수신하지 않기 때문에 모델이 액세스 할 수 있는 컬렉션을 제한하지 않습니다. 컬렉션 허용 목록을 시행하다 하려면 호출 인수를 수신하는 before_tool_callback 후크를 대신 사용하세요.

from google.adk.agents import Agentfrom google.adk.integrations.mongodb import MongoDbToolset

def allow_products_only(tool, args, tool_context):  if tool.name.startswith("mongodb_") and args.get("collection_name") != "products":    return {        "status": "ERROR",        "error_details": "Only the products collection may be searched.",    }  return None

agent = Agent(    name="product_search_agent",    instruction="Answer questions about products.",    tools=[        MongoDbToolset(            connection_string="<connection_string>",            database_name="products_db",        )    ],    before_tool_callback=allow_products_only,)

콜백 사전을 반환하는 경우 ADK는 검색 도구를 실행하지 않습니다. 대신 해당 사전을 도구의 자체 출력인 것처럼 에이전트 로 보냅니다. None을 반환하면 검색 도구가 정상적으로 실행 됩니다.

MongoDbSessionService

MongoDbSessionService 세션, 이벤트 및 앱, 사용자 및 세션 범위 상태 MongoDB 에 저장합니다. 다음 예시 와 같이 Runner 객체 에 전달하여 에이전트 에 대한 영구 대화 기록을 구성합니다.

from google.adk.integrations.mongodb import MongoDbSessionServicefrom google.adk.runners import Runner
session_service = MongoDbSessionService(    connection_string="<connection_string>",    database_name="my_app",)
runner = Runner(    agent=agent,    app_name="my_app",    session_service=session_service,)

Parameter	유형	필요성	설명
`database_name`	`str`	필수 사항	세션 서비스의 컬렉션을 보관하는 데이터베이스 의 이름입니다.
`connection_string`	`str \| None`	조건부	MongoDB deployment 대한 연결 문자열입니다. `mongo_client` 값을 지정하지 않는 경우 필수입니다.
`mongo_client`	`MongoClient \| None`	조건부	기존 `pymongo.MongoClient` 인스턴스. `connection_string` 값을 지정하지 않는 경우 필수입니다.
`sessions_collection`	`str`	옵션	세션 문서를 저장하는 컬렉션 의 이름입니다. 기본값은 `"sessions"`입니다.
`events_collection`	`str`	옵션	이벤트 문서를 저장하는 컬렉션 의 이름입니다. 기본값은 `"events"`입니다.
`app_state_collection`	`str`	옵션	앱 범위 상태 저장하는 컬렉션 의 이름입니다. 기본값은 `"app_states"`입니다.
`user_state_collection`	`str`	옵션	사용자 범위 상태 저장하는 컬렉션 의 이름입니다. 기본값은 `"user_states"`입니다.
`ensure_indexes`	`bool`	옵션	처음 사용할 때 권장 세컨더리 인덱스를 생성할지 여부입니다. 기본값은 `True`입니다. 자세히 학습 이 페이지의 인덱스 가이드라인을 참조하세요.

문서 레이아웃

MongoDbSessionService 다음 컬렉션에 데이터를 저장합니다.

컬렉션	`_id` 값	콘텐츠
`sessions`	`<app_name>/<user_id>/<session_id>`	JSON 의 세션 범위 상태 , 타임스탬프 및 낙관적 동시성 수정 번호
`events`	`<app_name>/<user_id>/<session_id>/<event_id>`	전체 직렬화된 이벤트
`app_states`	`<app_name>`	앱 범위 상태
`user_states`	`<app_name>/<user_id>`	사용자 범위 상태

Google ADK 범위는 상태 키에 app: 또는 user: 접두사가 있는 앱 , 사용자 또는 현재 세션으로 상태 합니다. MongoDbSessionService는 각 값을 해당 컬렉션 에 저장하고 저장된 키에서 접두사를 제거하므로 app:theme 키로 설정하다 값은 app_states 컬렉션 에 theme로 저장됩니다.

참고

각 컬렉션의 state 필드 키와 값을 네이티브 MongoDB 문서 아닌 JSON 으로 인코딩된 문자열로 저장합니다. 결과적으로 . 또는 $와 같이 MongoDB 문서 필드 이름에 금지하는 문자가 포함된 상태 키는 데이터 손실이나 손상 없이 저장되고 검색됩니다.

동시성 모델

서비스의 동시성 모델은 배포서버 유형에 따라 다릅니다.

복제본 세트, 샤딩된 클러스터 또는 Atlas cluster 에서 모든 다중 문서 쓰기 (write) 트랜잭션 에서 실행되므로 원자적으로 커밋되거나 중단됩니다.
독립형 mongod 또는 트랜잭션 지원 없는 배포서버 에서 서비스는 세션 문서 에 대한 낙관적 동시성 수정 확인을 통해 순차적 쓰기로 대체됩니다.

단일 프로세스 내에서 세션별 락 동일한 세션에 대한 동시 쓰기를 방지합니다. 이 락 애플리케이션 의 여러 인스턴스가 동시에 동일한 세션에 쓰기 (write) 경우와 같이 여러 프로세스에는 영향을 미치지 않습니다.

여러 프로세스에 걸쳐 세션 문서의 수정 확인을 통해 데이터 손상을 방지합니다. 두 쓰기가 경쟁하는 경우, 먼저 완료되는 쓰기 (write) 는 수정본 번호를 증가시키고, 다른 쓰기 (write) 수정본 검사에 실패합니다. 애플리케이션 이 실패를 포착하고 세션을 다시 로드하여 현재 상태 가져온 다음 쓰기 (write) 다시 시도해야 합니다.

MongoDbMemoryService

MongoDbMemoryService 세션 이벤트를 메모리 컬렉션 에 저장하고 키워드 매칭을 통해 조회합니다. 다음 예시 와 같이 Runner 객체 에 전달하여 세션 간에 장기 메모리를 구성합니다.

from google.adk.integrations.mongodb import MongoDbMemoryServicefrom google.adk.runners import Runner
memory_service = MongoDbMemoryService(    connection_string="<connection_string>",    database_name="my_app",)
runner = Runner(    agent=agent,    app_name="my_app",    memory_service=memory_service,)

Parameter	유형	필요성	설명
`database_name`	`str`	필수 사항	메모리 서비스의 컬렉션 보관하는 데이터베이스 의 이름입니다.
`connection_string`	`str \| None`	조건부	MongoDB deployment 대한 연결 문자열입니다. `mongo_client` 값을 지정하지 않는 경우 필수입니다.
`mongo_client`	`MongoClient \| None`	조건부	기존 `pymongo.MongoClient` 인스턴스. `connection_string` 값을 지정하지 않는 경우 필수입니다.
`memories_collection`	`str`	옵션	메모리 문서를 저장하는 컬렉션 의 이름입니다. 기본값은 `"memories"`입니다.
`stop_words`	`set[str] \| None`	옵션	키워드 추출에서 제외할 단어입니다. 기본값은 `"the"` 및 `"and"`와 같은 일반적인 영어 불용어의 간략한 목록입니다.
`max_results`	`int`	옵션	쿼리 당 반환되는 최대 메모리 수입니다. 기본값은 `50`입니다.
`ensure_indexes`	`bool`	옵션	처음 사용할 때 권장 세컨더리 인덱스를 생성할지 여부입니다. 기본값은 `True`입니다. 자세히 학습 이 페이지의 인덱스 가이드라인을 참조하세요.

Runner 객체 메모리 서비스의 add_session_to_memory() 메서드를 호출하여 세션의 이벤트를 메모리로 수집합니다. 수집된 각 이벤트 memories_collection 매개변수가 구성하는 메모리 컬렉션 에 메모리 문서 로 저장됩니다. 이러한 문서에는 이벤트의 텍스트 콘텐츠에서 추출한 소문자 키워드가 포함되어 있습니다.

고려 사항

메모리 서비스를 사용할 때는 다음 동작을 고려하세요.

메모리를 검색 때 서비스는 키워드 배열 이 쿼리의 키워드와 교차하는 문서를 반환합니다.
수집 은 멱등 있습니다. 세션을 다시 수집하면 서비스는 메모리를 복제하지 않고 덮어씁니다.
조회는 키워드 검색 수행하며 임베딩 모델, Google 자격 증명 또는 벡터 인덱스 필요하지 않습니다. 따라서 메모리 검색은 모든 MongoDB deployment 에서 작동합니다.

인덱스 가이드라인

이 섹션에서는 MongoDB 와 Google ADK를 통합하는 데 필요한 인덱스에 대해 설명하고 성능 개선을 위한 권장 인덱스도 포함되어 있습니다.

필수 MongoDbToolset 인덱스

에이전트 검색하는 각 컬렉션 에는 다음 인덱스가 필요합니다.

임베딩을 저장하는 필드 에 대한 MongoDB Vector Search 인덱스 이며, vector 유형으로 인덱싱된 필드 입니다. Atlas 자동 임베딩을 사용하는 경우 대신 필드 autoEmbed 유형으로 인덱스 .
mongodb_hybrid_search 도구를 사용하는 경우 검색 할 텍스트를 저장하는 필드 에 대한 MongoDB Search 인덱스

MongoDbToolset 는 이러한 인덱스를 이름으로 읽고 생성하지 않습니다. 이러한 인덱스를 만드는 방법을 학습 보려면 MongoDB 벡터 검색 인덱스 만들기 및 MongoDB 검색 인덱스 만들기를 참조하세요.

컬렉션	Index	인덱싱된 필드 및 정렬 순서
`events`	`app_user_session_ts`	`(app_name, user_id, session_id, timestamp DESC, revision DESC)`
`sessions`	`app_user`	`(app_name, user_id)`
`memories`	`app_user_keywords`	`(app_name, user_id, keywords)` (multikey)

권한 지침

단일 관리 사용자를 사용하는 대신 두 명의 별도 데이터베이스 사용자를 사용하여 각 구성 요소에 필요한 권한 범위를 유지하는 것이 좋습니다.

다음 표에서는 두 데이터베이스 사용자에 대해 권장되는 최소 권한 구성에 대해 설명합니다.

데이터베이스 사용자	사용자	최소 권한
사용자 검색(읽기 전용)	`MongoDbToolset`	`find` 에이전트 검색할 각 컬렉션 에서
상태 사용자(읽기-쓰기)	`MongoDbSessionService`, `MongoDbMemoryService`	* `find`, `insert`, `update`, `remove` on the `sessions` and `events` collections * `find`, `insert`, `update` on the `app_states`, `user_states`, and `memories` collections * If you set `ensure_indexes` to `True`, add the `createIndex` action on the `sessions`, `events`, and `memories` collections

중요

앞의 표의 권한은 Atlas 내장 역할이 아닌 MongoDB 작업입니다. 권한을 부여하려면 나열된 컬렉션으로 범위가 지정된 이러한 작업을 사용하여 각 사용자에 대한 사용자 지정 역할 만듭니다.

추가 리소스

MongoDB 에서 Google ADK를 사용하는 방법에 대해 자세히 학습 다음 리소스를 참조하세요.

Google ADK documentation
Google ADK GitHub 리포지토리

돌아가기

OpenAI Agents SDK

시작하기

MongoDB 와 Google ADK 통합

시작하기

설치

사용법

MongoDbToolset

MongoDbToolset 매개변수이 매개변수를 사용하여 도구 세트를 구성합니다.

설정 구성

MongoDbToolSettings 옵션이 옵션을 사용하여 검색 도구를 구성합니다.

임베딩 모드

컬렉션 선택

MongoDbSessionService

MongoDbSessionService 매개변수이 매개변수를 사용하여 세션 서비스를 구성합니다.

문서 레이아웃

동시성 모델

MongoDbMemoryService

MongoDbMemoryService 매개변수이 매개변수를 사용하여 메모리 서비스를 구성합니다.

고려 사항

인덱스 가이드라인

필수 MongoDbToolset 인덱스

추천 서비스 인덱스

권한 지침

추가 리소스