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

Limites e Melhores Práticas

Aula 3 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Restrições técnicas da chamada de funções
  2. Máximo de 200 ferramentas por pedido
  3. O modelo não garante a validade dos argumentos
  4. Gestão de erros
  5. Nomes únicos e explícitos
  6. Descrições: o fator de qualidade nº 1
  7. Otimização do número de ferramentas
  8. Segurança: nunca confie no modelo
  9. Pontos-chave

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 string onde se espera um integer
  • 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