This article was written by Damilola Oladele.

Imagine you built an employee onboarding assistant agent for your company. The agent answers questions about company policies, guides new employees through onboarding, and provides role-specific training.

As employees begin using the agent, you encounter a few challenges. The agent cannot remember previous conversations, so employees must repeat information they have already provided. It also struggles to retrieve accurate answers from company documents and sometimes recommends training that employees have already completed. You might also want to monitor its behavior and ensure it only accesses information that each employee is authorized to see.

A common approach to addressing these challenges is to combine several systems. You might use a vector database to retrieve company documents and a separate database to store conversation history. An agent framework would coordinate workflows, while an observability platform would monitor agent execution. You would also need infrastructure to run the agent and enforce security policies. While this approach works, integrating and maintaining these systems introduces additional complexity.

So instead of building and managing these systems separately, you can use MongoDB Atlas Agent Engine (Agent Engine). It provides a unified platform that runs AI agents, stores conversation history, manages long-term memory, retrieves relevant information, and monitors agent execution.

This tutorial helps you get started with Agent Engine. You'll install the agentengine CLI, scaffold a Hello World agent, test it locally, and deploy it to Agent Engine.

The following flowchart outlines the local setup and deployment stages:

The tutorial uses OpenRouter's free tier and a free Atlas M0 cluster, so you don't need a credit card.

Note: Agent Engine is in public preview. MongoDB intends it for evaluation and prototyping, and doesn't recommend production deployments during preview. MongoDB expects breaking changes periodically. When your terminal output differs from this tutorial, trust your terminal.

Prerequisites

Before you start, make sure you have the following ready:

  • Operating system: macOS or Linux.
  • Git: Git installed on your machine
  • Docker Desktop: Docker Desktop installed and running on your machine.
  • Python: Version 3.1 or later installed on your machine.

  • Atlas cluster: A MongoDB Atlas account with a free M0 cluster.

    Note: Agent Engine doesn't support Atlas free clusters. This tutorial turns off the memory feature and stores only a few short sessions, so it can run on an M0 cluster. For an agent that uses the memory feature, use a Flex cluster or higher. To learn more, see Set Up Atlas Resources and Atlas Free Cluster Limits.

  • Connection string: The connection string for your Atlas cluster. In Atlas, click Connect on your cluster, then select Drivers. Atlas prompts you to create a database user if you don't have one.

  • Voyage AI API key: An API key created in the same Atlas project as your cluster. To create one, follow these steps:

1. Sign in to your Atlas account, the same one as your M0 cluster. 2. Go to **SERVICES > AI Model APIs**. 3. Select **Create model API key**. 4. Give it a name, then select **Create**. 5. Copy the key immediately and store it somewhere safe.
  • OpenRouter account: A free OpenRouter account with an API key.

Install the agentengine CLI

The agentengine CLI creates, runs, and deploys your agent, so it's the first tool to set up. Download it from the CLI download page, and follow the instructions for your operating system. The page requires an Atlas sign-in. You can also open it from the Atlas UI, under SERVICES > Agent Engine > Open Agent Engine, then Authorize.

When I first tried installing the CLI, the installation failed with a network error. If you encounter the same issue, try running the installer again or switching to the manual download tab on the same page.

Confirm the installation:

agentengine --version

If the installation succeeds, the command displays the installed version, such as 0.1.120.

Sign In to Atlas Agent Engine

Now sign in with your Atlas login information to allow the CLI to access your Atlas account:

agentengine auth login

A sign-in URL opens in your browser. After you sign in, the terminal confirms it:

Open the following URL to authenticate: https://agentengine.mongodb.com/auth/start?... Successfully logged in.

Set Up Docker for Local Development

After signing in to Agent Engine, set up Docker to run the agent locally in containers. Before you begin local development, check that Docker meets these three requirements:

  • Docker Desktop is installed on your machine.
  • The Docker daemon is running. Launching Docker Desktop starts it.
  • The docker command works in your terminal.

Launch Docker Desktop, then check all three conditions at once:

docker info

If the command displays both client and server details, then Docker is ready. If your shell can't find docker, then the command isn't on your PATH. So add the directory containing the Docker CLI to your PATH, then try again. If the command runs but can't connect to the server, then make sure Docker Desktop has finished starting.

Get a Free OpenRouter API Key

Your agent needs a language model to generate responses. The next step is to obtain an LLM API key. OpenRouter provides one API for many models, including free ones, and you don't need a credit card to use it.

