Human-in-the-loop

Some tool calls, such as sending an email or changing data, need a person to approve them first. With requires_confirmation, the conversation stops before these calls run, so that a user or your system can approve or deny each one.

i
Information

Confirmation works for connector tools, built-in tools such as web_search_premium, and local functions. Local functions are available in the Python SDK only.

You can implement the confirmation flow in two ways:

  • REST API: you manage the conversation IDs and tool call IDs. Works with any language or HTTP client.
  • Python SDK: RunContext and DeferredToolCallsException manage the IDs for you.
Choose the tools that need approval

Choose the tools that need approval

In the tool_configuration of a connector or built-in tool, list the names of the tools that need approval in requires_confirmation:

[
  {
    "type": "connector",
    "connector_id": "gmail",
    "tool_configuration": {
      "requires_confirmation": ["gmail_search"]
    }
  },
  {
    "type": "web_search_premium",
    "tool_configuration": {
      "requires_confirmation": ["web_search", "news_search"]
    }
  }
]
Confirm tool calls with the REST API

Confirm tool calls with the REST API

The REST API flow has two steps:

  1. Start the conversation and get a pending function.call.
  2. Approve or deny the call to resume the conversation.
Start a conversation that needs approval

Start a conversation that needs approval

The API returns a pending function.call entry instead of running the tool.

RESPONSE=$(curl -s -X POST "https://api.mistral.ai/v1/conversations" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-medium-latest",
    "inputs": "What is the title of my latest email?",
    "tools": [
      {
        "type": "connector",
        "connector_id": "gmail",
        "tool_configuration": {
          "requires_confirmation": ["gmail_search"]
        }
      }
    ]
  }')

CONVERSATION_ID=$(echo "$RESPONSE" | jq -r '.conversation_id')
TOOL_CALL_ID=$(echo "$RESPONSE" | jq -r '.outputs[0].tool_call_id')

The response contains a pending function.call:

{
  "conversation_id": "conv_abc123...",
  "outputs": [
    {
      "type": "function.call",
      "tool_call_id": "WJfo42Ow3",
      "name": "gmail_search",
      "arguments": "{\"limit\": 1}",
      "confirmation_status": "pending"
    }
  ]
}
Approve a pending tool call

Approve a pending tool call

To run the tool and get the model response, send "allow".

curl -X POST "https://api.mistral.ai/v1/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_confirmations": [
      {"tool_call_id": "'$TOOL_CALL_ID'", "confirmation": "allow"}
    ]
  }'
Deny a pending tool call

Deny a pending tool call

To reject the call, send "deny". The tool doesn't run, and the model answers without its result.

curl -X POST "https://api.mistral.ai/v1/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_confirmations": [
      {"tool_call_id": "'$TOOL_CALL_ID'", "confirmation": "deny"}
    ]
  }'
Tip

Several tool calls can be pending at the same time. Approve or deny them one by one, or send all the decisions in one tool_confirmations array.

Confirm tool calls with the Python SDK

Confirm tool calls with the Python SDK

i
Information

The Python SDK flow requires mistralai 2.4 or later with the agents extra: pip install "mistralai[agents]". With an earlier version, use the REST API flow.

run_async runs the conversation loop and raises DeferredToolCallsException when a tool needs approval. Call dc.confirm() or dc.reject() on each deferred call, then run the loop again to resume.

Confirm local function calls

Confirm local function calls

Register your Python functions with register_func. For each function that needs approval, set requires_confirmation=True.

import asyncio
import os
import random

from mistralai.client import Mistral
from mistralai.extra.run.context import RunContext
from mistralai.extra.exceptions import DeferredToolCallsException


def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    temp = random.randint(10, 30)
    return f"The weather in {city} is {random.choice(['sunny', 'cloudy'])}, {temp}C"


def book_flight(destination: str, date: str) -> str:
    """Book a flight to a destination."""
    return f"Flight booked to {destination} on {date}. Confirmation: FL-{random.randint(10000, 99999)}"


