Executar e Devolver o Resultado
Nesta página
O Passo que Controla Totalmente
Recebeu um tool_call do modelo. Este indica-lhe qual a função a chamar e com que argumentos—nada mais. Agora é o seu código que assume o controlo: executa a função, obtém o resultado e envia-o de volta ao modelo como uma mensagem com a função tool. Esta lição cobre todo este ciclo de ida e volta. Este é o único momento no ciclo em que toma todas as decisões.
Executar a Função no Lado do Cliente
Vamos revisitar o dicionário de despacho da Lição 4 e ligá-lo à resposta do modelo.
import json
from functools import partial
# Funções já definidas
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
}
# O modelo devolveu um tool_call
tool_call = response.choices[0].message.tool_calls[0]
function_name = tool_call.function.name
function_params = json.loads(tool_call.function.arguments)
# Executar a função
if function_name in available_functions:
result = available_functions[function_name](**function_params)
print(f"Result: {result}")
# → '{"status": "paid"}'
else:
result = json.dumps({"error": f"Function {function_name} not available"})
Dois mecanismos estão aqui em ação. O primeiro é **function_params, que desenrola o dicionário do JSON em argumentos nomeados: se o modelo gerou {"transaction_id": "T1001"}, a chamada é exatamente equivalente a retrieve_payment_status(transaction_id="T1001"). O segundo é o bloco else. É menos vistoso, mas essencial. Um modelo pode alucinar um nome de função que não existe no seu despacho; sem esta verificação, a sua aplicação levanta um KeyError e a conversa para abruptamente. Com ele, o erro torna-se dados que o modelo pode tratar graciosamente.
Construir a Mensagem da Ferramenta
O resultado deve voltar ao modelo num formato específico—uma mensagem com a função "tool":
tool_message = {
"role": "tool",
"name": function_name,
"content": result, # Deve ser uma string
"tool_call_id": tool_call.id
}
| Campo | Função |
|---|---|
role | "tool"—identifica a mensagem como um resultado de função |
name | O nome da função executada |
content | O resultado como uma string JSON |
tool_call_id | O ID do tool_call original—permite ao modelo associar o resultado à chamada correta |
Enviar o Resultado e Obter a Resposta Final
O modelo não tem memória de uma chamada para a outra: não se lembra de lhe ter pedido nada. Por isso, deve reconstruir toda a conversa para ele, incluindo o seu próprio pedido de chamada de ferramenta, antes de apresentar o resultado.
# 1. Adicionar a mensagem do assistente (com o tool_call)
messages.append(response.choices[0].message)
# 2. Adicionar o resultado da função
messages.append({
"role": "tool",
"name": function_name,
"content": result,
"tool_call_id": tool_call.id
})
# 3. Chamar o modelo novamente com o contexto completo
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
# 4. Mostrar a resposta final
print(final_response.choices[0].message.content)
# → "Payment T1001 status is: paid."
A ordem das duas operações append é inegociável: a mensagem do assistente que transporta o tool_call deve vir antes da mensagem tool que lhe responde. Trocar a ordem cria um histórico inconsistente que a API rejeita.
O Fluxo Completo num Único Bloco
Eis todo o processo, desde a pergunta do utilizador até à resposta final:
import os
import json
from mistralai.client import Mistral
from functools import partial
# Configuração
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
model = "mistral-large-latest"
# Funções e ferramentas (definidas anteriormente)
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
}
# Passos 1-2: Pergunta do utilizador + chamada à API
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
# Passos 3-4: Extrair o tool_call e executar
message = response.choices[0].message
if message.tool_calls:
tool_call = message.tool_calls[0]
function_name = tool_call.function.name
function_params = json.loads(tool_call.function.arguments)
# Execução no lado do cliente
result = available_functions[function_name](**function_params)
# Passo 5: Enviar o resultado de volta ao modelo
messages.append(message)
messages.append({
"role": "tool",
"name": function_name,
"content": result,
"tool_call_id": tool_call.id
})
final_response = client.chat.complete(
model=model, messages=messages, tools=tools
)
print(final_response.choices[0].message.content)
else:
print(message.content)
Estrutura da Mensagem em Cada Passo
Vale a pena inspecionar a lista messages assim que o ciclo termina, pois é a melhor forma de depurar chamadas de função com mau comportamento. Contém quatro mensagens.
# Mensagem 1: A pergunta do utilizador
{"role": "user", "content": "What is the status of payment T1001?"}
# Mensagem 2: A resposta do modelo com o tool_call
{"role": "assistant", "tool_calls": [{"id": "call_abc123", ...}]}
# Mensagem 3: O resultado da função
{"role": "tool", "name": "retrieve_payment_status",
"content": '{"status": "paid"}', "tool_call_id": "call_abc123"}
# Mensagem 4 (implícita): A resposta final do modelo
# → "Payment T1001 status is: paid."
Siga o ID call_abc123: nasce na Mensagem 2 e reaparece na Mensagem 3. Esse fio condutor liga o pedido à sua resposta. Esta estrutura é o padrão fundamental da chamada de funções; todas as variações que encontrar mais tarde, sejam de várias voltas ou paralelas, apenas o repetem ou duplicam.
Vigiar o Formato do Conteúdo
Um erro surge mais frequentemente do que todos os outros, e resume-se ao tipo do campo content: deve ser sempre uma string.
# Correto — string JSON
{"content": '{"status": "paid"}'}
# Correto — texto simples
{"content": "The status is paid"}
# Incorreto — dicionário Python (causará um erro)
{"content": {"status": "paid"}}
A diferença entre o primeiro e o terceiro exemplos reside nas aspas que envolvem o JSON. Se a sua função devolver um dicionário, converta-o com json.dumps() antes de enviar—é precisamente por isso que as funções na Lição 4 terminavam todas com um json.dumps().
Pontos-chave
- A execução da função ocorre no lado do cliente, no seu código—nunca pelo modelo
- O resultado é enviado de volta numa mensagem com a função
"tool"e otool_call_idcorrespondente - O
contentda mensagem da ferramenta deve ser uma string (uma string JSON) - Após enviar o resultado, chama
chat.complete()novamente para que o modelo possa formular a resposta final - Verifique sempre se a função solicitada existe no seu dicionário de despacho