Skip to main content
Give an agent on MongoDB Atlas Agent Engine, MongoDB’s platform to build, deploy, and govern agents, live web data from Nimble. The starter agent searches the web, reads pages, and runs multi-step research, then cites its sources.
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, the agentengine CLI signed in, and a Nimble and an OpenAI API key. See Prerequisites.
Open the playground at 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

Two ways to add Nimble

The starter agent supports both, with the same Nimble API key. The default path defines the tools in src/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 agent.yaml ships this block commented out. Uncomment it:
agent.yaml
Keep 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 in src/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_name per user. nimble_research accepts an agent_name parameter. 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.