Agents & Conversations

Agents is a feature that allows developers to create predefined models with their own system prompts and tools. In the other hand, Conversations is a feature that allows developers to create a history of interactions with an assistant that leverage Agents or our models directly.

We introduce three new main objects that our API makes use of:

• Agents: A set of pre-selected values to augment model abilities, such as tools, instructions, and completion parameters.
• Conversation: A history of interactions, past events and entries with an assistant, such as messages and tool executions, Conversations can be started by an Agent or a Model.
• Entry: An action that can be created by the user or an assistant. It brings a more flexible and expressive representation of interactions between a user and one or multiple assistants. This allows for more control over describing events.

To find all details visit our Agents and Conversations API spec.

Agent Creation and Management

Agents are a set of pre-selected values, such as tools, instructions, and completion parameters, that will define the behavior of the model.

import os
from mistralai import Mistral

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

simple_agent = client.beta.agents.create(
    model="mistral-medium-2505",
    description="A simple Agent with persistent state.",
    name="Simple Agent"
)

import os
from mistralai import Mistral

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

simple_agent = client.beta.agents.create(
    model="mistral-medium-2505",
    description="A simple Agent with persistent state.",
    name="Simple Agent"
)

websearch_agent = client.beta.agents.create(
    model="mistral-medium-2505",
    description="Agent able to search information over the web, such as news, weather, sport results...",
    name="Websearch Agent",
    instructions="You have the ability to perform web searches with `web_search` to find up-to-date information.",
    tools=[{"type": "web_search"}],
    completion_args={
        "temperature": 0.3,
        "top_p": 0.95,
    }
)

websearch_agent = client.beta.agents.create(
    model="mistral-medium-2505",
    description="Agent able to search information over the web, such as news, weather, sport results...",
    name="Websearch Agent",
    instructions="You have the ability to perform web searches with `web_search` to find up-to-date information.",
    tools=[{"type": "web_search"}],
    completion_args={
        "temperature": 0.3,
        "top_p": 0.95,
    }
)

Conversations

In the other hand, Conversations are a history of interactions with an assistant. They are more flexible and expressive than the Chat Completion API, allowing for more control over describing events.

Once your agent is created, you can start conversations at any point while keeping the same conversation persistent. You first start a conversation by providing:

• agent_id: The ID of the agent, created during the Agent creation.
• inputs: The message to start the conversation with. It can be either a string with the first user message or question, or the history of messages.

Creating a Conversation will return a conversation ID.

To continue the conversation and append the exchanges as you go, you provide two values:

• conversation_id: The ID created during the conversation start or append that maps to the internally stored conversation history.
• inputs: The next message or reply. It can be either a string or a list of messages.

A new Conversation ID is provided at each append.

You can also opt out from the automatic storing with store=False; this will make the new history not being stored on our cloud.

We also provide the parameter handoff_execution, which currently has two modes: server or client.

• server: Runs the handoff as expected internally on our cloud servers; this is the default setting.
• client: When a handoff is triggered, a response is provided directly to the user, enabling them to handle the handoff with control.

For more information regarding handoffs visit this section.

Below you can find examples of how to create and manage conversations.

response = client.beta.conversations.start(
    agent_id=simple_agent.id,
    inputs="Who is Albert Einstein?",
    # inputs=[{"role": "user", "content": "Who is Albert Einstein?"}] is also valid
    # store=False
)

response = client.beta.conversations.start(
    agent_id=simple_agent.id,
    inputs="Who is Albert Einstein?",
    # inputs=[{"role": "user", "content": "Who is Albert Einstein?"}] is also valid
    # store=False
)

response = client.beta.conversations.start(
    model="mistral-medium-latest",
    inputs=[{"role": "user", "content": "Who is Albert Einstein?"}]
)

response = client.beta.conversations.start(
    model="mistral-medium-latest",
    inputs=[{"role": "user", "content": "Who is Albert Einstein?"}]
)