Definir Ferramentas em JSON
Nesta página
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
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
messagesetools(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 otool_call_id - Verifique
finish_reasonpara saber se o modelo está à espera de um resultado - Pode declarar múltiplas ferramentas; o modelo escolhe automaticamente