Você pode integrar o MongoDB ao Google ADK para configurar as ferramentas de pesquisa do agente e o histórico persistente de conversas, ambos apoiados pelo MongoDB. Este tutorial usa a classe MongoDbToolset para habilitar um agente do Google ADK a pesquisar uma coleção contendo dados de pinguim. Em seguida, o tutorial usa a classeMongoDbSessionService , permitindo ao agente acessar as voltas anteriores na conversa.
Neste tutorial, você executa as seguintes tarefas:
Configure seu ambiente.
Crie uma coleção e um índice de pesquisa vetorial .
Construa um agente que pesquise sua collection.
Adicione sessões persistentes para que o agente se lembre das voltas anteriores.
Execute o arquivo e revise a saída.
Plano de fundo
O Google ADK é um framework Python de código aberto para criar agentes de IA. Este tutorial utiliza os seguintes componentes do Google ADK para configurar um agente e habilitar o acesso MongoDB :
MongoDbToolset: Fornece Vector Search MongoDB e ferramentas de pesquisa híbridas em um banco de dados MongoDBMongoDbSessionService: persiste sessões de agente , eventos e estado no MongoDB
Este tutorial configura a classe MongoDbToolset para usar o Atlas Automated Embedding, que incorpora seus documentos armazenados e suas queries de pesquisa sem exigir um modelo de incorporação separado ou credenciais do Google.
Pré-requisitos
Para concluir este tutorial, você deve ter os seguintes recursos:
Um dos seguintes tipos de cluster MongoDB :
Um cluster do Atlas executando a versão do MongoDB 6.0.11, 7.0.2, ou posterior. Certifique-se de que seu endereço IP esteja incluído na lista de acesso do seu projeto Atlas.
Uma implantação local do Atlas criada usando Python e Docker. Instale
atlas-local-lib-py(pip install atlas-local-lib-py) para criar e gerenciar implantações locais programaticamente. Para saber mais, consulte o repositório atlas-local-lib-py.Um cluster MongoDB Community com Search e pesquisa vetorial instalados.
Chave de API Gêmeos. Este tutorial usa um modelo Gêmeos, mas você pode usar qualquer provedor compatível. Para saber mais, consulte Modelos na documentação do Google ADK.
Python v3.11 ou posterior.
Configurar o ambiente
Nesta seção, você prepara seu ambiente instalando as dependências necessárias, definindo suas variáveis de ambiente e criando um arquivo de projeto .
Defina suas variáveis de ambiente.
No seu diretório google-adk-mongodb-project, crie um arquivo .env e adicione o seguinte código:
GOOGLE_API_KEY="<gemini-api-key>"MONGODB_URI="<connection-string>"Substitua <connection-string> pela string de conexão do seu cluster do Atlas ou da implantação local do Atlas.
Sua string de conexão deve usar o seguinte formato:
mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.netIMPORTANTE: certifique-se de que a string de conexão inclua as credenciais do usuário de banco de dados. Para aprender mais sobre como localizar sua string de conexão, consulte Conectar-se a um cluster por meio de bibliotecas de clientes.
Sua string de conexão deve usar o seguinte formato:
mongodb://localhost:<port-number>/?directConnection=truePara saber mais, consulte Connection strings.
Crie um arquivo de projeto.
No seu diretório google-adk-mongodb-project, crie um arquivo denominado main.py. Adicione o seguinte código a este arquivo para carregar suas variáveis de ambiente e importar os módulos necessários:
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()Em etapas futuras, você adicionará código a este arquivo para criar sua coleção, construir seu agente e executá-lo.
Crie sua collection e índice
Nesta seção, você insere documentos de exemplo sobre pingos em uma coleção do MongoDB e cria o índice do MongoDB Vector Search que o Atlas Automated Embedding exige.
Insira documentos de amostra.
Adicione o seguinte código ao seu arquivo main.py para inserir cinco documentos descrevendo pinguim em sua coleção. O campo embeddings armazena o texto que o Atlas incorpora automaticamente:
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.", }, ])Crie o índice Incorporação automatizada do Atlas .
Adicione o seguinte código ao seu arquivo main.py para criar um índice do MongoDB Vector Search no campoembeddings . O tipo de campo autoEmbed instrui o Atlas a gerar e armazenar automaticamente embeddings para este campo :
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()O índice deve levar cerca de um minuto para criar. Enquanto constrói, o índice está em um estado de sincronização inicial. Quando terminar de ser criado, você poderá começar a consultar os dados em sua coleção.
Configurar ferramentas e sessões do agente
Nesta seção, você constrói um agente que utiliza a classe MongoDbToolset para pesquisar sua coleção. Em seguida, configure a classe MongoDbSessionService para persistir o histórico de conversa do agente no MongoDB.
Configure o conjunto de ferramentas.
Adicione o seguinte código ao seu arquivo main.py para vincular o MongoDbToolset ao seu banco de dados e configurá-lo para utilizar a Incorporação Automatizada do 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", ),)Como a opção use_mongodb_auto_embedding está definida como True, o conjunto de ferramentas envia um texto de query para o Atlas como texto sem formatação em vez de chamar um modelo de incorporação do Google.
Defina o agente.
Adicione o seguinte código ao seu arquivo main.py para criar um agente que use um modelo Gêmeos e seu conjunto de ferramentas:
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],)Configure o serviço de sessão e um executor.
Adicione o seguinte código ao seu arquivo main.py para configurar a classe MongoDbSessionService e passe-a, junto com seu agente, para um objetoRunner :
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,)Por padrão, o MongoDbSessionService cria os índices recomendados para seu uso, a menos que você defina o parâmetro ensure_indexes para False. Para saber mais, consulte Diretivas de índice na referência do Google ADK.
Execute o agente em duas voltas de conversa.
Adicione o seguinte código ao seu arquivo main.py para criar uma sessão e, em seguida, envie duas mensagens para o agente por meio dessa sessão:
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())Como ambas as chamadas usam o mesmo valor de session_id, MongoDbSessionService carrega os eventos do primeiro turno antes que o agente responda à segunda mensagem. Se você criar uma nova sessão para a segunda chamada, o agente não terá registro da primeira chamada.
Execute o arquivo
Para executar o arquivo main.py, execute o seguinte comando do seu diretório google-adk-mongodb-project:
python main.pySe o comando for executado com êxito, a saída se assemelha ao seguinte:
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.Próximos passos
Para saber mais sobre MongoDbToolset, MongoDbSessionService e MongoDbMemoryService, incluindo seu parâmetro completo e referência de método, consulte Integrar MongoDB com Google ADK.
Para saber mais sobre o Google ADK, consulte o repositório adk-python do GitHub.