Go to OpenRouter, create an account, and open your account settings. Create a new API key, copy it, and save it. You'll paste it when prompted in the next section.

OpenRouter's free models have the following rate limits:

  • 20 requests per minute.
  • 50 requests per day for accounts that have never purchased credits, or 1,000 requests per day for accounts that have purchased at least $10 in credits.

One message to your agent can trigger multiple model requests. This is because the agent calls the model, runs its tools, and calls the model again to generate a response. A 50-request daily allowance is enough for this tutorial.

The Hello World agent calls tools to process your request, so its model must support tool calling. I chose nvidia/nemotron-3.5-lightning:free because it supports tool calling and is available on OpenRouter's free tier. To list every free model that supports tool calling, query OpenRouter's public models endpoint by running the following in your terminal:

curl -sS https://openrouter.ai/api/v1/models | python3 -c " import json, sys for m in json.load(sys.stdin)['data']: if m['id'].endswith(':free') and 'tools' in (m.get('supported_parameters') or []): print(m['id']) "

Any model in that list can run this agent.

Scaffold a Hello World Agent

With the tools ready, generate the agent and confirm it can reach its model before you start any containers.

The agentengine create command builds the project directory from MongoDB's Hello World template. Typing back at any prompt returns you to the previous one:

agentengine create

Answer the prompts as follows:

Prompt Answer
Starter template Hello World Agent
Framework and language Google ADK + Python
Application name my-agent
Local directory accept the default
LLM connection OpenRouter
Model or deployment name nvidia/nemotron-3.5-lightning:free
LLM API key your OpenRouter key
Enable memory for local dev no
External host access accept the recommended egress option
Smoke test yes

After the prompts, the CLI reports what it generated and runs the smoke test:

✓ Created my-agent from the Hello World Agent (Google ADK) template ✓ Personalized app name, slug, module, and local defaults ✓ Applied the selected LLM connection to the agent source ✓ Wrote .env ✓ Declared network.egress for openrouter.ai:443 (Agent and Tool) This list covers the LLM only. Add other destinations in agent.yaml under network.egress, or later with `agentengine agent egress add <fqdn>:443`. ✓ Installed the Atlas Agent Engine skill for Codex, Copilot, and Claude Code ✓ Installed the Atlas Agent Engine docs skill. Ask your coding agent platform questions to retrieve current docs. Smoke test now? (one 'Hello' request from this machine, 10s timeout) [Y/n] y ✓ openrouter/nvidia/nemotron-3.5-lightning:free responded in 4.4s Next: 1. cd my-agent/agents/my-agent 2. agentengine dev up 3. When you're ready to deploy: agentengine deploy

The final line, ✓ openrouter/nvidia/nemotron-3.5-lightning:free responded in 4.4s, confirms that the generated agent reached OpenRouter and received a response. That rules out key and network problems before Docker is involved.

During my earlier setup attempt, the smoke test prompt returned an HTTP 401 (Unauthorized) error, even though my OpenRouter API key was valid. If you encounter the same error, don't assume that project creation failed. Continue with the instructions in the Run the Agent Locally section.

Explore the Hello World Agent

The agentengine create command creates a my-agent project directory containing an agents/ directory, with your agent in a subdirectory. Your project structure looks like this:

my-agent/ ├── project-config.yaml └── agents/ └── my-agent/ ├── agent.yaml ├── pyproject.toml ├── .env └── src/ └── agent_my_agent/ ├── main.py ├── llm.py ├── system_message.py └── tools.py

The agent.yaml file tells Agent Engine what your agent is called, which tools it has, and where it can connect:

# Human-readable app slug used by Agent Engine tooling. # `agentengine create` should rewrite this when generating a new app from the template. name: my-agent # Python import path to the SDK App instance. # Format: <module path>:<variable name>. This template exposes `app` from # src/agent_my_agent/main.py. entrypoint: agent_my_agent.main:app framework: adk # Runtime feature flags controlled by agent.yaml, not .env. A key that is # present here wins over any ENABLE_* environment variable, so declaring memory # keeps ambient environment state from switching it on behind your back. # Set memory to true to enable long-term profile memory; VOYAGE_API_KEY must be # present in .env when memory is enabled. features: durable_workflow: true memory: false # Tool placement and pass-through secrets. This template's tools are all # remote-capable, so they run in the tool sandbox. sandboxes: agent: secrets: ["*"] tools: [] tool: secrets: ["*"] tools: - get_current_date - save_user_info - recall_user_info version: 0.1.0 network: egress: - fqdn: openrouter.ai ports: [443]

