Atlas Agent Engine is in public preview and may change. MongoDB does not recommend production workloads on it during the preview.
Quick Start
You need Docker running, theagentengine CLI signed in, and a Nimble and an OpenAI API key. See Prerequisites.
http://localhost:3000 and try:
- “What are the latest announcements about MongoDB Atlas?”
- “Summarize https://www.mongodb.com/docs/agentengine/”
- “Research the top three open-source vector databases and compare their licenses.”
MONGODB_URI in .env can stay empty: local runs use their own MongoDB. To use your Atlas cluster in local dev instead, set mongodb.local: false in dev.yaml and fill in MONGODB_URI. Stop it with agentengine dev down.
Prerequisites
- A Nimble API key. Sign up for a free trial.
- The
agentengineCLI, installed and signed in. - Docker, running.
- An OpenAI API key. To use another model provider, see Change the model provider.
Two ways to add Nimble
The starter agent supports both, with the same Nimble API key. The default path defines the tools insrc/hello_world_agent/tools.py with the Nimble Python SDK. The other path serves search and extract from the Nimble MCP server, set up in agent.yaml.
How it works
1
Tools reach only allowed hosts
Nimble tools can call out only to hosts on the
egress list (the outbound allow-list) in agent.yaml. The starter allows sdk.nimbleway.com. Your NIMBLE_API_KEY is passed in as a secret.2
Long research continues across calls
By default, Agent Engine gives each tool call 30 seconds. A Nimble Agent run can take longer, so
nimble_research waits about 20 seconds, then returns status: running with a run_id and agent_id. The model calls the tool again with both until the cited answer is ready.nimble_research defaults to low effort, and the model can request a higher effort per call. Higher efforts cost more per run and take longer (x-high can run 15 to 30 minutes, which means many polling calls). To cap cost, remove the effort argument or limit its values in tools.py.Use the hosted MCP server
To use Nimble’s hosted MCP server for search and extract:1
Add the MCP server to agent.yaml
The starter’s Keep
agent.yaml ships this block commented out. Uncomment it:agent.yaml
allowed_tools set. Without it, the model also sees MCP tools that start paid crawls or delete Nimble Agents.2
Allow the MCP host
Uncomment the
mcp.nimbleway.com entry under egress in agent.yaml, so the sandbox can reach the server.3
Remove the duplicate SDK tools
Delete
nimble_search and nimble_extract from tools.py and from sandboxes.tool.tools in agent.yaml. Otherwise the model sees each tool twice.Deploy
Deploying needs the Project Owner role and an Atlas cluster.agentengine atlas setup connects the cluster, adds Agent Engine to the cluster’s IP access list, and stores its MONGODB_URI as a secret. See MongoDB’s Set Up Atlas Resources guide.
Change the model provider
The starter uses OpenAI. To switch, change the client insrc/hello_world_agent/llm.py. Then replace api.openai.com in the egress list of agent.yaml with your provider’s host.
Good to know
- Use a dedicated Nimble API key for the agent, so you can track its usage separately. Nimble billing is separate from MongoDB billing. See pricing.
- Scope
agent_nameper user.nimble_researchaccepts anagent_nameparameter. All callers that share the same API key and name share that agent’s memory, so in a multi-user deployment, scope the name per user to avoid leaking context between them. - Nimble maintains the starter. For bugs in the starter, open an issue on its GitHub repository. For your Nimble account or API, contact Nimble support.
Resources
Starter agent
The full agent: tools,
agent.yaml, and the MCP alternative.Nimble MCP Server
Tools, authentication, and setup for other MCP clients.
Agent
How Nimble Agents run research and return cited answers.