Function Calling

Function calling funciona como uma camada de tradução entre linguagem natural e interfaces de software. A aplicação informa ao modelo um catálogo de ferramentas com nomes, descrições e parâmetros, frequentemente expressos em JSON Schema. Diante de um pedido, o modelo pode produzir uma chamada estruturada, como `set_light_brightness(room="sala", percent=30)`. A aplicação não deve executar automaticamente: primeiro valida schema, resolve IDs, verifica identidade, permissão, estado, faixa e necessidade de confirmação. Depois executa a API real e devolve o resultado. O modelo usa esse retorno para responder. O mecanismo melhora interoperabilidade com hubs, bancos e serviços, mas permanece probabilístico. Não é RPC confiável por si, nem substitui autorização, transação, idempotência ou tratamento de falhas.

• A definição da ferramenta é um contrato. Nome e descrição precisam ser inequívocos. Parâmetros usam tipos, enums, limites, campos obrigatórios e formatos. Em vez de uma ferramenta genérica `run_command`, preferem-se funções específicas, como `get_device_state`, `set_light_level` e `create_scene`, com escopo reduzido. Isso diminui interpretações perigosas. O schema ainda não garante semântica: um valor 23 pode ser temperatura em °C ou ID. Unidades devem estar explícitas. IDs internos são resolvidos pela aplicação. O modelo pode receber candidatos autorizados, mas não toda a infraestrutura. Ferramentas versionadas evitam quebra. Mudanças de assinatura exigem testes. A descrição não deve conter segredos ou regras que só existam em texto.
• A seleção da ferramenta é uma sugestão do modelo, não uma decisão de acesso. Um usuário visitante pode pedir “destranque a porta”; o modelo pode produzir a função correta, mas o policy engine deve negar. RBAC, ABAC, autenticação, horário, presença e confirmação são avaliados fora. Ferramentas críticas podem exigir dois passos: `prepare_unlock` gera desafio; a UI confirma por biometria; somente então `execute_unlock` recebe token curto. O modelo nunca vê a credencial. Para iluminação, risco é menor e política pode permitir. O sistema classifica ações. Uma ferramenta de consulta não deve ganhar permissão de escrita. A conta de serviço usa menor privilégio. A autorização é reavaliada no momento da execução.
• Validação e normalização são obrigatórias. Structured output reduz JSON inválido, mas argumentos podem ser incorretos. O backend verifica enum, tipo, faixa, comprimento, pattern, unidade e existência. Evita injeção em SQL, shell, URL e caminho. Não concatena. Um parâmetro `url` não pode acessar metadados internos sem allowlist. Um horário é convertido com timezone. Um brilho é limitado 0–100%. Se há ambiguidade entre duas “luzes da sala”, a chamada é suspensa e o modelo pede esclarecimento. Correções automáticas devem ser transparentes. O retorno de erro é estruturado, sem stack trace ou segredo. O modelo pode explicar, mas não mascarar. A ferramenta registra ID de correlação.
• Idempotência e estado evitam efeitos duplicados. Modelos podem repetir chamadas após timeout. Para ações como criar rotina, comprar serviço ou abrir portão, o backend usa chave de idempotência e estado. `set_light(30%)` é naturalmente mais idempotente que `toggle_light`, porque toggle repetido reverte. Prefira operações declarativas. A função verifica precondições e versão do recurso. Para cenas, uma transação pode falhar parcialmente; o resultado lista cada dispositivo. O modelo não deve afirmar sucesso global. Retentativas usam backoff e somente em erros seguros. A aplicação diferencia timeout de falha. Uma chamada de destravamento não é repetida cegamente. Logs correlacionam pedido, decisão, execução e confirmação física.
• A resposta da ferramenta precisa ser pequena, estruturada e confiável. Ela contém estado, unidade, timestamp, fonte e erros. O modelo não deve receber páginas de log sem filtragem. Para uma consulta de energia, a ferramenta calcula agregados e retorna tabela. Para documentos, a busca retorna trechos e citações. O prompt instrui a usar o resultado. Mesmo assim, a resposta final pode distorcer. Para valores críticos, a UI pode renderizar dados diretamente e usar o modelo apenas para explicação. O resultado da ferramenta é tratado como dado não confiável se vem de fonte externa; pode conter prompt injection. Campos de texto são delimitados. O orquestrador impede que uma mensagem de dispositivo altere políticas.
• Function calling também permite orquestração em múltiplas etapas. O modelo consulta estado, decide que precisa de outra informação e chama nova ferramenta. Isso se aproxima de agente. Limites são necessários: máximo de chamadas, tempo, custo, profundidade e ferramentas. Um pedido não pode entrar em loop. O sistema pode exigir plano e aprovação antes de ações. Paralelismo é permitido para consultas independentes, mas escrita concorrente precisa de controle. A observabilidade registra cada etapa, modelo, prompt, versão do schema, latência e resultado. Avaliação testa escolha correta, argumentos, erros e ataques. O mecanismo deve ter fallback manual. Se o modelo está indisponível, automações determinísticas continuam.