Connecting MongoDB Atlas to Google ADK for Agent Sessions

Ananya Desai

1h200100Article

AI agents become more useful when they can maintain session information between requests.

A user might start a conversation, ask a follow-up question several minutes later, or return to the application after a longer period. If the agent cannot recover the required session state, it has to reconstruct the conversation from the beginning.

Google Agent Development Kit, commonly called Google ADK, provides tools for building and managing agent-based applications. MongoDB Atlas can be used as a persistent data store for agent session information.

This combination is useful when an application needs agent sessions to survive application restarts, work across multiple application instances, and retain structured conversation state.

The important design decision is to separate the agent's execution logic from the persistence layer. The agent handles reasoning and tasks, while MongoDB stores the information that needs to survive between requests.

What Is an Agent Session?

An agent session represents the state of an interaction between a user and an agent.

It can contain information such as:

Session ID
User ID
Current conversation
Agent state
Tool results
Workflow state
Session metadata

For example:

{
  "sessionId": "session-1001",
  "userId": "user-501",
  "state": {
    "currentTask": "order-support",
    "orderId": "ORD-1024"
  }
}

The exact information stored depends on the application.

A simple chatbot may only need conversation history, while a business workflow may need several additional fields.

Why Store Agent Sessions in MongoDB Atlas?

An application can keep session state in application memory, but that approach becomes unreliable when the application runs across multiple instances.

Consider this architecture:

User
  |
  v
Load Balancer
  |
  +----> Application Instance A
  |
  +----> Application Instance B

If the session is stored only inside Instance A, the next request may reach Instance B and lose access to that state.

MongoDB provides a shared persistence layer:

                    +-------------------+
                    | Application A     |
                    +---------+---------+
                              |
                    +---------v---------+
                    | MongoDB Atlas     |
                    | Agent Sessions    |
                    +---------^---------+
                              |
                    +---------+---------+
                    | Application B     |
                    +-------------------+

Both application instances can retrieve the same session.

This is especially useful for applications deployed in distributed environments.

How Google ADK and MongoDB Fit Together

The responsibilities can be separated into three layers:

User Request
     |
     v
Google ADK Agent
     |
     +---- Agent logic
     +---- Tools
     +---- Session handling
     |
     v
Session Persistence
     |
     v
MongoDB Atlas

Google ADK manages the agent workflow.

MongoDB Atlas provides persistent storage for session-related information.

This separation allows the application to scale its agent runtime independently from its session data.

Designing the MongoDB Session Document

MongoDB uses documents, which makes it possible to store related session information together.

A basic document might look like this:

{
  "_id": "session-1001",
  "userId": "user-501",
  "agentId": "support-agent",
  "state": {
    "currentTask": "order-support",
    "orderId": "ORD-1024"
  },
  "messages": [
    {
      "role": "user",
      "content": "Where is my order?"
    },
    {
      "role": "assistant",
      "content": "Your order is currently being shipped."
    }
  ],
  "createdAt": "2026-11-05T10:00:00Z",
  "updatedAt": "2026-11-05T10:05:00Z"
}

This structure keeps session information associated with a single session.

However, conversation history can become large. For long-running applications, it may be better to separate session metadata from message history instead of allowing one document to grow indefinitely.

Connecting to MongoDB Atlas

A Node.js application can connect to MongoDB using the MongoDB driver.

A simplified example looks like this:

import { MongoClient } from "mongodb";

const client = new MongoClient(process.env.MONGODB_URI);

await client.connect();

const db = client.db("agentdb");
const sessions = db.collection("sessions");

The connection string should be stored securely in the application's environment or secret-management system.

Do not place database credentials directly inside source code.

Creating a Session

When a new agent interaction starts, the application can create a session document.

const session = {
  _id: crypto.randomUUID(),
  userId: userId,
  agentId: "support-agent",
  state: {
    currentTask: "general-support"
  },
  messages: [],
  createdAt: new Date(),
  updatedAt: new Date()
};

await sessions.insertOne(session);

The generated session ID can then be returned to the client or associated with the authenticated user session.

The client sends the session ID with later requests.

Loading a Session

When a user sends another request, the application retrieves the session.

const session = await sessions.findOne({
  _id: sessionId,
  userId: userId
});

Checking both the session ID and user ID is important.

The application should not assume that possession of a session identifier automatically grants access to that session.

If the session does not exist, the application can create a new session or return an appropriate response.

Updating Agent State

Agent state changes as the workflow progresses.

For example:

