De API aanroepen met Tools
Op deze pagina
Tools verzenden naar de Mistral API
U heeft uw functies en hun JSON-specificaties gedefinieerd. Nu moet u deze naar de Mistral API verzenden en, nog belangrijker, begrijpen wat het model retourneert. We bevinden ons nu bij stap 2 en 3 van het proces: het model ontvangt het verzoek van de gebruiker samen met de tools en produceert een functieaanroep, of weigert er een te doen, wat even leerzaam is.
Het eerste verzoek
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Tools gedefinieerd in de vorige les
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Retrieves the status of a payment based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Unique transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
# Bericht van de gebruiker
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# API-aanroep met tools
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
De respons van het model begrijpen
De respons bevat een message-object dat twee vormen kan aannemen, en uw code moet vanaf dag één beide afhandelen. In het eerste geval reageert het model direct omdat er geen functie nodig is: content bevat tekst en tool_calls is None.
# response.choices[0].message.content bevat de tekstrespons
# response.choices[0].message.tool_calls is None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
In het tweede geval wil het model een functie aanroepen. De situatie is dan omgekeerd: content is leeg of null, en tool_calls bevat de payload.
# response.choices[0].message.content is None of leeg
# response.choices[0].message.tool_calls bevat de aanroepen
message = response.choices[0].message
if message.tool_calls:
for tool_call in message.tool_calls:
print(f"Function: {tool_call.function.name}")
print(f"Arguments: {tool_call.function.arguments}")
print(f"ID: {tool_call.id}")
Typische uitvoer:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
De respons parseren en tool_calls extraheren
Hier is de volledige code om informatie uit een tool-aanroep op een schone manier te extraheren:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# De functienaam extraheren
function_name = tool_call.function.name
# JSON-argumenten parseren naar een Python-dictionary
function_params = json.loads(tool_call.function.arguments)
# De unieke aanroep-ID ophalen
tool_call_id = tool_call.id
print(f"The model wants to call: {function_name}")
print(f"With parameters: {function_params}")
print(f"Call ID: {tool_call_id}")
else:
# Het model heeft direct gereageerd
print(f"Response: {message.content}")
Er komen drie informatieonderdelen uit dit blok, en het derde is degene die mensen vaak vergeten. De functienaam wordt gebruikt voor dispatching, de geparseerde argumenten voor de aanroep, maar de tool_call_id is wat het model in staat stelt uw resultaat aan de juiste aanroep te koppelen wanneer u het terugstuurt. Als u deze verliest, wordt de conversatiestap onherstelbaar.
Wanneer het model ontbrekende informatie opvraagt
Soms levert de gebruiker niet genoeg informatie. Het model heeft een elegante uitweg: helemaal geen functie aanroepen, maar in plaats daarvan een verduidelijkende vraag stellen.
messages = [
{"role": "user", "content": "What is the status of my payment?"}
]
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
message = response.choices[0].message
print(message.content)
# → "I need the transaction ID to check the status.
# Could you please provide the transaction number?"
Dit gedrag is precies wat u wilt. Het model weet dat transaction_id in required staat; in plaats van een plausibele ID te verzinnen en een verzoek op niet-bestaande gegevens te triggeren, geeft het het woord terug aan de gebruiker. Dit is ook het beste bewijs van het nut van het veld required dat in de vorige les aan bod kwam.
Het system-bericht afhandelen
Met het system-bericht kunt u dit gedrag sturen in plaats van erop te hopen.
messages = [
{
"role": "system",
"content": "You are a payment tracking assistant. "
"Respond in English. "
"Use the available tools to answer questions "
"about transactions. If the user does not provide "
"the transaction ID, ask for it politely."
},
{
"role": "user",
"content": "What is the status of payment T1001?"
}
]
Lees het regel voor regel: de eerste zin stelt de rol in, de tweede de toon en taal van de assistent, de derde specificeert wanneer functies gebruikt moeten worden, en de laatste geeft een expliciete instructie voor een randgeval—ontbrekende informatie. Dit zijn de drie use cases waarvoor een system-bericht wordt aanbevolen, en ze volstaan meestal.
Volledige code voor stap 2–3
Hier is de volledige, herbruikbare code om een verzoek met tools te verzenden. Het kapselt alles hierboven in en normaliseert de respons naar een dictionary met twee vormen, zodat u niet overal in uw applicatie if message.tool_calls-controles hoeft te verspreiden.
import os
import json
from mistralai.client import Mistral
def call_mistral_with_tools(
messages: list,
tools: list,
model: str = "mistral-large-latest",
tool_choice: str = "auto"
) -> dict:
"""Sends a request to Mistral with tools and returns the parsed response."""
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.chat.complete(
model=model,
messages=messages,
tools=tools,
tool_choice=tool_choice
)
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
return {
"type": "tool_call",
"message": message,
"tool_calls": [
{
"id": tc.id,
"function_name": tc.function.name,
"arguments": json.loads(tc.function.arguments)
}
for tc in message.tool_calls
]
}
return {
"type": "text",
"message": message,
"content": message.content
}
Merk op dat de list comprehension itereren over alle tool_calls, niet alleen de eerste. Het model kan er meerdere tegelijk produceren; een latere les behandelt dat, maar uw utility-functie is al klaar om ze af te handelen.
Belangrijkste punten
- Verzending
toolsenmessagesnaarclient.chat.complete()om functieaanroepen in te schakelen - Controleer altijd of
message.tool_callsbestaat voordat u probeert te parseren - De
tool_call_idis verplicht om het resultaat terug te sturen naar het model - Argumenten zijn een JSON-string die met
json.loads()geparseerd moet worden - Het model kan kiezen om direct te reageren als het geen functie nodig heeft of als informatie ontbreekt