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

Chamar a API com Ferramentas

Aula 5 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Enviar Ferramentas para a API da Mistral
  2. O Primeiro Pedido
  3. Compreender a Resposta do Modelo
  4. Analisar a Resposta e Extrair tool_calls
  5. Quando o Modelo Solicita Informações em Falta
  6. Gerir a Mensagem de Sistema
  7. Código Completo para os Passos 2–3
  8. Pontos-chave

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 tools e messages para client.chat.complete() para ativar a chamada de funções
  • Verifique sempre se message.tool_calls existe 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