Chamar a API com Ferramentas
Nesta página
Enviar Ferramentas para a API da Mistral
Já definiu as suas funções e as respetivas especificações JSON. Agora, precisa de as enviar para a API da Mistral e, mais importante ainda, compreender o que o modelo devolve. Encontramo-nos agora nos passos 2 e 3 do processo: o modelo recebe o pedido do utilizador juntamente com as ferramentas e produz uma chamada de função — ou recusa fazê-la, o que é igualmente instrutivo.
O Primeiro Pedido
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Tools defined in the previous lesson
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"]
}
}
}
]
# User message
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# API call with tools
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Compreender a Resposta do Modelo
A resposta contém um objeto message que pode assumir duas formas, e o seu código deve lidar com ambas desde o primeiro dia. No primeiro caso, o modelo responde diretamente porque não é necessária nenhuma função: content contém texto e tool_calls é None.
# response.choices[0].message.content contains the text response
# response.choices[0].message.tool_calls is None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
No segundo caso, o modelo pretende chamar uma função. A situação inverte-se: content está vazio ou é nulo, e tool_calls transporta a carga útil.
# response.choices[0].message.content is None or empty
# response.choices[0].message.tool_calls contains the calls
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}")
Saída típica:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
Analisar a Resposta e Extrair tool_calls
Eis o código completo para extrair limpidamente informações de uma chamada de ferramenta:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Extract the function name
function_name = tool_call.function.name
# Parse JSON arguments into a Python dictionary
function_params = json.loads(tool_call.function.arguments)
# Retrieve the unique call identifier
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:
# The model responded directly
print(f"Response: {message.content}")
Três elementos de informação resultam deste bloco, sendo o terceiro aquele que as pessoas esquecem. O nome da função serve para o despacho, os argumentos analisados servem para a chamada, mas o tool_call_id é o que permite ao modelo associar o seu resultado à chamada correta quando o reenvia. Se o perder, o turno da conversa torna-se irrecuperável.
Quando o Modelo Solicita Informações em Falta
Por vezes, o utilizador não fornece informações suficientes. O modelo tem uma saída elegante: não chamar nenhuma função e, em vez disso, fazer uma pergunta de esclarecimento.
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 comportamento é exatamente o que deseja. O modelo sabe que transaction_id está listado em required; em vez de inventar um ID plausível e desencadear um pedido sobre dados inexistentes, cede a vez ao utilizador. Esta é também a melhor demonstração da utilidade do campo required abordado na lição anterior.
Gerir a Mensagem de Sistema
A mensagem de sistema permite-lhe enquadrar este comportamento em vez de esperar que ele ocorra.
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?"
}
]
Leia linha por linha: a primeira frase define o papel, a segunda define o tom e a língua do assistente, a terceira especifica quando usar funções e a última dá uma instrução explícita para um caso limite — informação em falta. Estes são os três casos de uso para os quais se recomenda uma mensagem de sistema, e na maioria das vezes são suficientes.
Código Completo para os Passos 2–3
Eis o código completo e reutilizável para enviar um pedido com ferramentas. Encapsula tudo o que foi visto acima e normaliza a resposta num dicionário com duas formas, poupando-o a espalhar verificações if message.tool_calls por toda a sua aplicação.
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
}
Note que a compreensão de lista itera sobre todas as tool_calls, e não apenas sobre a primeira. O modelo pode produzir várias de uma só vez; uma lição posterior abordará isso, mas a sua função utilitária já está pronta para as gerir.
Pontos-chave
- Envie
toolsemessagesparaclient.chat.complete()para ativar a chamada de funções - Verifique sempre se
message.tool_callsexiste antes de tentar analisar - O
tool_call_idé obrigatório para enviar o resultado de volta ao modelo - Os argumentos são uma cadeia JSON que deve ser analisada com
json.loads() - O modelo pode optar por responder diretamente se não precisar de uma função ou se faltar informação