Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Executar e Devolver o Resultado

Aula 6 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. O Passo que Controla Totalmente
  2. Executar a Função no Lado do Cliente
  3. Construir a Mensagem da Ferramenta
  4. Enviar o Resultado e Obter a Resposta Final
  5. O Fluxo Completo num Único Bloco
  6. Estrutura da Mensagem em Cada Passo
  7. Vigiar o Formato do Conteúdo
  8. Pontos-chave

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
}
CampoFunção
role"tool"—identifica a mensagem como um resultado de função
nameO nome da função executada
contentO resultado como uma string JSON
tool_call_idO 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 o tool_call_id correspondente
  • O content da 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