How to create a first Mistral agent

Mistral’s Agents API saves a predefined model setup you can reuse: a model, a name, a description, and, if you need them, instructions, tools, and completion arguments. Conversations are a separate feature. They keep a history of interactions with an assistant that uses an agent, or a model directly. The docs say the two APIs are independent, and that you can create conversations without creating an agent.

This walkthrough stays on the create call. You will make the documented simple agent, then the documented web-search agent, and keep the agent ID that comes back. That ID is what later conversations use. These steps do not build a chat UI.

Fields on the create call

An agent is a set of pre-selected values that augment model abilities, such as tools, instructions, and completion parameters. Those values define how the model behaves.

The agents page lists what to set in advance:

• model is the model the agent will use, chosen from the models available for chat completion.
• description is related to the task or the use case.
• name is the agent’s name.
• instructions is optional. It is the main instructions, also called the system prompt, and it must accurately describe the main task.
• tools is optional. It is a list of tools the model can use. Types named on that page include user-defined function tools, built-in web_search and web_search_premium, code_interpreter, image_generation, and document_library.
• completion_args is optional. These are standard chat completion sampler arguments. All chat completion arguments are accepted.

The first example sets only model, description, and name. Instructions, tools, and completion arguments stay unset.

Create the simple agent

The Python example reads the key from the environment, passes it to the client, and calls the agents create method. The fetched pages do not include an install command or a path for issuing the key. The snippet expects the named environment variable to already be set.

import os
from mistralai.client import Mistral

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

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

Copy that block as it appears. The model, description, and name are the three strings in the call.

Save the agent ID

Creating an agent returns an Agent object with an agent ID. The docs say you can then use that ID to have conversations. There is no extra lookup in the example. The ID is on the object you just received. The start example later on the same page reads it as simple_agent.id.

Keep it. After the agent exists, you can start a conversation at any point by passing that agent ID and inputs. Inputs can be a string with the first user message or question, or a history of messages. Starting a conversation returns a conversation ID, which is a different value from the agent ID.

You can also start and continue conversations with no agent at all. In that case the docs say to use a model parameter instead of an agent ID. The public Conversations API can read and modify only the conversations owned by the creator of the API key used in the request.

Create the web-search agent

The same page shows a second create call: an agent able to search the web. It still sets model, description, and name, and it adds instructions, a tools list, and completion arguments.

websearch_agent = client.beta.agents.create(
    model="mistral-medium-latest",
    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,
    }
)

The tools list contains one object whose type is web search. The instructions tell the model it can perform web searches with that tool to find up-to-date information. The completion arguments in the snippet set temperature and top_p to the numbers shown. This call returns its own Agent object and its own ID. Conversations that should search use that ID, not the simple agent’s ID.

The tools page describes web search as a built-in tool for up-to-date information that is not in the agent’s knowledge. Built-in tools are ready out of the box. They can be called at any point, and all execution happens in Mistral’s internal environment. The same built-in tools can be used directly via Conversations without creating an agent first. You specify the tool in the tools parameter when creating an agent or when calling the Conversations API. You can use more than one tool at the same time.

Where web search is supported

Support depends on the API. The tools page warns that web_search, web_search_premium, and code_interpreter work with the Conversations API (/v1/conversations) and the Agents API. They are not supported in the Chat Completions API (/v1/chat/completions). Built-in tools such as image_generation are also supported in Chat Completions.

Other types on that page, if you later move past the first web-search agent:

• Code Interpreter runs code and can generate plots, for data analysis, visualization, or sandboxed execution.
• Image Generation generates images from a prompt or description.
• Document Library searches documents uploaded to your Libraries, enabling RAG so answers can use that information.
• Function Calling is for custom local tools. Functions are defined in your environment, and execution happens locally.
• Connectors register MCP servers as managed connectors. Tools are discovered automatically and executed server-side.

For a first agent, stay with the two create calls. Do not put web search or the code interpreter on a Chat Completions request and expect Agents API behavior.

How a later conversation uses the ID

The agents page shows the next use of the ID without defining a UI. One documented start passes the simple agent’s ID and a string input:

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
)

The comment marks the message-list form of inputs as also valid. The commented store flag is the documented opt-out from automatic storing, so the new history is not stored on Mistral’s cloud. A start without an agent, on the same page, passes a model instead of an agent ID.

Next step

Run the simple create call and save the agent ID on the returned object. If the agent needs current web information, run the web-search create call and save that second ID. Then read the Agents and Conversations page for the start call that takes the agent ID, and the Tools page for which built-in tools are valid on the Agents API rather than Chat Completions.

Sources

• Agents & Conversations
• Tools