Llamar a la API con herramientas
En esta página
Enviar herramientas a la API de Mistral
Ya has definido tus funciones y sus especificaciones JSON. Ahora debes enviarlas a la API de Mistral y, lo que es más importante, comprender qué devuelve el modelo. Nos encontramos en los pasos 2 y 3 del proceso: el modelo recibe la solicitud del usuario junto con las herramientas y genera una llamada a función, o bien decide no hacer ninguna, lo cual resulta igualmente instructivo.
La primera solicitud
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Herramientas definidas en la lección anterior
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"]
}
}
}
]
# Mensaje del usuario
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# Llamada a la API con herramientas
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Comprender la respuesta del modelo
La respuesta contiene un objeto message que puede adoptar dos formas, y tu código debe gestionar ambas desde el primer día. En el primer caso, el modelo responde directamente porque no necesita ninguna función: content contiene texto y tool_calls es None.
# response.choices[0].message.content contiene la respuesta de texto
# response.choices[0].message.tool_calls es None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
En el segundo caso, el modelo quiere llamar a una función. La situación se invierte: content está vacío o es null, y tool_calls contiene la carga útil.
# response.choices[0].message.content es None o está vacío
# response.choices[0].message.tool_calls contiene las llamadas
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}")
Salida típica:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
Analizar la respuesta y extraer tool_calls
Aquí tienes el código completo para extraer limpiamente la información de una llamada a herramienta:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Extraer el nombre de la función
function_name = tool_call.function.name
# Analizar los argumentos JSON en un diccionario de Python
function_params = json.loads(tool_call.function.arguments)
# Recuperar el identificador único de la llamada
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:
# El modelo respondió directamente
print(f"Response: {message.content}")
De este bloque se obtienen tres datos, y el tercero es el que la gente suele olvidar. El nombre de la función se usa para el enrutamiento (dispatching), los argumentos analizados se emplean para realizar la llamada, pero el tool_call_id es lo que permite al modelo asociar tu resultado con la llamada correcta cuando se lo envías de vuelta. Si lo pierdes, el turno de la conversación se vuelve irrecuperable.
Cuando el modelo solicita información faltante
A veces el usuario no proporciona suficiente información. El modelo tiene una salida elegante: no llamar a ninguna función en absoluto y, en su lugar, formular una pregunta de aclaración.
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?"
Este comportamiento es exactamente lo que deseas. El modelo sabe que transaction_id figura en required; en lugar de inventar un ID plausible y desencadenar una solicitud sobre datos inexistentes, cede la palabra al usuario. Esta es también la mejor demostración de la utilidad del campo required tratado en la lección anterior.
Gestionar el mensaje de sistema
El mensaje de sistema te permite encuadrar este comportamiento en lugar de confiar en que ocurra por sí solo.
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?"}
}
]
Léelo línea por línea: la primera frase establece el rol, la segunda define el tono y el idioma del asistente, la tercera especifica cuándo usar las funciones y la última da una instrucción explícita para un caso límite: la falta de información. Estos son los tres casos de uso para los que se recomienda un mensaje de sistema, y suelen ser suficientes la mayor parte del tiempo.
Código completo para los pasos 2–3
Aquí tienes el código completo y reutilizable para enviar una solicitud con herramientas. Encapsula todo lo anterior y normaliza la respuesta en un diccionario con dos formas, ahorrándote tener que dispersar comprobaciones if message.tool_calls por toda tu aplicación.
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
}
Ten en cuenta que la comprensión de lista itera sobre todas las tool_calls, no solo sobre la primera. El modelo puede generar varias a la vez; una lección posterior cubrirá esto, pero tu función de utilidad ya está preparada para gestionarlas.
Puntos clave
- Envía
toolsymessagesaclient.chat.complete()para habilitar la llamada a funciones - Comprueba siempre si
message.tool_callsexiste antes de intentar analizarlo - El
tool_call_ides obligatorio para enviar el resultado de vuelta al modelo - Los argumentos son una cadena JSON que debe analizarse con
json.loads() - El modelo puede optar por responder directamente si no necesita una función o si falta información