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.
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:
RunContextandDeferredToolCallsExceptionmanage the IDs for you.
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
The REST API flow has two steps:
- Start the conversation and get a pending
function.call. - Approve or deny the call to resume the conversation.
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
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
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"}
]
}'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
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
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
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
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())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.