These settings do the following:

  • name: The name Agent Engine uses for your agent. It appears in your invoke URL and in agentengine workspace list.
  • features.memory: Turns the optional memory feature on or off. It's false because you answered no to the "Enable memory for local dev" prompt.
  • sandboxes.tool.tools: The tools the agent can call.
  • network.egress: The hosts the agent can contact. The CLI added openrouter.ai on port 443 because your model is served there.

The system_message.py file in src/agent_my_agent holds the agent's instructions:

SYSTEM_PROMPT = """ You are a daily inspiration assistant. Your name is Daily. If long-term memory is enabled, call `recall_user_info` at the start of a conversation to check what you know about the user. Address them by name and use any known details to personalize your responses. When long-term memory is enabled and the user shares personal details (name, location, interests, occupation, etc.), save each piece with `save_user_info` so you remember them in future conversations. When the user greets you or asks for inspiration, use the get_current_date tool to find out today's date, then craft a short, uplifting message of the day. Tailor the message to the season or any notable aspect of the date (e.g. start of a new month, a Friday, mid-year, etc.). Keep it warm, positive, and concise. """

The instructions are plain text that the model reads with every request. They give the agent its name, Daily, and say when to call a tool. This is why a prompt that asks for inspiration makes the agent call its get_current_date tool.

The main.py file combines the instructions, the model, and the tools into one agent:

@app.entrypoint def build_agent() -> LlmAgent: # ...  return LlmAgent( name="daily", instruction=SYSTEM_PROMPT.strip(), model=app.llm(build_llm()), tools=app.tools(), )

The build_llm() function in llm.py sets the model you chose during agentengine create and reads your OpenRouter key from LLM_API_KEY. The daily here is the agent's name inside the code, which is separate from the name in agent.yaml.

Finally, the tools.py file defines the tools. Each tool is a Python function with the @app.tool() decorator, which registers it so the model can call it. For example, the following is the get_current_date tool from the tools.py file:

def register(app: App) -> None: @app.tool() def get_current_date(timezone_name: str = "UTC") -> str: """Return today's date in ISO 8601 format for an IANA timezone.""" try: timezone = ZoneInfo(timezone_name) except ZoneInfoNotFoundError: return json.dumps( { "error": f"Unknown timezone: {timezone_name}", "hint": "Use an IANA timezone like America/Los_Angeles.", } ) return datetime.now(timezone).date().isoformat()

The model reads the function's docstring to determine when to call it. The template defines three tools:

  • get_current_date: Returns today's date for a timezone, UTC by default.
  • recall_user_info: Looks up what the agent has stored about you.
  • save_user_info: Stores a detail about you, such as your name.

Run the Agent Locally

Before you deploy your agent, run it on your machine.

First, move into the agent directory:

cd my-agent/agents/my-agent

Then run every remaining agentengine command from the my-agent/agents/my-agent directory, because the CLI looks for agent.yaml in the current directory.

Start the local stack

To start the local stack, run:

agentengine dev up

Note: Docker must be running before you run the preceding command.

The stack is ready when the output returns ✓ Stack running, followed by its services and an example request:

✓ Stack running (hot-reload) oe http://localhost:55542 mongo mongodb://localhost:55544 ui http://localhost:3000 Invoke: curl -X POST 'http://localhost:3000/api/v1/projects/<project-id>/workspaces/my-agent/invoke' \ -H 'Content-Type: application/json' \ -d '{"message": "Hello"}'

My first agentengine dev up run took several minutes because Docker had to download images and install Python dependencies. If yours takes a while, don't assume something has gone wrong. Subsequent runs reuse those dependencies and start much faster.

The first run can also stop with the following error while the app is still installing its dependencies:

Error: local app failed before becoming ready: Up About a minute (unhealthy)

If you get the error, then leave the stack running and check its progress with the following command:

agentengine dev status

Until the install finishes, the status reports fewer than 4/4 running and ends with error="status unhealthy". Don't stop or restart the stack while you wait. Run agentengine dev status again every few minutes until the output looks like this:

Stack: hot-reload app Up ... (healthy) oe Up ... (healthy) mongodb Up ... (healthy) ui Up ... 4/4 running

