Join us Sept 17 at .local NYC! Use code WEB50 to save 50% on tickets. Learn more >
MongoDB Jokes
Docs Menu
Docs Home
/
Atlas
/ / /

Build an AI Agent with LangGraph.js and MongoDB Atlas

You can integrate MongoDB Atlas with LangGraph.js to build AI agents. This tutorial demonstrates how to build an agent with LangGraph.js and MongoDB Vector Search that can answer questions about your data.

Specifically, you perform the following actions:

  1. Set up the environment.

  2. Configure your MongoDB cluster.

  3. Build the agent, including the agent tools.

  4. Add memory to the agent.

  5. Create a server and test the agent.

Work with the code for this tutorial by cloning the GitHub repository.

Before you begin, ensure that you have the following:

  • One of the following MongoDB cluster types:

    • An Atlas cluster running MongoDB version 6.0.11, 7.0.2, or later. Ensure that your IP address is included in your Atlas project's access list.

    • A local Atlas deployment created using the Atlas CLI. To learn more, see Create a Local Atlas Deployment.

    • A MongoDB Community or Enterprise cluster with Search and Vector Search installed.

  • npm and Node.js installed.

  • A Voyage AI API Key. To create an account and API Key, see the Voyage AI website.

  • An OpenAI API Key. You must have an OpenAI account with credits available for API requests. To learn more about registering an OpenAI account, see the OpenAI API website.

Note

This tutorial uses models from OpenAI and Voyage AI, but you can modify the code to use your models of choice.

To set up the environment, complete the following steps:

1

Create a new project directory, then run the following commands in the project to install the required dependencies:

npm init -y
npm i -D typescript ts-node @types/express @types/node
npx tsc --init
npm i langchain @langchain/langgraph @langchain/mongodb @langchain/community @langchain/langgraph-checkpoint-mongodb dotenv express mongodb zod

Note

Your project uses the following structure:

├── .env
├── index.ts
├── agent.ts
├── seed-database.ts
├── package.json
├── tsconfig.json
2

Create a .env file in your project root and add your API keys and connection string:

OPENAI_API_KEY = "<openai-api-key>"
MONGODB_URI = "<connection-string>"
VOYAGEAI_API_KEY = "<voyage-api-key>"

Replace <connection-string> with the connection string for your Atlas cluster or local Atlas deployment.

Your connection string should use the following format:

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

To learn more, see Connect to a Cluster via Drivers.

Your connection string should use the following format:

mongodb://localhost:<port-number>/?directConnection=true

To learn more, see Connection Strings.

You can follow along with this tutorial by watching the video.

Duration: 30 Minutes

In this section, you configure and ingest sample data into your MongoDB cluster to enable vector search over your data.

1

Create an index.ts file that establishes a connection to your MongoDB cluster:

import { MongoClient } from "mongodb";
import 'dotenv/config';
const client = new MongoClient(process.env.MONGODB_URI as string);
async function startServer() {
try {
await client.connect();
await client.db("admin").command({ ping: 1 });
console.log("Pinged your deployment. You successfully connected to MongoDB!");
// ... rest of the server setup
} catch (error) {
console.error("Error connecting to MongoDB:", error);
process.exit(1);
}
}
startServer();
2

Create a seed-database.ts script to generate and store sample employee records. This script performs the following actions:

  • Defines a schema for employee records.

  • Creates a function to generate sample employee data using the LLM.

  • Processes each record to create a text summary to use for embeddings.

  • Uses the LangChain MongoDB integration to initialize your MongoDB cluster as a vector store. This component generates vector embeddings and stores the documents in your hr_database.employees namespace.

3
npx ts-node seed-database.ts
Pinged your deployment. You successfully connected to MongoDB!
Generating synthetic data...
Successfully added database record: {
acknowledged: true,
insertedId: new ObjectId('685d89d966545cfb242790f0')
}
Successfully added database record: {
acknowledged: true,
insertedId: new ObjectId('685d89d966545cfb242790f1')
}
Successfully added database record: {
acknowledged: true,
insertedId: new ObjectId('685d89da66545cfb242790f2')
}
Successfully added database record: {
acknowledged: true,
insertedId: new ObjectId('685d89da66545cfb242790f3')
}

