document_library Tool: QnA on Your Files

Lesson updated November 3, 2026 based on mistralai SDK 3.7.0: library documents are managed via client.beta.libraries.documents (upload, list, delete). The add_document, list_documents, and remove_document methods from the previous version no longer exist, and uploads now go directly into the library. Source: client-python.

Mistral’s Built-in RAG

The document_library tool is a Retrieval-Augmented Generation (RAG) system built directly into the Agents API. Your agent accesses documents you’ve uploaded to the Mistral cloud, retrieves relevant passages, and formulates its response with citations. The difference compared to a homegrown RAG solution is significant: you don’t need to host a vector database, maintain an embedding pipeline, or tune a chunking strategy. You simply upload files, declare the tool when creating the agent, and let the model decide when to query the library.

Create a Document Library

A library is the container that holds your documents. You create it with a single API call before uploading any files.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Create a library
library = client.beta.libraries.create(
    name="Technical Documentation",
    description="Product manuals and technical specifications."
)

print(f"Library ID: {library.id}")

Take note of the returned ID: this is what you pass to the agent. There is no shortcut using the library name. If your team manages separate HR, legal, and technical libraries, store these IDs in your configuration just like connection strings.

Upload Documents

Uploading happens in two steps: first, the file is deposited into the Files space with an explicit purpose, then it is attached to the library.

# Upload a PDF directly to the library
with open("product-manual.pdf", "rb") as f:
    document = client.beta.libraries.documents.upload(
        library_id=library.id,
        file={"file_name": "product-manual.pdf", "content": f},
    )

print(f"Document {document.id}: {document.processing_status}")

Supported formats include PDF, plain text, and other common document types.

Create an Agent with a Document Library

agent = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Documentation Agent",
    instructions="""You are a documentation assistant.
- Answer only using documents from the library
- Cite relevant passages
- If the information is not in the documents, state this clearly""",
    tools=[{
        "type": "document_library",
        "library_ids": [library.id]
    }]
)

The library_ids parameter is a list: you can associate multiple libraries with a single agent. For example, a support assistant might use both product documentation and internal procedures. Here, instructions are more than just nice to have. Without the directive to limit responses to documents, the model fills gaps with its general knowledge, and you lose the ability to distinguish what comes from your files versus what comes from elsewhere. The third line—explicitly stating when information is missing—is what turns a chatty agent into a reliable one.

Query the Documents

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="How does the Pixtral 12B vision encoder work?"
)

for entry in response.outputs:
    if entry.type == "message.output":
        for chunk in entry.content:
            if chunk.type == "text":
                print(chunk.text)
            elif chunk.type == "tool_reference":
                print(f"  [Source] {chunk.title}")

Like web search, the response arrives in chunks of two types. text chunks contain the written response; tool_reference chunks contain the provenance, with the title field holding the source document name and the url field providing the internal reference within that document. This separation lets you display the answer and, just below it, the list of documents that produced it.

This traceability isn’t just decorative. An advisor answering a client based on an internal procedure must be able to specify which procedure they’re citing; a lawyer relying on a contract must be able to trace back to that contract. Without citations, a RAG system produces unverifiable claims.

Manage Libraries

# List libraries
libraries = client.beta.libraries.list()
for lib in libraries.data:
    print(f"{lib.name} ({lib.id})")

# List documents in a library
documents = client.beta.libraries.documents.list(library_id=library.id)
for doc in documents.data:
    print(f"{doc.name} — {doc.size} bytes")

# Delete a document from the library
client.beta.libraries.documents.delete(
    library_id=library.id,
    document_id=document.id
)

# Delete the library
client.beta.libraries.delete(library_id=library.id)

Removing documents is the most often overlooked operation, and the most costly when forgotten. An outdated version of a price list or procedure remains citable by the agent indefinitely, carrying all the appearance of legitimacy because it is sourced. Make removing a document a reflex whenever you publish a new version.

From Internal Support to Contract Analysis

Internal support is the most immediate use case: employees ask HR questions in natural language instead of digging through an intranet.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Internal Support",
    instructions="Answer employee questions using the HR documentation base.",
    tools=[{"type": "document_library", "library_ids": [rh_library.id]}]
)

Contract analysis shifts the paradigm: the agent doesn’t just retrieve, it examines. Here, instructions describe a task, not just a scope.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Contract Analyst",
    instructions="""Analyze uploaded contracts.
- Identify important clauses
- Flag potential risks
- Compare against industry standards""",
    tools=[{"type": "document_library", "library_ids": [contrats_library.id]}]
)

Finally, a product knowledge base illustrates tool combination: official documentation takes precedence, and web search fills the gaps when docs don’t cover a question.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Product Expert",
    instructions="Answer technical questions about our products based on official documentation.",
    tools=[
        {"type": "document_library", "library_ids": [docs_library.id]},
        {"type": "web_search"}  # Fallback if docs are insufficient
    ]
)

Prepare Sources, Isolate Libraries

RAG quality is determined before you even call the API. A structured PDF with clear headings, subheadings, and distinct paragraphs chunks and retrieves far better than a flattened scan or a document where all logic resides in the layout. Next, separate your libraries by domain rather than creating a single catch-all bucket. An agent connected only to the legal library won’t risk citing an HR memo to answer a contract question. These two decisions—polishing source structure and isolating libraries—impact the final result more than any model tuning.

Key Takeaways

• document_library is built-in RAG—no need to manage your own vector infrastructure
• Create thematic libraries and upload documents via the Files API
• Responses cite relevant passages using tool_reference chunks
• You can associate multiple libraries with a single agent
• Combine with other tools for comprehensive coverage