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

Definir Ferramentas em JSON

Aula 4 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Da teoria à prática
  2. Estrutura do pedido com ferramentas
  3. Números-chave da implementação
  4. Gerir a resposta tool_call
  5. Executar e devolver o resultado
  6. Definir múltiplas ferramentas
  7. Verificar finish_reason
  8. Pontos-chave

Da teoria à prática

Já compreende o conceito de chamada de funções e a estrutura dos esquemas JSON. É altura de passar à implementação concreta. Nesta lição, vai aprender a construir um pedido completo com definições de ferramentas e a gerir a resposta do modelo.

Estrutura do pedido com ferramentas

Eis um pedido completo à API do Grok com uma ferramenta definida:

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.x.ai/v1"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "default": "celsius"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="grok-4.5",
    messages=[
        {"role": "user", "content": "What's the weather like in Paris?"}
    ],
    tools=tools
)

Note a estrutura aninhada: o objeto tools contém um array, onde cada elemento possui um type e um objeto function com os detalhes.

Números-chave da implementação

200
Ferramentas máximas por pedido
6
Tipos JSON suportados
3
SDKs compatíveis
1
Pedido = fluxo inteiro

Gerir a resposta tool_call

Quando o modelo decide chamar uma função, a resposta contém um array tool_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}")

O campo tool_call.function.arguments é uma cadeia JSON (não um objeto Python). Deve analisá-lo (parse):

import json

args = json.loads(tool_call.function.arguments)
city = args["city"]
unit = args.get("unit", "celsius")

Executar e devolver o resultado

Após executar a função, envia o resultado de volta ao modelo numa segunda chamada:

import json

# 1. Executar a função
weather_data = get_weather(city="Paris", unit="celsius")

# 2. Construir as mensagens com o resultado
messages = [
    {"role": "user", "content": "What's the weather like in Paris?"},
    message,  # A resposta do modelo com tool_calls
    {
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(weather_data)
    }
]

# 3. Chamar o modelo novamente com o resultado
final_response = client.chat.completions.create(
    model="grok-4.5",
    messages=messages,
    tools=tools
)

print(final_response.choices[0].message.content)

A mensagem com a função tool deve conter:

  • tool_call_id: o identificador único do tool_call (para o ligar ao pedido)
  • content: o resultado como uma cadeia JSON

Definir múltiplas ferramentas

Pode declarar tantas ferramentas quantas as necessárias no array tools:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": { ... }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_restaurants",
            "description": "Search for restaurants by city and cuisine type",
            "parameters": { ... }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "book_table",
            "description": "Book a table at a restaurant",
            "parameters": { ... }
        }
    }
]

O modelo escolherá automaticamente a(s) ferramenta(s) relevante(s) com base no pedido do utilizador.

Verificar finish_reason

O campo finish_reason na resposta indica se o modelo terminou a sua resposta ou se está à espera de um resultado de ferramenta:

finish_reason = response.choices[0].finish_reason

if finish_reason == "tool_calls":
    # O modelo está à espera do resultado de uma ou mais ferramentas
    handle_tool_calls(response)
elif finish_reason == "stop":
    # O modelo terminou a sua resposta
    print(response.choices[0].message.content)

Pontos-chave

  • O pedido contém messages e tools (definições)
  • Os argumentos do tool_call são uma cadeia JSON a analisar
  • Envie o resultado numa mensagem com a função tool, incluindo o tool_call_id
  • Verifique finish_reason para saber se o modelo está à espera de um resultado
  • Pode declarar múltiplas ferramentas; o modelo escolhe automaticamente