await sessions.updateOne(
  {
    _id: sessionId,
    userId: userId
  },
  {
    $set: {
      "state.currentTask": "order-tracking",
      "state.orderId": "ORD-1024",
      updatedAt: new Date()
    }
  }
);

The application does not need to replace the entire document.

Updating only the required fields reduces unnecessary data movement.

Storing Conversation Messages

If the application needs recent conversation history, messages can be stored with the session.

For example:

await sessions.updateOne(
  {
    _id: sessionId,
    userId: userId
  },
  {
    $push: {
      messages: {
        role: "user",
        content: userMessage,
        createdAt: new Date()
      }
    },
    $set: {
      updatedAt: new Date()
    }
  }
);

The same pattern can be used for the agent response.

However, continuously appending messages to one document is not always suitable for long-running sessions.

Avoiding Oversized Session Documents

A long-running AI agent may generate hundreds or thousands of messages.

Storing all messages inside one MongoDB document can eventually create an oversized document and make every session read more expensive.

A better architecture can separate the data:

sessions
    |
    +---- Session metadata
    +---- Current agent state

session_messages
    |
    +---- Individual conversation messages

A session document might contain:

{
  "_id": "session-1001",
  "userId": "user-501",
  "agentId": "support-agent",
  "state": {
    "currentTask": "order-tracking"
  }
}

A separate message document can contain:

{
  "sessionId": "session-1001",
  "role": "user",
  "content": "Where is my order?",
  "createdAt": "2026-11-05T10:05:00Z"
}

This structure is more suitable when conversation history grows significantly.

Connecting Session IDs to Google ADK

The application should treat the session identifier as the bridge between the agent runtime and persistent storage.

The general flow is:

Request
   |
   v
Get sessionId
   |
   v
Load session from MongoDB
   |
   v
Create or restore ADK session state
   |
   v
Run agent
   |
   v
Persist updated state

The exact ADK API used for session creation and persistence depends on the ADK runtime and language integration being used.

The architectural principle remains the same: the persistent identifier should remain stable while the agent execution can occur on different application instances.

Handling Multiple Agents

A single application may contain several agents.

For example:

Support Agent
Order Agent
Billing Agent
Knowledge Agent

The session document can store the active agent or workflow state:

{
  "_id": "session-1001",
  "userId": "user-501",
  "agentId": "order-agent",
  "state": {
    "orderId": "ORD-1024",
    "status": "tracking"
  }
}

If an orchestrator changes the active agent, the state can be updated accordingly.

This allows the workflow to continue even if a different application instance handles the next request.

Handling Concurrent Requests

AI applications can receive multiple requests for the same session.

For example:

Request A → Load session
Request B → Load session
Request A → Update session
Request B → Update session

If both requests modify the same fields, one update can overwrite another.

This is a common concurrency problem.

Use targeted MongoDB updates where possible instead of replacing the complete session document.

For workflows that require strict sequencing, the application may also need request coordination or optimistic concurrency controls.

The important point is to design session updates assuming that concurrent requests can occur.

Indexing Agent Sessions

Session lookup is usually performed using a session identifier.

A user-based lookup may also be required.

For example:

await sessions.createIndex({
  userId: 1,
  updatedAt: -1
});

This can support queries such as retrieving a user's recent sessions.

For message storage, an index such as the following can support session history queries:

await messages.createIndex({
  sessionId: 1,
  createdAt: 1
});

Indexes should reflect the actual access patterns of the application.

Do not create indexes simply because a field exists in the document.

Session Expiration and Cleanup

Not every agent session needs to remain active forever.

Applications should define a retention strategy.

For temporary sessions, old records can be removed after a defined period.

For example, an application might classify sessions as:

Active
Inactive
Archived
Expired

The appropriate retention period depends on the application's business and compliance requirements.

If conversation history must be retained, archive it separately instead of treating every active session as permanent.

Protecting Agent Session Data

Agent sessions can contain sensitive information.

The application should:

Restrict database access
Use secure credentials
Validate user ownership of sessions
Avoid exposing database connection details
Limit the information sent to the AI model
Apply appropriate data retention policies
Protect session identifiers

A session ID should not be treated as a complete authorization mechanism.

The application should still verify that the authenticated user is allowed to access the requested session.

Common Mistakes

Keeping Sessions Only in Application Memory

This fails when requests move between application instances or when the process restarts.

Use persistent shared storage for sessions that need to survive these events.

Storing the Entire Conversation in Every Request

Reading and sending a huge conversation history can increase application and model processing costs.

