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.
Menu Docs

Integre o MongoDB com o SDK dos agentes OpenAI

Você pode usar o MongoDB como banco de dados de apoio para os agentes que você cria com o SDK do OpenAI Agents. O Agents SDK é uma estrutura Python para criar aplicativos agentes a partir de um pequeno conjunto de primitivos:

  • Agentes, que são modelos de linguagem grandes (LLMs) configurados com instruções e ferramentas.

  • Transferências, quepermitem que um agente delegue uma tarefa a outro agente.

  • Proteções, que validam as entradas e saídas de um agente.

  • Sessões, que armazenam o histórico de conversas entre as execuções do agente .

O SDK segue dois princípios de design. Inclui recursos suficientes para construir aplicativos reais, mas poucos primitivos suficientes para aprender em um curto espaço de tempo. Seus padrões também produzem bons resultados, e você pode personalizar cada etapa da execução de um agente .

O Agents SDK fornece MongoDBSession, uma implementação de sessão que persiste o histórico de conversas no MongoDB. Armazenar esse histórico no MongoDB oferece aos seus agentes as seguintes vantagens:

  • Armazenamento de sessão de vários processos horizontalmente escalável. O estado da sessão reside em seu cluster e não na memória de um único processo, portanto, qualquer trabalhador, contêiner ou função sem servidor que se conecte ao mesmo cluster pode continuar uma conversa. Cada mensagem carrega um seq contador monotonicamente crescente, que preserva a ordem das mensagens entre os gravadores simultâneos.

  • Um banco de dados para conversas e dados de aplicação . Se o seu aplicação já usa o MongoDB, seus agentes leem os dados operacionais e gravam o histórico da sessão por meio da mesma conexão e do mesmo driver, sem um serviço de memória separado para implantar e proteger.

  • Documentos flexíveis para o estado do agente . O modelo de documento armazena mudanças de conversa, chamadas de ferramentas e saídas estruturadas à medida que evoluem, para que você possa estender o que registro sem uma migração de esquema.

  • Histórico do agente consultável. O histórico de sessões é armazenado em collections comuns, para que você possa consultá-lo, agregá-lo e indexá-lo para auditar o comportamento do agente ou criar análises.

  • Um caminho para a recuperação. Como seus agentes já se conectam ao MongoDB, você pode adicionar o MongoDB Vector Search ao mesmo cluster para fornecer a eles recuperação semântica de seus dados. Para saber mais, consulte Agentic RAG.

Neste tutorial, você constrói um assistente de viagem multiagente. Um agente de triagem responde a perguntas ligando para dois agentes especializados como ferramentas, e ambos os especialistas leem dados de referência do mesmo cluster que armazena a sessão de conversa.

Para concluir este tutorial, você deve ter o seguinte:

  • Python 3.10 ou posterior.

  • Um dos seguintes tipos de cluster MongoDB :

    • Um cluster do Atlas executando a versão 6.0.11 do MongoDB, 7.0.2, ou posterior. Certifique-se de que seu endereço IP esteja incluído na lista de acesso do seu projeto Atlas.

    • Um sistema local do Atlas criado usando Python e Docker. Instale atlas-local-lib-py opip 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 da MongoDB Community com o Search e o Vector Search instalados.

  • Uma chave de API da OpenAI. Você deve ter uma conta da OpenAI com créditos disponíveis para solicitações de API. Para saber mais sobre como registrar uma conta OpenAI, consulte o site da API OpenAI.

1

Este tutorial utiliza uv para gerenciar o ambiente:

uv venv
source .venv/bin/activate
2

Instale o Agents SDK com o mongodb extra. Cite o nome do pacote para que seu shell não interprete os colchetes:

uv pip install "openai-agents[mongodb]"

O extra instala o pymongo versão 4.14 ou posterior, que fornece a classe AsyncMongoClient que a sessão e as ferramentas do agente utilizam.

3

O aplicação lê sua string de conexão do Atlas a partir de ATLAS_URI e o SDK do Agents lê sua chave a partir de OPENAI_API_KEY:

export ATLAS_URI="<connection-string>"
export OPENAI_API_KEY="<api-key>"

Substitua o valor do espaço reservado <connection-string> pela string de conexão SRV do seu cluster.

Sua string de conexão deve usar o seguinte formato:

mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net
1

Crie um arquivo denominado multi_agent_app.py e cole o seguinte código nele. Os comentários in-line explicam como cada parte do aplicação usa o MongoDB.