Tip

After running the script, you can view the seeded data in your MongoDB cluster by navigating to the hr_database.employees namespace in the Atlas UI.

4

Follow the steps to create a MongoDB Vector Search index for the hr_database.employees namespace. Name the index vector_index and specify the following index definition:

{
"fields": [
{
"numDimensions": 1024,
"path": "embedding",
"similarity": "cosine",
"type": "vector"
}
]
}

In this section, you build a graph to orchestrate the agent's workflow. The graph defines the sequence of steps that the agent takes to respond to a query.

1

Create a new file named agent.ts in your project, then add the following code to begin setting up the agent. You will add more code to the asynchronous function in the subsequent steps.

import { ChatOpenAI } from "@langchain/openai";
import { AIMessage, BaseMessage, HumanMessage } from "@langchain/core/messages";
import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
import { StateGraph } from "@langchain/langgraph";
import { Annotation } from "@langchain/langgraph";
import { tool } from "@langchain/core/tools";
import { ToolNode } from "@langchain/langgraph/prebuilt";
import { MongoDBSaver } from "@langchain/langgraph-checkpoint-mongodb";
import { MongoDBAtlasVectorSearch } from "@langchain/mongodb";
import { MongoClient } from "mongodb";
import { z } from "zod";
import "dotenv/config";
export async function callAgent(client: MongoClient, query: string, thread_id: string) {
// Define the MongoDB database and collection
const dbName = "hr_database";
const db = client.db(dbName);
const collection = db.collection("employees");
// ... (Add rest of code here)
}
2

Add the following code to the file to define the graph state:

const GraphState = Annotation.Root({
messages: Annotation<BaseMessage[]>({
reducer: (x, y) => x.concat(y),
}),
});

The state defines the data structure that flows through your agent workflow. Here, the state tracks conversation messages, with a reducer that concatenates new messages to the existing conversation history.

3

Add the following code to define a tool and tool node that uses MongoDB Vector Search to retrieve relevant employee information by querying the vector store:

const executeQuery = async (embedding:[], n: number) => {
try {
const client = new MongoClient(process.env.MONGODB_URI as string);
const database = client.db("hr_database");
const coll = database.collection("employees");
const agg = [
{
'$vectorSearch': {
'index': 'vector_index',
'path': 'embedding',
'queryVector': embedding,
'numCandidates': 150,
'limit': n
}
}, {
'$project': {
'_id': 0,
'pageContent': 1,
'score': {
'$meta': 'vectorSearchScore'
}
}
}
];
const result = await coll.aggregate(agg).toArray();
return result
} catch(error) {
console.log("Error while querying:", error)
}
}
const fetchEmbeddings = async (query: string) => {
const apiUrl = "https://api.voyageai.com/v1/embeddings";
const apiKey = process.env.VOYAGEAI_API_KEY;
const requestBody = {
input: query,
model: "voyage-3.5",
};
try {
const response = await fetch(apiUrl, {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify(requestBody),
});
if (!response.ok) {
throw new Error(`Error: ${response.status} ${response.statusText}`);
}
const data = await response.json();
return data.data[0].embedding;
} catch (error) {
console.error("Error while fetching embedding:", error);
}
};
const employeeLookupTool = tool(
async ({ query, n = 10 }) => {
console.log("Employee lookup tool called");
const embedding = await fetchEmbeddings(query)
const response = await executeQuery(embedding, n)
const result = JSON.stringify(response)
return result;
},
{
name: "employee_lookup",
description: "Gathers employee details from the HR database",
schema: z.object({
query: z.string().describe("The search query"),
n: z.number().optional().default(10).describe("Number of results to return"),
}),
}
);
const tools = [employeeLookupTool];
const toolNode = new ToolNode<typeof GraphState.State>(tools);
4

Add the following code to the file to determine which model to use for the agent. This example uses a model from OpenAI, but you can modify it to use your preferred model:

const model = new ChatOpenAI({
model: "gpt-4o"
}).bindTools(tools);
5

Add the following code to define the functions that the agent uses to process messages and determine whether to continue the conversation:

  1. This function configures how the agent uses the LLM:

    • Constructs a prompt template with system instructions and conversation history.

    • Formats the prompt with the current time, available tools, and messages.

    • Invokes the LLM to generate the next response.

    • Returns the model's response to be added to the conversation state.

    async function callModel(state: typeof GraphState.State) {
    const prompt = ChatPromptTemplate.fromMessages([
    [
    "system",
    `You are a helpful AI assistant, collaborating with other assistants. Use the provided tools to progress towards answering the question. If you are unable to fully answer, that's OK, another assistant with different tools will help where you left off. Execute what you can to make progress. If you or any of the other assistants have the final answer or deliverable, prefix your response with FINAL ANSWER so the team knows to stop. You have access to the following tools: {tool_names}.\n{system_message}\nCurrent time: {time}.`,
    ],
    new MessagesPlaceholder("messages"),
    ]);
    const formattedPrompt = await prompt.formatMessages({
    system_message: "You are helpful HR Chatbot Agent.",
    time: new Date().toISOString(),
    tool_names: tools.map((tool) => tool.name).join(", "),
    messages: state.messages,
    });
    const result = await model.invoke(formattedPrompt);
    return { messages: [result] };
    }
  2. This function determines whether the agent should continue or end the conversation:

    • If the message contains tool calls, route the flow to the tools node.

    • Otherwise, end the conversation and return the final response.

    function shouldContinue(state: typeof GraphState.State) {
    const messages = state.messages;
    const lastMessage = messages[messages.length - 1] as AIMessage;
    if (lastMessage.tool_calls?.length) {
    return "tools";
    }
    return "__end__";
    }
6

Add the following code to define the sequence of steps that the agent takes to respond to a query.

const workflow = new StateGraph(GraphState)
.addNode("agent", callModel)
.addNode("tools", toolNode)
.addEdge("__start__", "agent")
.addConditionalEdges("agent", shouldContinue)
.addEdge("tools", "agent");

Specifically, the agent performs the following steps:

  1. The agent receives a user query.

  2. In the agent node, the agent processes the query and determines whether to use a tool or to end the conversation.

  3. If a tool is needed, the agent routes to the tools node, where it executes the selected tool. The result from the tool are sent back to the agent node.

  4. The agent interprets the tool's output and forms a response or decides on the next action.

  5. This continues until the agent determines that no further action is needed (shouldContinue function returns end).

Diagram that shows the workflow of the LangGraph-MongoDB agent.
click to enlarge

To improve the agent's performance, you can persist its state by using the MongoDB Checkpointer. Persistence allows the agent to store information about previous interactions, which the agent can use in future interactions to provide more contextually relevant responses.

1

Add the following code to your agent.ts file to set up a persistence layer for your agent's state:

const checkpointer = new MongoDBSaver({ client, dbName });
const app = workflow.compile({ checkpointer });
2

Finally, add the following code to complete the agent function to handle queries:

const finalState = await app.invoke(
{
messages: [new HumanMessage(query)],
},
{ recursionLimit: 15, configurable: { thread_id: thread_id } }
);
console.log(finalState.messages[finalState.messages.length - 1].content);
return finalState.messages[finalState.messages.length - 1].content;

In this section, you create a server to interact with your agent and test its functionality.

1

Replace your index.ts file with the following code:

import 'dotenv/config';
import express, { Express, Request, Response } from "express";
import { MongoClient } from "mongodb";
import { callAgent } from './agent';
const app: Express = express();
app.use(express.json());
const client = new MongoClient(process.env.MONGODB_URI as string);
async function startServer() {
try {
await client.connect();
await client.db("admin").command({ ping: 1 });
console.log("Pinged your deployment. You successfully connected to MongoDB!");
app.get('/', (req: Request, res: Response) => {
res.send('LangGraph Agent Server');
});
app.post('/chat', async (req: Request, res: Response) => {
const initialMessage = req.body.message;
const threadId = Date.now().toString();
try {
const response = await callAgent(client, initialMessage, threadId);
res.json({ threadId, response });
} catch (error) {
console.error('Error starting conversation:', error);
res.status(500).json({ error: 'Internal server error' });
}
});
app.post('/chat/:threadId', async (req: Request, res: Response) => {
const { threadId } = req.params;
const { message } = req.body;
try {
const response = await callAgent(client, message, threadId);
res.json({ response });
} catch (error) {
console.error('Error in chat:', error);
res.status(500).json({ error: 'Internal server error' });
}
});
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`Server running on port ${PORT}`);
});
} catch (error) {
console.error('Error connecting to MongoDB:', error);
process.exit(1);
}
}
startServer();
2

Run the following command to start your server:

npx ts-node index.ts
3

Send sample requests to interact with your agent. Your responses vary depending on your data and the models you use.

Note

The request returns a response in JSON format. You can also view the plaintext output in your terminal where the server is running.

curl -X POST -H "Content-Type: application/json" -d '{"message": "Build a team to make a web app based on the employee data."}' http://localhost:3000/chat
# Sample response
{"threadId": "1713589087654", "response": "To assemble a web app development team, we ideally need..." (truncated)}
# Plaintext output in the terminal
To assemble a web app development team, we ideally need the following roles:
1. **Software Developer**: To handle the coding and backend.
2. **UI/UX Designer**: To design the application's interface and user experience.
3. **Data Analyst**: For managing, analyzing, and visualizing data if required for the app.
4. **Project Manager**: To coordinate the project tasks and milestones, often providing communication across departments.
### Suitable Team Members for the Project:
#### 1. Software Developer
- **John Doe**
- **Role**: Software Engineer
- **Skills**: Java, Python, AWS
- **Location**: Los Angeles HQ (Remote)
- **Notes**: Highly skilled developer with exceptional reviews (4.8/5), promoted to Senior Engineer in 2018.
#### 2. Data Analyst
- **David Smith**
- **Role**: Data Analyst
- **Skills**: SQL, Tableau, Data Visualization
- **Location**: Denver Office
- **Notes**: Strong technical analysis skills. Can assist with app data integration or dashboards.
#### 3. UI/UX Designer
No specific UI/UX designer was identified in the current search. I will need to query this again or look for a graphic designer with some UI/UX skills.
#### 4. Project Manager
- **Emily Davis**
- **Role**: HR Manager
- **Skills**: Employee Relations, Recruitment, Conflict Resolution
- **Location**: Seattle HQ (Remote)
- **Notes**: Experienced in leadership. Can take on project coordination.
Should I search further for a UI/UX designer, or do you have any other parameters for the team?

You can continue the conversation by using the thread ID returned in your previous response. For example, to ask a follow-up question, use the following command. Replace <threadId> with the thread ID returned in the previous response.

curl -X POST -H "Content-Type: application/json" -d '{"message": "Who should lead this project?"}' http://localhost:3000/chat/<threadId>
# Sample response
{"response": "For leading this project, a suitable choice would be someone..." (truncated)}
# Plaintext output in the terminal
### Best Candidate for Leadership:
- **Emily Davis**:
- **Role**: HR Manager
- **Skills**: Employee Relations, Recruitment, Conflict Resolution
- **Experience**:
- Demonstrated leadership in complex situations, as evidenced by strong performance reviews (4.7/5).
- Mentored junior associates, indicating capability in guiding a team.
- **Advantages**:
- Remote-friendly, enabling flexible communication across team locations.
- Experience in managing people and processes, which would be crucial for coordinating a diverse team.
**Recommendation:** Emily Davis is the best candidate to lead the project given her proven leadership skills and ability to manage collaboration effectively.
Let me know if you'd like me to prepare a structured proposal or explore alternative options.

Back

LangGraph.js

Earn a Skill Badge

Master "Gen AI" for free!

Learn more

On this page