Retrieve only the context required for the current task.

Allowing Session Documents to Grow Forever

Long conversations can make session documents unnecessarily large.

Separate message history from session state when appropriate.

Replacing the Entire Session Document

Replacing the whole document for every small state change increases the chance of overwriting concurrent updates.

Use targeted updates for individual fields.

Using Session IDs Without Authorization Checks

A session identifier should not be the only protection around user data.

Always validate ownership or access permissions.

Best Practices

Generate a stable identifier for each agent session.
Keep session metadata separate from large conversation histories when necessary.
Store only the context required to continue the agent workflow.
Use targeted MongoDB updates for frequently changing state.
Add indexes based on actual session access patterns.
Handle concurrent requests explicitly.
Define retention and cleanup rules for inactive sessions.
Verify user access before loading session data.
Keep database credentials outside application source code.
Avoid sending unnecessary historical context to the AI model.
Monitor session size and database performance as usage grows.
Keep the persistence layer independent from agent business logic.

Advantages and Disadvantages

Area	Advantages	Disadvantages
Persistence	Sessions survive application restarts	Requires database management
Scalability	Multiple application instances can share sessions	Concurrent updates need careful handling
Flexibility	MongoDB documents can represent different agent states	Poor document design can create large records
Session history	Conversation data can be stored alongside metadata	Long histories require a separate storage strategy
Reliability	Centralized session storage provides consistent state	Database availability becomes part of the application dependency chain
Development	Easy to model structured agent state	Schema changes need versioning and migration planning

Troubleshooting Common Session Problems

If the agent forgets previous information, first verify that the same session ID is being used across requests.

If the session exists but the agent still loses state, check whether the application is loading the MongoDB document before starting the agent execution.

If information disappears after another request, investigate concurrent updates and document replacement operations.

If session queries become slower over time, examine document size, indexes, and message-history storage.

If different users appear to share context, verify that session identifiers are unique and that every session lookup includes the correct user or authorization boundary.

Summary

MongoDB Atlas can provide persistent storage for agent sessions built with Google ADK.

The main advantage is that agent state no longer depends on a single application process. Multiple application instances can retrieve the same session and continue an existing workflow.

A production-ready design should separate session state from large conversation histories when necessary, use stable session identifiers, create indexes based on real access patterns, handle concurrent updates, and enforce authorization when loading sessions.

The most useful approach is to store only the context required to continue the agent's work. Persistent storage should support the agent rather than become an unstructured copy of every interaction.

Google ADKAI agentsMongoDB Atlasagent sessionssession persistenceNode.js

Comments

Join the conversation! Your thoughts help the community grow.

Connecting MongoDB Atlas to Google ADK for Agent Sessions

Ananya Desai

1h200100Article

AI agents become more useful when they can maintain session information between requests.

This combination is useful when an application needs agent sessions to survive application restarts, work across multiple application instances, and retain structured conversation state.

What Is an Agent Session?

An agent session represents the state of an interaction between a user and an agent.

It can contain information such as:

Session ID
User ID
Current conversation
Agent state
Tool results
Workflow state
Session metadata

For example:

{
  "sessionId": "session-1001",
  "userId": "user-501",
  "state": {
    "currentTask": "order-support",
    "orderId": "ORD-1024"
  }
}

The exact information stored depends on the application.

A simple chatbot may only need conversation history, while a business workflow may need several additional fields.

Why Store Agent Sessions in MongoDB Atlas?

An application can keep session state in application memory, but that approach becomes unreliable when the application runs across multiple instances.

Consider this architecture:

User
  |
  v
Load Balancer
  |
  +----> Application Instance A
  |
  +----> Application Instance B

If the session is stored only inside Instance A, the next request may reach Instance B and lose access to that state.

MongoDB provides a shared persistence layer:

                    +-------------------+
                    | Application A     |
                    +---------+---------+
                              |
                    +---------v---------+
                    | MongoDB Atlas     |
                    | Agent Sessions    |
                    +---------^---------+
                              |
                    +---------+---------+
                    | Application B     |
                    +-------------------+

Both application instances can retrieve the same session.

This is especially useful for applications deployed in distributed environments.

How Google ADK and MongoDB Fit Together

The responsibilities can be separated into three layers:

User Request
     |
     v
Google ADK Agent
     |
     +---- Agent logic
     +---- Tools
     +---- Session handling
     |
     v
Session Persistence
     |
     v
MongoDB Atlas

Google ADK manages the agent workflow.

