Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Primeiros passos com a integração do MongoDB Google ADK

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:

  1. Configure seu ambiente.

  2. Crie uma coleção e um índice de pesquisa vetorial .

  3. Construa um agente que pesquise sua collection.

  4. Adicione sessões persistentes para que o agente se lembre das voltas anteriores.

  5. Execute o arquivo e revise a saída.

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 MongoDB

  • MongoDbSessionService: 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.

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.

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 .

1

Execute os seguintes comandos no seu terminal para criar um novo diretório denominado google-adk-mongodb-project e instalar as dependências necessárias:

mkdir google-adk-mongodb-projectcd google-adk-mongodb-projectpip install "google-adk[mongodb]" python-dotenv
2

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.net

IMPORTANTE: 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.

3

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.

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.

1

Adicione o seguinte código ao seu arquivo main.py para criar uma coleção penguins no banco de dadosgoogle_adk_tutorial ou acesse-a se a coleção já existir:

client = MongoClient(os.environ["MONGODB_URI"])collection = client["google_adk_tutorial"]["penguins"]
2

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.", }, ])
3

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.

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.

1

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.

2

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],)
3

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.

4

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.

Para executar o arquivo main.py, execute o seguinte comando do seu diretório google-adk-mongodb-project:

python main.py

Se 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.

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.