For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.

Integrate MongoDB with Fireworks AI

You can integrate MongoDB with Fireworks AI, an inference and training platform for open-source models. This guide shows how to use Fireworks chat models alongside MongoDB, which allows you to provide context for agent responses and configure your agent's data store.

The MongoDB integration for Fireworks AI provides the following features:

  • Chat model data: Pass MongoDB data to a chat model as context, or expose it to a tool that the model calls.

  • Agent memory: Persist agent conversation history and session state as documents.

  • Training data source: Use MongoDB data to fine-tune a Fireworks model and customize its behavior for your use cases.

You can call Fireworks chat models by using the Fireworks SDK or compatible APIs, such as the OpenAI API. Frameworks that support OpenAI-compatible providers, including LangChain, LangGraph, and LlamaIndex, also work with Fireworks.

Get Started

To complete a tutorial that uses Fireworks models with MongoDB Vector Search to build a RAG application, see Get Started with the MongoDB Fireworks AI Integration.

Installation

To install the required packages, run the following command:

pip install --quiet --upgrade pymongo openai

This command installs the following packages:

  • pymongo: The MongoDB Python driver

  • openai: An OpenAI client, which the examples on this page use to call Fireworks chat models

LangChain Packages

If you build with LangChain, use the langchain-fireworks package's ChatFireworks class to call Fireworks chat models. Run the following command to install this package:

pip install --quiet --upgrade langchain-fireworks

Usage

To use Fireworks chat models with MongoDB, create the following clients:

  • A client, such as an OpenAI client, configured to use the Fireworks endpoint

  • A MongoDB client for your deployment

The following example creates both of these clients and selects a Fireworks chat model:

FIREWORKS_BASE_URL = "https://api.fireworks.ai/inference/v1"fireworks = OpenAI(    base_url=FIREWORKS_BASE_URL,    api_key=os.environ["FIREWORKS_API_KEY"],)
mongo_client = MongoClient(os.environ["MONGODB_URI"])collection = mongo_client["<database-name>"]["<collection-name>"]
CHAT_MODEL = "accounts/fireworks/models/gpt-oss-120b"

To use this example, set the following environment variables:

Interact with a Chat Model

To send a conversation to a Fireworks model and receive a response, call the chat.completions.create() method on the Fireworks client. This section shows how to customize your chat model interactions in the following ways:

Use MongoDB Data as Context

To generate an answer based on context that you provide, set the messages parameter to a list containing the following messages:

  • system message that instructs the model to answer only from the provided context

  • user message that contains the context and the question

You can pass any MongoDB query result as the context in your user message to generate a response from your MongoDB data.

The following example queries a MongoDB collection for a small set of candidate documents. Then, the code provides their titles and plots as context to generate a movie recommendation:

question = "Recommend a movie about a heist that goes wrong."movies = collection.find(    {"plot": {"$regex": r"\bheist\b", "$options": "i"}}, {"_id": 0, "title": 1, "plot": 1}).limit(5)context = "\n".join(f'{m["title"]}: {m["plot"]}' for m in movies)
response = fireworks.chat.completions.create(    model=CHAT_MODEL,    messages=[        {            "role": "system",            "content": "Answer using only the movies in the context. "            "If the context doesn't contain the answer, say so.",        },        {            "role": "user",            "content": f"Context:\n{context}\n\nQuestion: {question}",        },    ],)
print(response.choices[0].message.content)

Specify Agent Tools

To specify a list of tools that supported Fireworks chat models can call, use the tools parameter. Set this parameter to a list of function definitions, each containing a function's name, description, and parameters.

When the model decides to call a function, it returns a tool_calls list on the response message instead of a text answer. Your code runs the named function and sends the result back as a tool message to continue the conversation. Use this pattern to build an agent that decides when to call a tool, such as a function that queries your MongoDB collection.