MongoDB Atlas provides persistent storage for session-related information.

This separation allows the application to scale its agent runtime independently from its session data.

Designing the MongoDB Session Document

MongoDB uses documents, which makes it possible to store related session information together.

A basic document might look like this:

{
  "_id": "session-1001",
  "userId": "user-501",
  "agentId": "support-agent",
  "state": {
    "currentTask": "order-support",
    "orderId": "ORD-1024"
  },
  "messages": [
    {
      "role": "user",
      "content": "Where is my order?"
    },
    {
      "role": "assistant",
      "content": "Your order is currently being shipped."
    }
  ],
  "createdAt": "2026-11-05T10:00:00Z",
  "updatedAt": "2026-11-05T10:05:00Z"
}

This structure keeps session information associated with a single session.

Connecting to MongoDB Atlas

A Node.js application can connect to MongoDB using the MongoDB driver.

A simplified example looks like this:

import { MongoClient } from "mongodb";

const client = new MongoClient(process.env.MONGODB_URI);

await client.connect();

const db = client.db("agentdb");
const sessions = db.collection("sessions");

The connection string should be stored securely in the application's environment or secret-management system.

Do not place database credentials directly inside source code.

Creating a Session

When a new agent interaction starts, the application can create a session document.

const session = {
  _id: crypto.randomUUID(),
  userId: userId,
  agentId: "support-agent",
  state: {
    currentTask: "general-support"
  },
  messages: [],
  createdAt: new Date(),
  updatedAt: new Date()
};

await sessions.insertOne(session);

The generated session ID can then be returned to the client or associated with the authenticated user session.

The client sends the session ID with later requests.

Loading a Session

When a user sends another request, the application retrieves the session.

const session = await sessions.findOne({
  _id: sessionId,
  userId: userId
});

Checking both the session ID and user ID is important.

The application should not assume that possession of a session identifier automatically grants access to that session.

If the session does not exist, the application can create a new session or return an appropriate response.

Updating Agent State

Agent state changes as the workflow progresses.

For example:

await sessions.updateOne(
  {
    _id: sessionId,
    userId: userId
  },
  {
    $set: {
      "state.currentTask": "order-tracking",
      "state.orderId": "ORD-1024",
      updatedAt: new Date()
    }
  }
);

The application does not need to replace the entire document.

Updating only the required fields reduces unnecessary data movement.

Storing Conversation Messages

If the application needs recent conversation history, messages can be stored with the session.

For example:

await sessions.updateOne(
  {
    _id: sessionId,
    userId: userId
  },
  {
    $push: {
      messages: {
        role: "user",
        content: userMessage,
        createdAt: new Date()
      }
    },
    $set: {
      updatedAt: new Date()
    }
  }
);

The same pattern can be used for the agent response.

However, continuously appending messages to one document is not always suitable for long-running sessions.

Avoiding Oversized Session Documents

A long-running AI agent may generate hundreds or thousands of messages.

Storing all messages inside one MongoDB document can eventually create an oversized document and make every session read more expensive.

A better architecture can separate the data:

sessions
    |
    +---- Session metadata
    +---- Current agent state

session_messages
    |
    +---- Individual conversation messages

A session document might contain:

{
  "_id": "session-1001",
  "userId": "user-501",
  "agentId": "support-agent",
  "state": {
    "currentTask": "order-tracking"
  }
}

A separate message document can contain:

{
  "sessionId": "session-1001",
  "role": "user",
  "content": "Where is my order?",
  "createdAt": "2026-11-05T10:05:00Z"
}

This structure is more suitable when conversation history grows significantly.

Connecting Session IDs to Google ADK

The application should treat the session identifier as the bridge between the agent runtime and persistent storage.

The general flow is:

Request
   |
   v
Get sessionId
   |
   v
Load session from MongoDB
   |
   v
Create or restore ADK session state
   |
   v
Run agent
   |
   v
Persist updated state

The exact ADK API used for session creation and persistence depends on the ADK runtime and language integration being used.

The architectural principle remains the same: the persistent identifier should remain stable while the agent execution can occur on different application instances.

Handling Multiple Agents

A single application may contain several agents.

For example:

Support Agent
Order Agent
Billing Agent
Knowledge Agent

The session document can store the active agent or workflow state:

{
  "_id": "session-1001",
  "userId": "user-501",
  "agentId": "order-agent",
  "state": {
    "orderId": "ORD-1024",
    "status": "tracking"
  }
}

If an orchestrator changes the active agent, the state can be updated accordingly.

