O MongoDB Atlas oferece diversos recursos para a construção de agentes de AI. Como um banco de dados vetorial e de documentos, o Atlas oferece suporte a vários métodos de pesquisa para RAG de agente, bem como ao armazenamento de interações do agente no mesmo banco de dados para memória de curto e longo prazo do agente.
O que é um agente de AI?
No contexto da IA generativa, um agente de AI geralmente se refere a um sistema que pode completar uma tarefa de forma autônoma ou semiautônoma, combinando modelos de AI, como LLMs com um conjunto de ferramentas predefinidas.
Agentes de AI podem usar ferramentas para reunir contexto, realizar interação com sistemas externos e executar ações. Eles podem definir seu próprio fluxo de execução (planejamento) e lembrar interações anteriores para informar suas respostas (memória). Portanto, os agentes de AI são mais adequados para tarefas complexas que exigem raciocínio, planejamento e tomada de decisões.
Arquitetura
Um agente de AI normalmente inclui uma combinação dos seguintes componentes:
Percepção | Sua informação para o agente. Informações em texto são o mecanismo de percepção mais comum para agentes de AI, mas também podem ser de áudio, imagens ou dados multimodais. |
Planejamento | Como o agente determina o que fazer em seguida. Esse componente normalmente inclui LLMs e prompts, utilizando ciclos de feedback e várias técnicas de engenharia de prompts, como cadeia de pensamento e reAct, para ajudar o LLM a raciocinar sobre tarefas complexas. Os agentes de AI podem consistir em um único LLM como tomador de decisões, um LLM com vários prompts, múltiplos LLMs trabalhando juntos ou qualquer combinação dessas abordagens. |
Ferramentas | Como o agente reúne contexto para uma tarefa. As ferramentas permitem que os agentes interajam com sistemas externos e realizem ações como pesquisa vetorial, pesquisa na web ou chamadas de APIs de outros serviços. |
Memória | Um sistema para armazenar interações do agente, de forma que ele possa aprender com experiências passadas para informar suas respostas. A memória pode ser de curto termo (para a sessão atual) ou de longo termo (persistida entre as sessões). |
Observação
Os agentes de AI variam em padrão de design, função e complexidade. Para aprender mais sobre outras arquiteturas de agentes, incluindo sistemas multiagentes, consulte Padrões de design de agentes.
Crie agentes de AI com o MongoDB
O MongoDB Atlas oferece suporte aos seguintes componentes para a construção de agentes de AI:
Ferramentas: aproveite os recursos de pesquisa do MongoDB como ferramentas para seu agente recuperar informações relevantes e implementar RAG de agente.
Memória: armazene interações de agentes em coleções MongoDB para memória de curto e longo prazo.
Ferramentas do Agente
No contexto de agentes de AI, uma ferramenta é qualquer recurso que possa ser definido e invocado programaticamente pelo agente. As ferramentas ampliam as funcionalidades do agente além da geração de textos, permitindo a interação com sistemas externos, a recuperação de informações e a execução de ações. As ferramentas são tipicamente definidas com uma interface específica que inclui:
Um nome e uma descrição que ajudam o agente a entender quando usar a ferramenta.
Parâmetros obrigatórios e seus formatos esperados.
Uma função que realiza a operação efetiva quando chamada.
O agente utiliza suas capacidades de raciocínio para determinar qual ferramenta empregar, quando utilizá-la e quais parâmetros fornecer, com base na entrada do usuário e na tarefa em questão.
Além das queries padrão do MongoDB, o Atlas oferece várias funcionalidades de pesquisa que você pode implementar como ferramentas para o seu agente.
Atlas Vector Search: realize uma pesquisa vetorial para recuperar o contexto relevante com base no significado semântico e na similaridade. Para aprender mais, consulte Visão geral do Atlas Vector Search.
Atlas Search: realize uma pesquisa de texto completo para recuperar o contexto relevante com base na correspondência de palavras-chave e na pontuação de relevância. Para aprender mais, consulte Visão geral do Atlas Search.
Pesquisa Híbrida: combine o Atlas Vector Search com o Atlas Search para aproveitar os pontos fortes de ambas as abordagens. Para aprender mais, consulte Como fazer a pesquisa híbrida.
Você pode definir ferramentas manualmente ou usando frameworks como LangChain e LangGraph, que fornecem abstrações integradas para criação e chamada de ferramentas.
As ferramentas são definidas como funções que o agente pode chamar para executar tarefas específicas. Por exemplo, a sintaxe a seguir ilustra como você pode definir uma ferramenta que executa uma query de pesquisa vetorial:
def vector_search_tool(query: str) -> str: pipeline = [ { "$vectorSearch": { # Vector search query pipeline... } } ] results = collection.aggregate(pipeline) array_of_results = [] for doc in results: array_of_results.append(doc) return array_of_results
As chamadas de ferramentas são o que o agente usa para executar as ferramentas. Você pode definir como processar chamadas de ferramentas em seu agente ou usar um framework para lidar com isso para você. Normalmente, eles são definidos como objetos JSON que incluem o nome da ferramenta e outros argumentos a serem passados para a ferramenta, para que o agente possa chamar a ferramenta com os parâmetros apropriados. Por exemplo, a sintaxe a seguir ilustra como um agente pode chamar o vector_search_tool:
{ "tool": "vector_search_tool", "args": { "query": "What is MongoDB?" }, "id": "call_H5TttXb423JfoulF1qVfPN3m" }
RAG agêntica
Ao usar o Atlas como um banco de dados vetorial, você pode criar ferramentas de recuperação que implementam o RAG de agente, que é uma forma avançada de RAG que permite orquestrar dinamicamente o processo de recuperação e geração por meio de um agente de AI.
Esta abordagem possibilita fluxos de trabalho e interações com o usuário mais complexos. Por exemplo, você pode configurar seu agente de AI para determinar a ferramenta de recuperação ideal com base na tarefa, como usar o Atlas Vector Search para pesquisa semântica e o Atlas Search para pesquisa de texto completo. Você também pode definir diferentes ferramentas de recuperação para diferentes coleções para personalizar ainda mais as funcionalidades de recuperação do agente.
Memória de agente
A memória para agentes envolve armazenar informações sobre interações anteriores, para que o agente possa aprender com experiências passadas e fornecer respostas mais relevantes e personalizadas. Isso é particularmente importante para tarefas que exigem contexto, como agentes conversacionais, em que o agente precisa se lembrar das interações anteriores na conversa para fornecer respostas coerentes e relevantes ao contexto. Existem dois tipos primários de memória de agente:
Memória de curto prazo: armazena informações para a sessão atual, como as últimas interações e o contexto da tarefa ativa.
Memória de longo prazo: persiste informações entre sessões, podendo incluir conversas passadas e preferências personalizadas ao longo do tempo.
Como o Atlas também é um banco de dados de documentos, você pode implementar memória para agentes armazenando suas interações em uma coleção do MongoDB. O agente pode então realizar a query ou atualizar essa coleção conforme necessário. Existem várias maneiras de implementar a memória do agente com o MongoDB:
Para a memória de curto prazo, você pode incluir um campo
session_idpara identificar uma sessão específica ao armazenar interações e, em seguida, consultar as interações com o mesmo ID para passá-las ao agente como contexto.Para memória de longo prazo, você pode processar várias interações com um LLM para extrair informações relevantes, como preferências do usuário ou contexto importante, e então armazenar essas informações em uma coleção separada que o agente pode consultar quando necessário.
Para criar sistemas robustos de gerenciamento de memória que permitam uma recuperação mais eficiente e complexa de histórico de conversas, aproveite o Atlas Search ou o Atlas Vector Search para indexar e consultar suas interações armazenadas.
Um documento em uma coleção que armazena memória de curto prazo pode ser semelhante ao seguinte:
{ "session_id": "123", "user_id": "jane_doe", "interactions": [ { "role": "user", "content": "What is MongoDB?", "timestamp": "2025-01-01T12:00:00Z" }, { "role": "assistant", "content": "MongoDB is the world's leading modern database.", "timestamp": "2025-01-01T12:00:05Z" } ] }
Um documento em uma coleção que armazena memória de longo prazo pode ser semelhante ao seguinte:
{ "user_id": "jane_doe", "last_updated": "2025-05-22T09:15:00Z", "preferences": { "conversation_tone": "casual", "custom_instructions": [ "I prefer concise answers." ], }, "facts": [ { "interests": ["AI", "MongoDB"], } ] }
Os seguintes frameworks também oferecem abstrações diretas para a memória de agente com MongoDB:
Framework | Características |
|---|---|
LangChain |
Para aprender mais, consulte o tutorial. |
LangGraph |
Para aprender mais, veja LangGraph e LangGraph.js. |
Começar
O tutorial a seguir demonstra como criar um agente de AI usando o Atlas para RAG de agente e memória, sem um framework de agente.
Trabalhe com uma versão executável deste tutorial como um notebook do Python.
Pré-requisitos
Para concluir este tutorial, você deve ter o seguinte:
Uma conta do Atlas com um cluster executando o MongoDB versão 6.0.11, 7.0.2 ou posterior (incluindo RCs). Certifique-se de que seu endereço IP esteja incluído na lista de acesso do seu projeto Atlas. Para saber mais, consulte Criar um cluster.
Uma chave de API do Voyage AI.
Uma chave de API OpenAI.
Observação
Este tutorial usa modelos da Voyage AI e da OpenAI, mas você pode alterar o código para utilizar os modelos de sua preferência.
Procedimento
Esse agente de AI pode ser usado para responder a perguntas sobre uma fonte de dados personalizada e realizar cálculos. Ele também pode lembrar de interações anteriores para informar suas respostas. Ele usa os seguintes componentes:
Percepção: entradas de texto.
Planejamento: um LLM e várias instruções para raciocinar sobre a tarefa.
Ferramentas: uma ferramenta de pesquisa vetorial e uma ferramenta de cálculo.
Memória: armazena as interações em uma coleção do MongoDB.
Configure o ambiente.
Inicialize o projeto e instale dependências.
Crie um novo diretório de projeto e, em seguida, instale as dependências necessárias:
mkdir mongodb-ai-agent cd mongodb-ai-agent pip install --quiet --upgrade pymongo voyageai openai langchain langchain_mongodb langchain_community Observação
Seu projeto usará a seguinte estrutura:
mongodb-ai-agent ├── config.py ├── ingest-data.py ├── tools.py ├── memory.py ├── planning.py ├── main.py Configure o ambiente.
Crie um arquivo chamado
config.pyem seu projeto. Esse arquivo conterá suas chaves de API para o agente, a string de conexão do Atlas e os nomes do banco de dados, e da coleção do MongoDB.Substitua os valores de espaço reservado pela string de conexão do Atlas e pelas chaves de API do Voyage AI e OpenAI.
from pymongo import MongoClient from openai import OpenAI import voyageai MONGODB_URI = "<connection-string>" VOYAGE_API_KEY = "<voyage-api-key>" OPENAI_API_KEY = "<openai-api-key>" # MongoDB Atlas configuration mongo_client = MongoClient(MONGODB_URI) agent_db = mongo_client["ai_agent_db"] vector_collection = agent_db["embeddings"] memory_collection = agent_db["chat_history"] # Model configuration voyage_client = voyageai.Client(api_key=VOYAGE_API_KEY) client = OpenAI(api_key=OPENAI_API_KEY) VOYAGE_MODEL = "voyage-3-large" OPENAI_MODEL = "gpt-4o" Observação
Sua string de conexão deve usar o seguinte formato:
mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net
Use o Atlas como um banco de dados vetorial.
Crie um arquivo chamado ingest-data.py em seu projeto. Este script ingere um PDF de amostra que contém um relatório de ganhos recentes do MongoDB em uma coleção no Atlas usando o modelo de incorporação voyage-3-large.
Para aprender mais, consulte Ingestão.
from config import vector_collection, voyage_client, VOYAGE_MODEL from pymongo.operations import SearchIndexModel from langchain_community.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter import time # Define a function to generate embeddings def get_embedding(data, input_type = "document"): embeddings = voyage_client.embed( data, model = VOYAGE_MODEL, input_type = input_type ).embeddings return embeddings[0] # --- Ingest embeddings into MongoDB Atlas --- def ingest_data(): # Chunk PDF data loader = PyPDFLoader("https://investors.mongodb.com/node/13176/pdf") data = loader.load() text_splitter = RecursiveCharacterTextSplitter(chunk_size=400, chunk_overlap=20) documents = text_splitter.split_documents(data) print(f"Successfully split PDF into {len(documents)} chunks.") # Ingest chunked documents into collection print("Generating embeddings and ingesting documents...") docs_to_insert = [] for i, doc in enumerate(documents): embedding = get_embedding(doc.page_content) if embedding: docs_to_insert.append({ "text": doc.page_content, "embedding": embedding }) if docs_to_insert: result = vector_collection.insert_many(docs_to_insert) print(f"Inserted {len(result.inserted_ids)} documents into the collection.") else: print("No documents were inserted. Check embedding generation process.") # --- Create the vector search index --- index_name = "vector_index" search_index_model = SearchIndexModel( definition = { "fields": [ { "type": "vector", "numDimensions": 1024, "path": "embedding", "similarity": "cosine" } ] }, name=index_name, type="vectorSearch" ) try: vector_collection.create_search_index(model=search_index_model) print(f"Search index '{index_name}' creation initiated.") except Exception as e: print(f"Error creating search index: {e}") return # Wait for initial sync to complete print("Polling to check if the index is ready. This may take up to a minute.") predicate=None if predicate is None: predicate = lambda index: index.get("queryable") is True while True: indices = list(vector_collection.list_search_indexes(index_name)) if len(indices) and predicate(indices[0]): break time.sleep(5) print(index_name + " is ready for querying.")
Defina as ferramentas para o agente.
Crie um arquivo chamado tools.py em seu projeto. Esse arquivo define as ferramentas que o agente pode usar para dar resposta às perguntas. Neste exemplo, você define as seguintes ferramentas:
vector_search_tool: executa uma query de pesquisa vetorial para recuperar documentos relevantes da sua coleção.calculator_tool: usa a funçãoeval()para operações matemáticas básicas.
from config import vector_collection from ingest_data import get_embedding # Define a vector search tool def vector_search_tool(user_input: str) -> str: query_embedding = get_embedding(user_input) pipeline = [ { "$vectorSearch": { "index": "vector_index", "queryVector": query_embedding, "path": "embedding", "exact": True, "limit": 5 } }, { "$project": { "_id": 0, "text": 1 } } ] results = vector_collection.aggregate(pipeline) array_of_results = [] for doc in results: array_of_results.append(doc) return array_of_results # Define a simple calculator tool def calculator_tool(user_input: str) -> str: try: result = eval(user_input) return str(result) except Exception as e: return f"Error: {str(e)}"
Adicione memória ao agente.
Crie um arquivo chamado memory.py em seu projeto. Esse arquivo define o sistema que o agente utiliza para armazenar suas interações. Neste exemplo, você implementa a memória de curto prazo ao definir as seguintes funções:
store_chat_message: para armazenar informações sobre uma interação em uma coleção do MongoDB.retrieve_session_history: para obter todas as interações de uma sessão específica usando o camposession_id.
from config import memory_collection from datetime import datetime from typing import List def store_chat_message(session_id: str, role: str, content: str) -> None: message = { "session_id": session_id, # Unique identifier for the chat session "role": role, # Role of the sender (user or system) "content": content, # Content of the message "timestamp": datetime.now(), # Timestamp of when the message was sent } memory_collection.insert_one(message) def retrieve_session_history(session_id: str) -> List: # Query the collection for messages with a specific "session_id" in ascending order cursor = memory_collection.find({"session_id": session_id}).sort("timestamp", 1) # Iterate through the cursor and return a JSON object with the message role and content if cursor: messages = [{"role": msg["role"], "content": msg["content"]} for msg in cursor] else: messages = [] return messages
Defina o planejamento do agente.
Crie um arquivo chamado planning.py em seu projeto. Esse arquivo incluirá vários prompts e chamadas LLM para determinar o fluxo de execução do agente. Neste exemplo, você define as seguintes funções:
tool_selector: determina como o LLM seleciona a ferramenta apropriada para uma tarefa.generate_answer: orquestra o fluxo de execução do agente utilizando ferramentas, chamando o LLM e processando os resultados.get_llm_response: função de assistente para geração de resposta LLM.
from config import openai_client, OPENAI_MODEL from tools import vector_search_tool, calculator_tool from memory import store_chat_message, retrieve_session_history # Define a tool selector function that decides which tool to use based on user input and message history def tool_selector(user_input, session_history=None): messages = [ { "role": "system", "content": ( "Select the appropriate tool from the options below. Consider the full context of the conversation before deciding.\n\n" "Tools available:\n" "- vector_search_tool: Retrieve specific context about recent MongoDB earnings and announcements\n" "- calculator_tool: For mathematical operations\n" "- none: For general questions without additional context\n" "Process for making your decision:\n" "1. Analyze if the current question relates to or follows up on a previous vector search query\n" "2. For follow-up questions, incorporate context from previous exchanges to create a comprehensive search query\n" "3. Only use calculator_tool for explicit mathematical operations\n" "4. Default to none only when certain the other tools won't help\n\n" "When continuing a conversation:\n" "- Identify the specific topic being discussed\n" "- Include relevant details from previous exchanges\n" "- Formulate a query that stands alone but preserves conversation context\n\n" "Return a JSON object only: {\"tool\": \"selected_tool\", \"input\": \"your_query\"}" ) } ] if session_history: messages.extend(session_history) messages.append({"role": "user", "content": user_input}) response = openai_client.chat.completions.create( model=OPENAI_MODEL, messages=messages ).choices[0].message.content try: tool_call = eval(response) return tool_call.get("tool"), tool_call.get("input") except: return "none", user_input # Define the agent workflow def generate_response(session_id: str, user_input: str) -> str: # Store the user input in the chat history collection store_chat_message(session_id, "user", user_input) # Initialize a list of inputs to pass to the LLM llm_input = [] # Retrieve the session history for the current session and add it to the LLM input session_history = retrieve_session_history(session_id) llm_input.extend(session_history) # Append the user message in the correct format user_message = { "role": "user", "content": user_input } llm_input.append(user_message) # Call the tool_selector function to determine which tool to use tool, tool_input = tool_selector(user_input, session_history) print("Tool selected: ", tool) # Process based on selected tool if tool == "vector_search_tool": context = vector_search_tool(tool_input) # Construct the system prompt using the retrieved context and append it to the LLM input system_message_content = ( f"Answer the user's question based on the retrieved context and conversation history.\n" f"1. First, understand what specific information the user is requesting\n" f"2. Then, locate the most relevant details in the context provided\n" f"3. Finally, provide a clear, accurate response that directly addresses the question\n\n" f"If the current question builds on previous exchanges, maintain continuity in your answer.\n" f"Only state facts clearly supported by the provided context. If information is not available, say 'I DON'T KNOW'.\n\n" f"Context:\n{context}" ) response = get_llm_response(llm_input, system_message_content) elif tool == "calculator_tool": # Perform the calculation using the calculator tool response = calculator_tool(tool_input) else: system_message_content = "You are a helpful assistant. Respond to the user's prompt as best as you can based on the conversation history." response = get_llm_response(llm_input, system_message_content) # Store the system response in the chat history collection store_chat_message(session_id, "system", response) return response # Helper function to get the LLM response def get_llm_response(messages, system_message_content): # Add the system message to the messages list system_message = { "role": "system", "content": system_message_content, } # If the system message should go at the end (for context-based queries) if any(msg.get("role") == "system" for msg in messages): messages.append(system_message) else: # For general queries, put system message at beginning messages = [system_message] + messages # Get response from LLM response = openai_client.chat.completions.create( model=OPENAI_MODEL, messages=messages ).choices[0].message.content return response
Teste o agente.
Por fim, crie um arquivo chamado main.py em seu projeto. Esse arquivo executa o agente e permite a interação com ele.
from config import mongo_client from ingest_data import ingest_data from planning import generate_response if __name__ == "__main__": try: run_ingest = input("Ingest sample data? (y/n): ") if run_ingest.lower() == 'y': ingest_data() session_id = input("Enter a session ID: ") while True: user_query = input("\nEnter your query (or type 'quit' to exit): ") if user_query.lower() == 'quit': break if not user_query.strip(): print("Query cannot be empty. Please try again.") continue answer = generate_response(session_id, user_query) print("\nAnswer:") print(answer) finally: mongo_client.close()
Salve seu projeto e execute o seguinte comando. Quando você executar o agente:
Caso ainda não tenha feito, instrua o agente a ingerir os dados de amostra.
Digite um ID de sessão para começar uma nova sessão ou continuar uma já existente.
Faça perguntas. O agente gera uma resposta com base nas suas ferramentas, nas interações anteriores e nos prompts definidos na fase de planejamento. Consulte o exemplo de saída para uma interação de amostra:
python main.py
Ingest sample data? (y/n): y Successfully split PDF into 104 chunks. Generating embeddings and ingesting documents... Inserted 104 documents into the collection. Search index 'vector_index' creation initiated. Polling to check if the index is ready. This may take up to a minute. vector_index is ready for querying. Enter a session ID: 123 Enter your query (or type 'quit' to exit): What was MongoDB's latest acquisition? Tool selected: vector_search_tool Answer: MongoDB's latest acquisition was Voyage AI. Enter your query (or type 'quit' to exit): What do they do? Tool selected: vector_search_tool Answer: Voyage AI is a company that specializes in state-of-the-art embedding and reranking models designed to power next-generation AI applications. These technologies help organizations build more advanced and trustworthy AI capabilities. Enter your query (or type 'quit' to exit): What is 123+456? Tool selected: calculator_tool Answer: 579
Dica
Você pode visualizar suas incorporações e interações na IU do Atlas navegando até o banco de dados ai_agent_db no seu cluster e selecionando as coleções embeddings ou chat_history.
Continue a construir.
Agora que você possui um agente básico de AI, você pode continuar a desenvolvê-lo da seguinte maneira:
Melhorando o desempenho das suas ferramentas de pesquisa vetorial e pelo ajuste fino dos seus pipelines RAG.
Adicionar mais ferramentas ao agente, como ferramentas híbridas ou de pesquisa de texto completo.
Aprimorando a fase de planejamento ao utilizar prompts mais avançados e chamadas de LLM.
Implemente a memória de longo prazo e sistemas de memória mais avançados usando o Atlas Search ou o Atlas Vector Search para indexar e consultar suas interações armazenadas.
Tutorials
Para mais tutoriais sobre a construção de agentes de AI com o MongoDB, consulte a tabela a seguir:
Frameworks | |
Plataformas de empresas | |
Recursos adicionais |