Mistral API Guide: Agents, Conversations, and Stateful Handoffs

InYourLeague Research · 2026-09-05

Answer in brief

Mistral provides dedicated beta APIs for Agents and Conversations to configure assistants, tool integrations, and persistent multi-turn dialogue state. Developers can define reusable agent configurations or initiate standalone multi-turn conversations with internal cloud storage or client-side storage opt-out controls. The platform also supports automated guardrail enforcement and configurable server- or client-managed handoff modes across interaction turns.

Key facts at a glance

Failure modes and verification

FAQ

Can I use the Conversations API without creating an Agent first?

Yes, the Agents API and Conversations API are fully independent. You can initialize and manage conversations without creating an Agent by supplying the model parameter (for example, a chat completion model) directly in your conversation start request.

What is the difference between server and client handoff_execution modes?

The server mode, which is the default setting, executes the handoff internally on Mistral cloud servers. The client mode yields the response directly back to the user when a handoff is triggered, enabling client-side logic to handle and control the transition.

How can an application opt out of cloud-side conversation storage?

Applications can opt out of automatic storage by specifying store=False when starting or appending to a conversation. This prevents new interaction history from being stored on Mistral cloud servers.

How are safety guardrails handled between Agents and Conversations?

Guardrails configured directly on an Agent are automatically enforced across all conversations initiated under that Agent. When invoking conversations directly with a model, you can override or specify guardrails using the guardrails field on POST /v1/conversations.

What built-in tools are supported when defining an Agent in Mistral?

In addition to user-defined function calling, Mistral supports built-in tools including web_search, web_search_premium, code_interpreter, image_generation, and document_library for custom data grounding and RAG.

Sources and freshness

• Official source
• Last verified: 2026-09-05

Extended guide

Mistral offers an agentic framework structured around three foundational objects: Agents, Conversations, and Entries. Agents encapsulate reusable configurations including system instructions, model selections, tools, and completion parameters. Conversations manage interaction histories with an assistant, functioning either by binding to a predefined Agent ID or by directly invoking a chat completion model. Entries represent discrete actions generated by users or assistants, providing granular structural control over event sequences.

No product-specific selectable model ID has been verified for this entry. In official documentation examples, model identifiers such as mistral-medium-latest are supplied as sample selections rather than mandatory defaults or exhaustive lists.

Core Object Architecture and Tooling

When defining an Agent via the Mistral client (such as client.beta.agents.create), developers configure several distinct parameters:

• name: The human-readable name of the agent.
• description: A descriptive statement detailing the task or operational use case at stake.
• model: The model selected for chat completion.
• instructions (optional): The core system prompt directing the agent’s primary task.
• completion_args (optional): Standard sampling arguments such as temperature and top_p.
• tools (optional): A list of capabilities available to the agent, encompassing user-defined function calling alongside built-in tools such as web_search, web_search_premium, code_interpreter, image_generation, and document_library for custom data grounding.

Agents and Conversations operate independently. You can initialize persistent conversations directly referencing a model without registering an Agent beforehand.

Conversation Flows: Append, Storage, Guardrails, and Handoffs

Conversations maintain interaction state across turns. The public Conversations API strictly enforces ownership: an API key can read and modify only conversations owned by the creator of the API key used in the request. When continuing a conversation, each append request returns a newly updated Conversation ID that maps to the stored state.

Developers can control operational behavior through several parameters:

• store: Setting store=False disables cloud-side persistence, ensuring the new interaction history is not stored on Mistral cloud servers.
• guardrails: Guardrails defined on an Agent are applied automatically across all associated conversations. When executing a conversation directly with a model via POST /v1/conversations, developers can supply a guardrails field to apply custom guardrail rules.
• handoff_execution: Governs how handoffs are executed when delegating context. In server mode (the default), handoffs run internally on Mistral cloud servers. In client mode, when a handoff is triggered, a response is returned directly to the user, enabling client applications to manage the handoff explicitly.

Conceptual Step-by-Step Implementation Workflow

1. Initialize the Mistral client using an API key owned by the account managing conversation state.
2. Create an Agent by specifying the model (for example, mistral-medium-latest), name, task instructions, and desired tools (such as web_search).
3. Start a conversation using client.beta.conversations.start, supplying either the generated agent_id or a raw model parameter, alongside initial message inputs.
4. Capture the returned conversation ID from the conversation start response.
5. Append follow-up turns by providing the existing conversation_id and subsequent inputs to the conversation continuation endpoint, observing the newly issued conversation ID returned at each turn.
6. Configure handoff_execution as server or client depending on whether orchestration should occur in cloud infrastructure or client application logic.
7. Apply store=False if operational or regulatory requirements necessitate opting out of cloud conversation persistence.

Architectural Summary Table

Implementation Checklist

• Verify that the API key belongs to the account managing conversation state.
• Choose between Agent-bound sessions or standalone model conversations.
• Select appropriate built-in tools (e.g., web_search, code_interpreter, document_library) or user function definitions.
• Configure completion_args (such as temperature and top_p) according to task sensitivity.
• Determine whether handoff_execution should remain server-side or switch to client-side control.
• Review data compliance policies to evaluate whether store=False is required to prevent cloud storage.
• Verify custom guardrail overrides on POST /v1/conversations when omitting Agent pre-configurations.

Detailed specifications and endpoints can be accessed at the Mistral Agents API Documentation.