This example performs the following actions:

  • Defines a search_movies tool that queries MongoDB

  • Allows the model to decide whether to call the tool

  • Runs the search_movies tool and sends the result back to the model, if the model requests it

  • Generates a final recommendation

AGENT_MODEL = "accounts/fireworks/models/kimi-k3"
TOOLS = [    {        "type": "function",        "function": {            "name": "search_movies",            "description": "Keyword search over movie plots in the MongoDB movie catalog.",            "parameters": {                "type": "object",                "properties": {                    "keyword": {                        "type": "string",                        "description": "A single keyword to search for in movie plots.",                    }                },                "required": ["keyword"],            },        },    }]

def search_movies(keyword):    results = collection.find(        {"plot": {"$regex": rf"\b{keyword}\b", "$options": "i"}}, {"_id": 0, "title": 1, "plot": 1}    ).limit(5)    return [f'{m["title"]}: {m["plot"]}' for m in results]

messages = [    {        "role": "system",        "content": "Call search_movies before you recommend a movie.",    },    {        "role": "user",        "content": "Recommend a movie about a heist that goes wrong.",    },]
response = fireworks.chat.completions.create(    model=AGENT_MODEL,    messages=messages,    tools=TOOLS,)message = response.choices[0].messagemessages.append(message.model_dump(exclude_none=True))
for call in message.tool_calls:    args = json.loads(call.function.arguments)    results = search_movies(**args)    messages.append(        {            "role": "tool",            "tool_call_id": call.id,            "content": json.dumps(results),        }    )
response = fireworks.chat.completions.create(model=AGENT_MODEL, messages=messages)print(response.choices[0].message.content)

Persist Agent Memory

To configure an agent that remembers earlier conversation turns, store each message in a MongoDB collection. Then, load the message history into the messages list whenever you call the chat.completions.create() method. Store a session_id value in each message document to assign the stored history to a single conversation.

This example performs the following actions:

  • Loads any existing message history for the session from the chat_history collection

  • Appends a new user message and calls chat.completions.create() with the combined history

  • Saves the new user message and the model's response back to the chat_history collection

history = mongo_client["<database-name>"]["chat_history"]

def load_history(session_id):    return [        doc["message"]        for doc in history.find({"session_id": session_id}).sort("seq", 1)    ]

def save_messages(session_id, messages, start_seq):    history.insert_many(        {"session_id": session_id, "seq": start_seq + i, "message": message}        for i, message in enumerate(messages)    )

session_id = "demo-session"past_messages = load_history(session_id)new_messages = [{"role": "user", "content": "Recommend a movie about a heist that goes wrong."}]
response = fireworks.chat.completions.create(    model=AGENT_MODEL,    messages=past_messages + new_messages,)new_messages.append(response.choices[0].message.model_dump(exclude_none=True))
save_messages(session_id, new_messages, start_seq=len(past_messages))print(response.choices[0].message.content)

Because the agent loads past messages from the chat_history collection on every call, a future call that uses the same session_id value can refer back to this conversation.

Train Models on MongoDB Data

You can train an existing open-source chat model on data stored in MongoDB to customize its behavior for specific use cases and improve its accuracy.

To use MongoDB data for model training, your documents must store a messages array in the chat format that Fireworks expects. Export these documents from your collection to a JSONL file, where each line is one document's messages array. Then, upload the dataset and use firectl, the Fireworks CLI, to start supervised fine-tuning.

Run the following commands to upload a dataset and retrain a model:

firectl dataset create <dataset-name> <path-to-jsonl-file>firectl sftj create \  --base-model <base-model-id> \  --dataset <dataset-name> \  --output-model <output-model-name>

When the training finishes, deploy the tuned model and use its model ID in place of a base model ID in your chat calls. To learn about supported base models, training methods, and deployment options, see Supervised Fine-Tuning in the Fireworks documentation.

Additional Resources

Back
Troubleshooting
Next
Get Started
Rate this page

On this page