This allows the workflow to continue even if a different application instance handles the next request.

Handling Concurrent Requests

AI applications can receive multiple requests for the same session.

For example:

Request A → Load session
Request B → Load session
Request A → Update session
Request B → Update session

If both requests modify the same fields, one update can overwrite another.

This is a common concurrency problem.

Use targeted MongoDB updates where possible instead of replacing the complete session document.

For workflows that require strict sequencing, the application may also need request coordination or optimistic concurrency controls.

The important point is to design session updates assuming that concurrent requests can occur.

Indexing Agent Sessions

Session lookup is usually performed using a session identifier.

A user-based lookup may also be required.

For example:

await sessions.createIndex({
  userId: 1,
  updatedAt: -1
});

This can support queries such as retrieving a user's recent sessions.

For message storage, an index such as the following can support session history queries:

await messages.createIndex({
  sessionId: 1,
  createdAt: 1
});

Indexes should reflect the actual access patterns of the application.

Do not create indexes simply because a field exists in the document.

Session Expiration and Cleanup

Not every agent session needs to remain active forever.

Applications should define a retention strategy.

For temporary sessions, old records can be removed after a defined period.

For example, an application might classify sessions as:

Active
Inactive
Archived
Expired

The appropriate retention period depends on the application's business and compliance requirements.

If conversation history must be retained, archive it separately instead of treating every active session as permanent.

Protecting Agent Session Data

Agent sessions can contain sensitive information.

The application should:

Restrict database access
Use secure credentials
Validate user ownership of sessions
Avoid exposing database connection details
Limit the information sent to the AI model
Apply appropriate data retention policies
Protect session identifiers

A session ID should not be treated as a complete authorization mechanism.

The application should still verify that the authenticated user is allowed to access the requested session.

Common Mistakes

Keeping Sessions Only in Application Memory

This fails when requests move between application instances or when the process restarts.

Use persistent shared storage for sessions that need to survive these events.

Storing the Entire Conversation in Every Request

Reading and sending a huge conversation history can increase application and model processing costs.

Retrieve only the context required for the current task.

Allowing Session Documents to Grow Forever

Long conversations can make session documents unnecessarily large.

Separate message history from session state when appropriate.

Replacing the Entire Session Document

Replacing the whole document for every small state change increases the chance of overwriting concurrent updates.

Use targeted updates for individual fields.

Using Session IDs Without Authorization Checks

A session identifier should not be the only protection around user data.

Always validate ownership or access permissions.

Best Practices

Generate a stable identifier for each agent session.
Keep session metadata separate from large conversation histories when necessary.
Store only the context required to continue the agent workflow.
Use targeted MongoDB updates for frequently changing state.
Add indexes based on actual session access patterns.
Handle concurrent requests explicitly.
Define retention and cleanup rules for inactive sessions.
Verify user access before loading session data.
Keep database credentials outside application source code.
Avoid sending unnecessary historical context to the AI model.
Monitor session size and database performance as usage grows.
Keep the persistence layer independent from agent business logic.

Advantages and Disadvantages

Area	Advantages	Disadvantages
Persistence	Sessions survive application restarts	Requires database management
Scalability	Multiple application instances can share sessions	Concurrent updates need careful handling
Flexibility	MongoDB documents can represent different agent states	Poor document design can create large records
Session history	Conversation data can be stored alongside metadata	Long histories require a separate storage strategy
Reliability	Centralized session storage provides consistent state	Database availability becomes part of the application dependency chain
Development	Easy to model structured agent state	Schema changes need versioning and migration planning

Troubleshooting Common Session Problems

If the agent forgets previous information, first verify that the same session ID is being used across requests.

If the session exists but the agent still loses state, check whether the application is loading the MongoDB document before starting the agent execution.

If information disappears after another request, investigate concurrent updates and document replacement operations.

If session queries become slower over time, examine document size, indexes, and message-history storage.

If different users appear to share context, verify that session identifiers are unique and that every session lookup includes the correct user or authorization boundary.

Summary

MongoDB Atlas can provide persistent storage for agent sessions built with Google ADK.

The main advantage is that agent state no longer depends on a single application process. Multiple application instances can retrieve the same session and continue an existing workflow.

The most useful approach is to store only the context required to continue the agent's work. Persistent storage should support the agent rather than become an unstructured copy of every interaction.

Google ADKAI agentsMongoDB Atlasagent sessionssession persistenceNode.js

Comments

Join the conversation! Your thoughts help the community grow.