Once all services report a healthy status, run agentengine dev up to get your invoke URL:

... ✓ Stack running (hot-reload) oe http://localhost:55542 mongo mongodb://localhost:55542 ui http://localhost:3000 egress agent sandbox allow_list (openrouter.ai:443); tool sandbox allow_list (openrouter.ai:443) HTTP(S)_PROXY agent sandbox: http://host.docker.internal:62445; tool sandbox: http://host.docker.internal:62446 only clients that honor HTTP_PROXY are blocked; native sockets are not Invoke: my-agent 'http://localhost:3000/api/v1/projects/eff47008585047156a391d7d/workspaces/my-agent/invoke' curl -X POST 'http://localhost:3000/api/v1/projects/eff470.../workspaces/my-agent/invoke' \ -H 'Content-Type: application/json' \ -d '{"message": "Hello"}' Next: Open VS Code and run "Dev Containers: Reopen in Container" for editing and debugging inside the running app container Restart: from this workspace dir, run agentengine dev restart Logs: agentengine dev logs Stop: agentengine dev stop Clean: agentengine dev clean ############################## # # # ui http://localhost:3000 # # # ##############################

Four containers now run in Docker Desktop, under Containers, grouped as my-agent:

  • my-agent-ui: Serves the agent playground.
  • my-agent-oe-1: Runs the Orchestration Engine, which coordinates each request.
  • my-agent-app-1: Runs your agent code.
  • my-agent-mongodb-1: Stores data locally, so local development doesn't touch your Atlas cluster.

Talk to your agent in the playground

Open http://localhost:3000 in your browser, and send your agent this message:

I am starting a new job tomorrow. Can I get some inspiration for my first day?

The free model writes out its reasoning first, so expect a few paragraphs of planning before the reply.

Invoke the agent from the command line

You can also invoke the agent without using the browser. To do that, send the agent a request with curl. The request needs two values:

  • Invoke URL: Copy it from the Invoke: line of your agentengine dev up output. The URL contains your local project ID and your workspace name.

    Note: A workspace is the unit Agent Engine runs, and locally it takes your application's name, my-agent.

  • User ID: Any name you choose to identify yourself to the agent, such as Oladele.

I found that the example curl command generated by agentengine dev up omits user_id, which the Google ADK template requires. To avoid the resulting error, use the following command instead, with your own invoke URL:

curl -X POST 'http://localhost:3000/api/v1/projects/<project-id>/workspaces/my-agent/invoke' \ -H 'Content-Type: application/json' \ -d '{"message": "I am starting a new job tomorrow. Can I get some inspiration for my first day?", "user_id": "Oladele"}'

The response contains the agent's reply in its result field and reports "status": "completed".

Stop the local stack

To stop the containers, run the following command:

agentengine dev stop

Register the Project on Atlas Agent Engine

Now that you've tested your agent locally, let's prepare it for deployment to Agent Engine.

Locally, Docker supplied everything the agent needed. On Agent Engine, three things change. The agent needs a workspace to run in, its own copy of your secrets, and network access to your Atlas cluster. This section and the next two set these up in order.

To register your agent, run:

agentengine init

Choose your Atlas organization, then the Atlas project that holds your M0 cluster. The CLI registers your agent as a workspace on Agent Engine.

Upload Your Secrets to Atlas Agent Engine

The deployed agent can't access your local .env file, so you must upload the following values as Agent Engine secrets:

  • MONGODB_URI: Your Atlas connection string.
  • LLM_API_KEY: Your OpenRouter API key.
  • VOYAGE_API_KEY: Your Voyage AI API key.

Upload each one as a secret with the secret set command:

agentengine secret set MONGODB_URI agentengine secret set LLM_API_KEY agentengine secret set VOYAGE_API_KEY

Each command prompts for a value. A connection string looks like the following:

mongodb+srv://<db_username>:<db_password>@<cluster-host>/?appName=devrel-tutorial-agentengine-deploy

Replace the placeholders with your database user, its password, and your cluster host. Agent Engine stores these values as project secrets, so every workspace in your Atlas project can read them.

Each secret set command confirms the upload. For example:

✓ Project secret VOYAGE_API_KEY set version: 3 updated_at: 2026-10-14T12:11:30Z

Connect Atlas Agent Engine to Your Atlas Cluster

Before you deploy your agent, you need to configure network access between Agent Engine and your MongoDB Atlas cluster. Without the required IP access entries, Agent Engine cannot connect to your cluster, and deployment may time out after waiting up to 30 minutes.

