Funções personalizadas (chamada de funções)
Nesta página
Ligue o Grok aos seus próprios serviços
As ferramentas de servidor (web_search, x_search, code_interpreter) são úteis, mas limitadas aos serviços da xAI. Com ferramentas personalizadas do tipo function, pode ligar o Grok a qualquer API ou serviço na sua infraestrutura.
Como funciona
A chamada de funções segue um ciclo de três passos:
- Declaração: Descreve as suas funções (nome, descrição, parâmetros) no pedido.
- Chamada: O modelo gera uma chamada de função com os argumentos apropriados e pausa a geração.
- Resultado: O seu código executa a função e, em seguida, envia o resultado de volta ao modelo para que este possa formular a sua resposta.
Declarar uma função
{
"model": "grok-4.20-0309-reasoning",
"input": "Book me a table for 2 people tonight at 8 PM.",
"tools": [{
"type": "function",
"name": "book_restaurant",
"description": "Books a table at a restaurant",
"parameters": {
"type": "object",
"properties": {
"restaurant_name": {
"type": "string",
"description": "Restaurant name"
},
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format"
},
"time": {
"type": "string",
"description": "Time in HH:MM format"
},
"guests": {
"type": "integer",
"description": "Number of guests"
}
},
"required": ["date", "time", "guests"]
}
}]
}
A descrição de cada função e parâmetro é crucial. O modelo utiliza-as para decidir quando chamar a função e como preencher os argumentos.
Receber a chamada de função
Quando o modelo decide chamar a sua função, a resposta contém um item function_call:
{
"id": "resp-xyz789",
"status": "completed",
"output": [{
"type": "function_call",
"name": "book_restaurant",
"arguments": "{\"date\": \"2026-04-03\", \"time\": \"20:00\", \"guests\": 2}",
"call_id": "call-abc123"
}]
}
O campo arguments é uma cadeia JSON que deve analisar (parse). O call_id identifica esta chamada específica.
Devolver o resultado
Após executar a função no seu código, devolva o resultado:
import json
# 1. Pedido inicial
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What's the weather like in Paris?",
tools=[{
"type": "function",
"name": "get_weather",
"description": "Retrieves current weather",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}]
)
# 2. Verificar se o modelo quer chamar uma função
for item in response.output:
if item.type == "function_call":
args = json.loads(item.arguments)
# 3. Executar a sua função
weather_data = get_weather_from_api(args["city"])
# 4. Devolver o resultado ao modelo
final = client.responses.create(
model="grok-4.20-0309-reasoning",
input=[{
"type": "function_call_output",
"call_id": item.call_id,
"output": json.dumps(weather_data)
}],
previous_response_id=response.id
)
print(final.output[0].content[0].text)
Melhores práticas para descrições
O modelo depende das descrições para compreender as suas funções. Seja preciso:
{
"name": "search_products",
"description": "Searches for products in the e-commerce catalog. Returns the top 10 results sorted by relevance. Supports search by name, category, or price range.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search terms (product name, brand, keyword)"
},
"category": {
"type": "string",
"enum": ["electronics", "clothing", "home", "sports"],
"description": "Product category to filter"
},
"max_price": {
"type": "number",
"description": "Maximum price in euros"
}
},
"required": ["query"]
}
}
Utilize enum para valores predefinidos, uma description detalhada para cada parâmetro e marque apenas os parâmetros essenciais como required.
Gestão de erros
Se a sua função falhar, devolva o erro como resultado:
try:
result = call_external_api(args)
output = json.dumps(result)
except Exception as e:
output = json.dumps({"error": str(e)})
final = client.responses.create(
model="grok-4.20-0309-reasoning",
input=[{
"type": "function_call_output",
"call_id": call_id,
"output": output
}],
previous_response_id=response.id
)
O modelo interpreta o erro e pode reformular a sua resposta ou tentar uma abordagem diferente.
Pontos-chave
- As funções personalizadas ligam o Grok aos seus próprios serviços.
- O ciclo é: declarar, receber a chamada, executar e devolver o resultado.
- As descrições das funções e dos parâmetros orientam a escolha do modelo.
- O campo
argumentsé uma cadeia JSON a analisar no lado do cliente. - Devolva os erros como resultados para que o modelo se possa adaptar.