Limites e Melhores Práticas
Nesta página
Restrições técnicas da chamada de funções
Antes de começar a implementar, precisa de compreender os limites do sistema. A chamada de funções do Grok é poderosa, mas opera dentro de restrições específicas que deve dominar para construir aplicações robustas.
Máximo de 200 ferramentas por pedido
A API do Grok aceita até 200 definições de ferramentas num único pedido. Este limite é generoso — a maioria das aplicações utiliza apenas 5 a 20. No entanto, se construir um sistema escalável (plugins, mercado de ferramentas), tem de ter isto em conta.
Cada definição de ferramenta ocupa espaço na janela de contexto. Especificamente:
- Uma ferramenta simples (2-3 parâmetros) consome cerca de 50-100 tokens
- Uma ferramenta complexa (10+ parâmetros, descrições detalhadas) pode exceder 300 tokens
- 200 ferramentas complexas = 60.000 tokens apenas para definições
É por isso que precisa de ser estratégico: declare apenas as ferramentas relevantes para o pedido atual.
O modelo não garante a validade dos argumentos
O Grok faz o seu melhor para gerar argumentos que correspondam ao esquema, mas não é infalível. O modelo pode:
- Gerar um formato de data incorreto
- Passar uma
stringonde se espera uminteger - Omitir um campo obrigatório em casos raros
- Alucinar valores de enumeração que não existem
O seu código do lado do cliente deve validar sempre os argumentos recebidos antes de executar a função.
import json
def handle_tool_call(tool_call):
args = json.loads(tool_call.function.arguments)
# Validate before execution
if "city" not in args:
return {"error": "The city parameter is required"}
if not isinstance(args["city"], str):
return {"error": "city must be a string"}
return get_weather(args["city"], args.get("unit", "celsius"))
Gestão de erros
Quando uma função falha, deve devolver o erro ao modelo em vez de falhar silenciosamente. O modelo pode então:
- Reformular o seu pedido com parâmetros corrigidos
- Informar o utilizador sobre o problema
- Tentar uma ferramenta alternativa
try:
result = search_database(query=args["query"])
return json.dumps(result)
except ConnectionError:
return json.dumps({
"error": "Database unavailable",
"suggestion": "Retry in a few seconds"
})
Devolver sempre JSON estruturado, mesmo em caso de erro. O modelo compreende mensagens de erro e adapta a sua resposta em conformidade.
Nomes únicos e explícitos
Os nomes das funções devem ser únicos na lista de ferramentas. Se duas ferramentas partilharem o mesmo nome, o comportamento é indefinido — a API pode rejeitar o pedido ou ignorar uma delas.
Adote uma convenção de nomenclatura consistente:
✅ Melhores práticas:
get_weather → recuperação de dados
search_products → pesquisa
create_ticket → criação
update_order_status → atualização
delete_draft → eliminação
❌ A evitar:
fn1, fn2 → incompreensível
doStuff → demasiado vago
getWeatherData → camelCase (prefira snake_case)
Descrições: o fator de qualidade nº 1
A qualidade da descrição determina diretamente a fiabilidade da chamada de funções. Eis uma tabela comparativa:
| Descrição fraca | Descrição eficaz |
|---|---|
| "Search" | "Search for products by name, category, or price range in the e-commerce catalog" |
| "Send message" | "Send an email to a recipient. Requires a subject and message body. Does not support attachments." |
| "Calculate" | "Calculate the total price including tax from a pre-tax price and a VAT rate. Returns the amount in euros with 2 decimal places." |
Otimização do número de ferramentas
Em vez de declarar 200 ferramentas em cada pedido, selecione dinamicamente as que realmente importam. O primeiro filtro é o contexto: se o utilizador falar sobre meteorologia, carregar ferramentas de faturação apenas adiciona ruído — um encaminhamento leve a montante (por palavras-chave ou uma primeira chamada de classificação) é suficiente para apresentar apenas a família relevante. O segundo filtro é a função: um agente de suporte não precisa de ferramentas de administrador, e removê-las é uma questão de precisão tanto quanto de segurança. O terceiro é a etapa: num fluxo de trabalho multifase, cada fase tem as suas próprias ferramentas — carregá-las à medida que avança mantém o modelo focado no que precisa de fazer agora.
O benefício é duplo e imediato: menos tokens de entrada por pedido (as definições de ferramentas têm um custo em cada chamada) e melhor precisão na seleção — um modelo que escolhe entre seis ferramentas bem descritas raramente comete um erro, enquanto o mesmo modelo perante duzentas definições acaba por confundir variantes próximas.
Segurança: nunca confie no modelo
A chamada de funções é um vetor potencial de injeção. Um utilizador mal-intencionado poderia formular o seu pedido para manipular os argumentos passados às funções. Regras de segurança:
- Valide todos os argumentos no lado do servidor
- Limite as permissões: uma função de leitura não deve poder escrever
- Registe as chamadas: rastreie cada chamada de função para auditoria
- Limpe os inputs: escape caracteres especiais antes de consultas SQL/shell
Pontos-chave
- Máximo de 200 ferramentas por pedido — mas aponte para 5-20 para eficiência
- Valide sempre os argumentos no lado do cliente antes da execução
- Devolva erros ao modelo em JSON estruturado
- Os nomes devem ser únicos, em snake_case e explícitos
- Descrições detalhadas melhoram drasticamente a fiabilidade
- Selecione dinamicamente as ferramentas relevantes para cada pedido
- Nunca confie nos argumentos sem validação