Home
Studio

Use connectors in conversations

After you register a connector and connect it, you can attach it to a conversation. The model discovers the tools of the connector and calls the ones that match the request.

This page shows how to attach a connector, filter its tools, combine it with built-in tools, and add it to an agent so that every conversation with that agent can use it.

i
Information
Attach a connector to a conversation

Attach a connector to a conversation

To attach a connector, add an entry to the tools array with type: "connector" and the name or ID of the connector in connector_id.

The model can call every tool that the connector exposes. To restrict the list, see Filter tools.

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-small-latest",
        inputs=[
            {
                "role": "user",
                "content": "Using deepwiki, tell me about the structure of the sqlite/sqlite repository.",
            }
        ],
        tools=[
            {
                "type": "connector",
                "connector_id": "my_deepwiki",  # name or UUID
            },
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
Filter tools

Filter tools

To choose which tools of a connector the model can call, add a tool_configuration object. Set include to list the tools to allow, or exclude to list the tools to block. Use one or the other, not both.

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    # Exclude specific tools
    response = await client.beta.conversations.start_async(
        model="mistral-small-latest",
        inputs=[{"role": "user", "content": "What tools do you have access to?"}],
        tools=[
            {
                "type": "connector",
                "connector_id": "my_deepwiki",
                "tool_configuration": {
                    "exclude": ["read_wiki_structure"],
                },
            },
        ],
    )

    # Include only specific tools
    response = await client.beta.conversations.start_async(
        model="mistral-small-latest",
        inputs=[{"role": "user", "content": "What tools do you have access to?"}],
        tools=[
            {
                "type": "connector",
                "connector_id": "my_deepwiki",
                "tool_configuration": {
                    "include": ["ask_wiki_question"],
                },
            },
        ],
    )


asyncio.run(main())
Tip

To require approval before a tool runs, for example a tool that sends email or changes data, list it in requires_confirmation in the tool_configuration. For the full flow, see Human-in-the-loop.

Combine connectors with built-in tools

Combine connectors with built-in tools

You can pass built-in tools, such as web_search, code_interpreter, image_generation, and document_library, in the same tools array as connectors. The model picks the tool to call based on the request.

Warning

web_search, web_search_premium, and code_interpreter work with the Conversations API (/v1/conversations) and the Agents API. They aren't supported in the Chat Completions API (/v1/chat/completions). Built-in tools such as image_generation are also supported in the Chat Completions API.

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-small-latest",
        inputs=[
            {
                "role": "user",
                "content": "Search the web for the latest SQLite release, then use deepwiki to find where the version is defined in the sqlite/sqlite repo.",
            }
        ],
        tools=[
            {"type": "web_search"},
            {"type": "connector", "connector_id": "my_deepwiki"},
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
Add a connector to an agent

Add a connector to an agent

When an agent always needs the same tools, for example a support agent that queries a CRM, add the connector when you create the agent. Every conversation that you start with that agent can then call the tools of the connector, without a tools array.

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    # Create the agent with a connector
    agent = await client.beta.agents.create_async(
        name="deepwiki_agent",
        description="Agent with DeepWiki access for code repository exploration",
        model="mistral-small-latest",
        instructions="You are a helpful assistant that can explore code repositories using DeepWiki. Be concise.",
        tools=[
            {
                "type": "connector",
                "connector_id": "my_deepwiki",
            },
        ],
    )

    # Start a conversation using the agent. No tools needed here
    response = await client.beta.conversations.start_async(
        agent_id=agent.id,
        inputs=[
            {"role": "user", "content": "What is the main purpose of the sqlite repository?"}
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
Warning

To start a conversation with an agent, pass agent_id instead of model. You can't pass both.