multi_agent_app.py
"""Multi-agent travel assistant backed by MongoDB Atlas.
A triage agent answers travel questions by calling two specialist
agents as tools. Both specialists read reference data from the same
Atlas cluster that stores the conversation session, so every agent in
the application shares one database.
"""
import asyncio
import os
from agents import Agent, Runner, function_tool
from agents.extensions.memory import MongoDBSession
from pymongo import AsyncMongoClient
# The script reads your credentials from the environment so that you
# don't commit them to source control.
REQUIRED_ENV_VARS = ("ATLAS_URI", "OPENAI_API_KEY")
DATABASE_NAME = "travel_assistant"
# One client serves both the agent tools and the session store. Because
# you create the client yourself, your application owns its lifecycle.
# main() assigns both of these after it validates the environment.
client: AsyncMongoClient | None = None
database = None
@function_tool
async def lookup_destination(city: str) -> str:
"""Look up travel guidance for a destination city."""
# Sub-agent tools query the shared database directly, so the agents
# answer from your data instead of from model training data.
document = await database.destinations.find_one({"city": city})
if document is None:
return f"No destination guide found for {city}."
return (
f"{document['city']}: best months are {document['best_months']}. "
f"{document['summary']}"
)
@function_tool
async def lookup_policy(topic: str) -> str:
"""Look up the company travel policy for a topic."""
document = await database.policies.find_one({"topic": topic})
if document is None:
return f"No policy found for {topic}."
return f"{document['topic']}: {document['rule']}"
# Each specialist is a full agent with its own instructions and tools.
destination_agent = Agent(
name="Destination expert",
instructions=(
"You advise travelers on destinations. Always call "
"lookup_destination and answer only from what it returns."
),
tools=[lookup_destination],
)
policy_agent = Agent(
name="Policy expert",
instructions=(
"You answer questions about the company travel policy. Always "
"call lookup_policy and answer only from what it returns."
),
tools=[lookup_policy],
)
# The as_tool() pattern turns each specialist into a tool that the
# triage agent can call. Unlike a handoff, control returns to the
# triage agent after each call, so it can combine both answers in one
# reply.
triage_agent = Agent(
name="Travel assistant",
instructions=(
"You are a travel assistant. Use the destination and policy "
"tools to gather facts before you answer, and call both when "
"the question needs both. Remember details the traveler shared "
"earlier in the conversation."
),
tools=[
destination_agent.as_tool(
tool_name="ask_destination_expert",
tool_description="Get travel guidance about a city.",
),
policy_agent.as_tool(
tool_name="ask_policy_expert",
tool_description="Get the company travel policy for a topic.",
),
],
)
async def seed_reference_data() -> None:
"""Load the sample data that the specialist agents read."""
await database.destinations.delete_many({})
await database.policies.delete_many({})
await database.destinations.insert_many(
[
{
"city": "Lisbon",
"best_months": "March through May",
"summary": "Mild spring weather and low hotel rates.",
},
{
"city": "Reykjavik",
"best_months": "June through August",
"summary": "Long daylight hours and open highland roads.",
},
]
)
await database.policies.insert_many(
[
{"topic": "flights", "rule": "Book economy for flights under six hours."},
{"topic": "hotels", "rule": "Nightly rates must stay under 250 USD."},
]
)
async def main() -> None:
global client, database
# Fail fast with a clear message instead of surfacing a connection
# error or an authentication error later in the run.
missing = [name for name in REQUIRED_ENV_VARS if not os.environ.get(name)]
if missing:
raise SystemExit(
"Set these environment variables before you run this script: "
+ ", ".join(missing)
)
client = AsyncMongoClient(os.environ["ATLAS_URI"])
database = client[DATABASE_NAME]
await seed_reference_data()
# The session stores conversation history in Atlas. Pass the
# existing client so the session and the agent tools share one
# connection pool.
session = MongoDBSession(
session_id="traveler-123",
client=client,
database=DATABASE_NAME,
)
# Confirm connectivity before the first run.
await session.ping()
# The Runner loads prior turns from the session and writes the new
# turn back, so the second question resolves "there" without you
# passing the history yourself.
first = await Runner.run(
triage_agent,
"I'm planning a trip to Lisbon. When should I go?",
session=session,
)
print(first.final_output)
second = await Runner.run(
triage_agent,
"What's our hotel budget for that trip?",
session=session,
)
print(second.final_output)
# session.close() is a no-op when you supply the client, so close
# the client yourself.
await client.close()
if __name__ == "__main__":
asyncio.run(main())
2
python multi_agent_app.py

O agente responde à primeira pergunta da collection destinations e à segunda pergunta da collection policies. Como a sessão armazena a primeira curva no MongoDB, o assistente resolve "aquela viagem" na segunda pergunta sem que você mesmo passe a história.

Seu resultado pode ser diferente, pois o modelo gera uma nova resposta para cada execução.

For Lisbon, the best time to go is **March through May**.
That's the sweet spot for **mild weather**, comfortable sightseeing, **fewer crowds**, and generally **better hotel rates** than peak summer. If you want the best single month, I'd pick **May** for warmer days while still avoiding the biggest summer crowds.
I still don't see a company policy entry for a **Lisbon hotel budget/nightly cap**.
Best next step: check the company booking tool or ask your travel/admin team to confirm the approved lodging allowance for Lisbon.

O aplicação cria um AsyncMongoClient e o compartilha entre os agentes e a sessão:

  • Os agentes especializados fazem query das collections destinations e policies a partir de suas funções de ferramenta, então eles respondem a partir de seus dados.

  • MongoDBSession grava cada conversa nas coleções agent_sessions e agent_messages no mesmo banco de dados. Ambos os nomes de coleção são configuráveis e a sessão cria os índices necessários no primeiro uso.

Como o aplicação constrói o próprio cliente , o ciclo de vida do cliente pertence ao aplicação e session.close() não faz nada. Para que a sessão seja própria do cliente , crie-a com MongoDBSession.from_uri().

Para saber mais sobre como coordenar vários agentes com o SDK dos agentes, consulte as seguintes páginas na documentação do OpenAI:

  • Ordenação de vários agentes para as trocas entre orquestração por código e orquestração por meio de um LLM.

  • Transferências por delegar uma conversa para outro agente em vez de chamá-la como uma ferramenta.

  • Proteções para validar entradas e saídas do agente .

  • Sessões para a MongoDBSession referência completa.