DocumentaçãoFerramentas
Construir
Ferramentas
Descreve as tuas funções ao modelo. Ele decide quando chamar uma, o teu código executa-a e devolve-lhe o resultado.
Nesta página
O ciclo completo
Descreves a função
O seu nome, o que faz e os seus parâmetros, em JSON Schema.
O modelo pede a chamada
Em vez de texto, devolve tool_calls com os argumentos.
O teu código executa-a
O modelo não executa nada sozinho. Manténs o controlo sobre o que acontece.
O modelo responde
Com o resultado devolvido numa mensagem tool, escreve a sua resposta.
Exemplo
Uma função que diz se uma fatura está paga. A resposta mostrada é a da primeira chamada, quando o modelo pede a função.
import json
tools = [
{
"type": "function",
"function": {
"name": "invoice_status",
"description": "Payment status of an invoice.",
"parameters": {
"type": "object",
"properties": {"number": {"type": "string"}},
"required": ["number"],
},
},
}
]
messages = [
{
"role": "user",
"content": "Has invoice 2026-114 been paid?",
}
]
first = client.chat.completions.create(
model="flash", messages=messages, tools=tools
)
call = first.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)
# Run the function, then return its result with the call id.
result = {
"number": args["number"],
"status": "paid",
"paid_on": "2026-10-02",
}
messages.append(first.choices[0].message)
messages.append(
{
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
}
)
final = client.chat.completions.create(
model="flash", messages=messages, tools=tools
)
print(final.choices[0].message.content)const tools = [
{
type: "function",
function: {
name: "invoice_status",
description: "Payment status of an invoice.",
parameters: {
type: "object",
properties: { number: { type: "string" } },
required: ["number"],
},
},
},
]
const messages = [
{ role: "user", content: "Has invoice 2026-114 been paid?" },
]
const first = await client.chat.completions.create({
model: "flash",
messages,
tools,
})
const call = first.choices[0].message.tool_calls[0]
const args = JSON.parse(call.function.arguments)
// Run the function, then return its result with the call id.
const result = {
number: args.number,
status: "paid",
paid_on: "2026-10-02",
}
messages.push(first.choices[0].message)
messages.push({
role: "tool",
tool_call_id: call.id,
content: JSON.stringify(result),
})
const final = await client.chat.completions.create({
model: "flash",
messages,
tools,
})
console.log(final.choices[0].message.content)import type {
ChatCompletionMessageParam,
ChatCompletionTool,
} from "openai/resources"
const tools: ChatCompletionTool[] = [
{
type: "function",
function: {
name: "invoice_status",
description: "Payment status of an invoice.",
parameters: {
type: "object",
properties: { number: { type: "string" } },
required: ["number"],
},
},
},
]
const messages: ChatCompletionMessageParam[] = [
{ role: "user", content: "Has invoice 2026-114 been paid?" },
]
const first = await client.chat.completions.create({
model: "flash",
messages,
tools,
})
const call = first.choices[0].message.tool_calls?.[0]
if (call?.type !== "function")
throw new Error("no function call")
const args = JSON.parse(call.function.arguments) as {
number: string
}
// Run the function, then return its result with the call id.
const result = {
number: args.number,
status: "paid",
paid_on: "2026-10-02",
}
messages.push(first.choices[0].message)
messages.push({
role: "tool",
tool_call_id: call.id,
content: JSON.stringify(result),
})
const final = await client.chat.completions.create({
model: "flash",
messages,
tools,
})
console.log(final.choices[0].message.content)Resposta
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_7f3a",
"type": "function",
"function": { "name": "invoice_status", "arguments": "{\"number\": \"2026-114\"}" }
}
]
}Bom saber
- Uma lista de ferramentas vazia é removida juntamente com tool_choice, como se não tivesses enviado nenhuma.
- parallel_tool_calls permite ao modelo pedir várias funções de uma vez.
- Verifica os argumentos antes de agir. O modelo pode enganar-se, o teu código decide.