async def main():
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

    conversation_id = None
    pending_inputs = [
        {"role": "user", "content": "I need a vacation somewhere warm next Friday. Can you help?"}
    ]

    while True:
        async with RunContext(model="mistral-large-latest") as run_ctx:
            run_ctx.conversation_id = conversation_id
            run_ctx.register_func(get_weather, requires_confirmation=False)
            run_ctx.register_func(book_flight, requires_confirmation=True)

            try:
                result = await client.beta.conversations.run_async(
                    run_ctx=run_ctx,
                    inputs=pending_inputs,
                    instructions="You are a travel assistant. Check the weather and book a flight to the warmest destination.",
                )
                print(result.output_entries)
                break

            except DeferredToolCallsException as deferred:
                conversation_id = deferred.conversation_id

                pending_inputs = []
                for dc in deferred.deferred_calls:
                    print(f"[APPROVAL REQUIRED] {dc.tool_name}({dc.arguments})")
                    approved = input("Approve? (y/n): ").strip().lower() == "y"
                    pending_inputs.append(dc.confirm() if approved else dc.reject("Denied by user"))


asyncio.run(main())
Confirm connector tool calls

Confirm connector tool calls

Connector tools work the same way: run_async raises DeferredToolCallsException when the server returns a function.call with confirmation_status: "pending".

import asyncio
import os

from mistralai.client import Mistral
from mistralai.extra.exceptions import DeferredToolCallsException
from mistralai.extra.run.context import RunContext


async def main():
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

    conversation_id = None
    pending_inputs = [{"role": "user", "content": "Summarize my latest emails from Gmail."}]

    while True:
        async with RunContext(model="mistral-large-latest") as run_ctx:
            run_ctx.conversation_id = conversation_id

            try:
                result = await client.beta.conversations.run_async(
                    run_ctx=run_ctx,
                    inputs=pending_inputs,
                    instructions="You are a helpful assistant. Use Gmail to access the user's emails.",
                    tools=[
                        {
                            "type": "connector",
                            "connector_id": "gmail",
                            "tool_configuration": {
                                "requires_confirmation": ["gmail_search"],
                            },
                        },
                    ],
                )
                for entry in result.output_entries:
                    if hasattr(entry, "content"):
                        print(entry.content)
                break

            except DeferredToolCallsException as deferred:
                conversation_id = deferred.conversation_id

                pending_inputs = []
                for dc in deferred.deferred_calls:
                    print(f"[APPROVAL REQUIRED] {dc.tool_name}({dc.arguments})")
                    approved = input("Approve? (y/n): ").strip().lower() == "y"
                    pending_inputs.append(dc.confirm() if approved else dc.reject("Denied by user"))


asyncio.run(main())
Resume from a separate request

Resume from a separate request

When the approval arrives in a separate request, for example from your frontend, serialize the deferred state and rebuild it when the approval arrives.

import asyncio, json, os
from mistralai.client import Mistral
from mistralai.extra.run.context import RunContext
from mistralai.extra.exceptions import DeferredToolCallsException


def book_flight(destination: str, date: str) -> str:
    """Book a flight to a destination."""
    return f"Flight booked to {destination} on {date}"


async def main():
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

    async with RunContext(model="mistral-large-latest") as run_ctx:
        run_ctx.register_func(book_flight, requires_confirmation=True)

        try:
            result = await client.beta.conversations.run_async(
                run_ctx=run_ctx,
                inputs=[{"role": "user", "content": "Book me a flight to Paris next Friday."}],
                instructions="You are a travel assistant. Book the flight directly.",
            )
            print("No confirmation needed:", result.output_as_text)

        except DeferredToolCallsException as deferred:
            # Serialize and send to frontend / store in DB
            print(json.dumps(deferred.to_dict()))


asyncio.run(main())
i
Information

deferred.executed_results contains the results of the tools that ran before the deferral. Put them first in the inputs when you resume, so that the model has the full context.