You can configure your network access using the agentengine atlas setup command. The command's cluster list hides free M0 clusters, so you can't select yours there. It instead asks whether to keep the MONGODB_URI secret you uploaded in the previous section.

The command also adds Agent Engine's IP ranges to the access list of your Atlas project.

Run the command:

agentengine atlas setup

When prompted, enter y to keep the existing MONGODB_URI. The CLI then displays the IP address ranges that Agent Engine needs to access your cluster. Enter y again to add these ranges to your cluster's IP access list:

Keep the existing MONGODB_URI for this Agent Engine project? [Y/n] y These CIDR ranges will be added so the platform can reach this cluster: - 44.214.209.237/32 - 52.44.27.64/32 Add these CIDR ranges to Atlas IP access? [Y/n] y ... Atlas integration is ready.

The Atlas integration is ready output confirms that the network configuration is complete.

Build and Deploy the Agent

Your agent now has a workspace, its secrets, and a path to your cluster. Build and deploy it in one step:

agentengine deploy --auto

Without the --auto flag, you first run agentengine build to create the agent image, then agentengine deploy to deploy it. The --auto flag combines both steps into a single command and monitors the deployment until completion.

Deployment takes several minutes. When it finishes, each component reports its status:

✓ Build succeeded ... ✓ Deployment succeeded version: v0.1.0 components: Orchestration Engine ready (2 replicas) Agent Sandbox ready (4 replicas) Tool Sandbox ready (4 replicas) url: https://agentengine.mongodb.com/project/<project-id>/deployments/<deployment-id>

All three components reporting ready means that Agent Engine built your agent and started it. Agent Engine now runs the agent and its supporting services instead of your local Docker environment.

Invoke the Deployed Agent

Once your deployment succeeds, send your deployed agent a message:

agentengine invoke "I have a big presentation today. Can you give me some motivation?"

As in the playground, the free model writes out its reasoning before the reply.

Now test whether the deployed agent remembers. Each invocation starts a new session unless you pass --session. A session holds the history of one conversation, while the optional memory feature stores facts about a user across conversations.

Run these two commands in order, with the same session name:

agentengine invoke --session tutorial-session "My name is Oladele." agentengine invoke --session tutorial-session "What is my name?"

The output for the second command ends with the answer:

Your name is Oladele.

The second request doesn't contain your name, so the answer came from the session's history. Agent Engine stored that history in your Atlas cluster, and the deployed agent read it back.

Clean Up Your Resources

You've now deployed your agent, sent it a message, and tested its session history. If you no longer need the agent, follow these steps to remove the resources you created locally, on Agent Engine, and in Atlas.

Note: Other workspaces or applications in your Atlas project may use the project secrets, IP access entries, database user, or Voyage AI API key. Delete them only when nothing else uses them.

First, stop and remove the local stack:

agentengine dev stop agentengine dev clean

Next, find your workspace ID:

agentengine workspace list

The list shows your workspace's ID next to its name:

WORKSPACE ID NAME FRAMEWORK ws-xxxxxxxxxxxxxxxxxxxxxxxx my-agent adk

Then delete the workspace:

agentengine workspace delete <workspace-id> --yes

You stored MONGODB_URI, LLM_API_KEY, and VOYAGE_API_KEY as Agent Engine secrets. To remove them, follow the instructions in Delete a Secret.

Three resources remain in the Atlas UI:

  • The IP access entries: Go to SECURITY > Database & Network Access > IP Access List and delete your IP access entries.
  • The database user: Go to SECURITY > Database & Network Access > Database Users and delete the user you created for your connection string if you no longer need it.
  • The Voyage AI API key: Go to SERVICES > AI Model APIs > Model API Keys and delete the key if you no longer need it.

Key Takeaways

Here's what to take away from this tutorial:

  • Agent Engine is in public preview and only intended for evaluation and prototyping, with breaking changes expected.
  • agentengine create generates a project directory on your machine, and agentengine init registers it with Agent Engine.
  • A .env file serves local development only. Upload every value the deployed agent needs with agentengine secret set.
  • A deployed agent reaches your cluster from Agent Engine's network, so the cluster's IP access list must include Agent Engine's address ranges.
  • Agent Engine keeps each session's history in your Atlas cluster, so requests that share a --session value continue one conversation. ## Further Reading

For more information on Agent Engine, see the following resources: