Adicionando ferramentas

Um modelo de linguagem pode escrever “Eu criei um ticket de suporte” sem criar nada. A geração de texto e as alterações em um sistema de negócio são atividades separadas. Uma ferramenta é uma operação que o agente pode solicitar através da aplicação circundante, como consultar um pedido, criar um ticket ou enviar um e‑mail. Ferramentas dão ao assistente uma conexão controlada para trabalhar além do texto da resposta.

Pense em um recepcionista que pode pedir ao sistema de reservas que encontre compromissos. Saber como discutir compromissos não é o mesmo que ter acesso ao calendário. As operações disponíveis, os detalhes necessários e as permissões determinam o que o recepcionista pode realmente realizar. Um agente precisa da mesma separação entre a capacidade de linguagem e a autoridade operacional.

A tool is a defined capability #

Uma ferramenta normalmente tem um nome, uma descrição e uma definição das informações que aceita. Essa informação é chamada de argumentos. Uma consulta de pedido pode precisar de uma referência que identifique o pedido; uma operação de criação de ticket pode precisar de um assunto e uma descrição. A definição dos campos aceitos e seus tipos costuma ser chamada de esquema.

Uma descrição clara ajuda o modelo a decidir quando uma ferramenta é apropriada. “Consultar o status de entrega de um pedido ao qual o usuário tem permissão de acesso” é mais útil do que “Gerenciar pedidos”. A descrição mais restrita facilita a compreensão do resultado esperado e dos limites. Também facilita para a aplicação rejeitar solicitações que não se encaixam na operação.

Read-only significa que uma operação tem a intenção de recuperar informações sem modificá‑las. Não significa inofensivo: ler os registros do cliente errado ainda pode divulgar dados privados. Uma write operation altera algo. Separar essas categorias ajuda a decidir quais ferramentas expor primeiro e quais precisam de verificações adicionais ou confirmação humana.

The model requests; the platform executes #

No padrão de chamada de ferramenta descrito aqui, o modelo nunca executa o código solicitado. Ele gera uma solicitação que identifica a operação e seus argumentos. A plataforma ou aplicação recebe essa solicitação, verifica‑a, executa o software adequado e devolve um resultado. Se uma ferramenta que executa código for fornecida, o código roda no ambiente de execução dessa ferramenta, não dentro da geração de texto do modelo de linguagem.

Essa divisão é importante porque o modelo pode cometer erros. Ele pode selecionar a operação errada, omitir um campo obrigatório ou confundir uma referência fornecida pelo cliente com uma verificada. A aplicação deve tratar a solicitação como entrada proposta para validação, não como uma instrução que sobrescreve automaticamente as regras de acesso.

sequenceDiagram
    participant User as Customer
    participant Model as Model
    participant App as Application
    participant System as Order system
    User->>Model: Ask about delivery
    Model->>App: Request order lookup
    App->>App: Check access and arguments
    App->>System: Read permitted order
    System-->>App: Return recorded status
    App-->>Model: Return tool result
    Model-->>User: Explain confirmed status

O diagrama mostra o caminho bem‑sucedido. Se a verificação de permissão falhar, a aplicação não deve contatar o sistema de pedidos para uma leitura não autorizada. Se o sistema de pedidos estiver indisponível, o assistente deve explicar que não pôde verificar o status. Caminhos de falha pertencem ao design, não apenas a uma mensagem de erro descoberta após o lançamento.

Read the conversation as evidence #

Agora imagine que a ferramenta retorne “Serviço indisponível”. Uma resposta adequada diria que o status não pôde ser verificado, não que a encomenda provavelmente está a caminho. Se o sistema retornar “Submissão pendente”, a resposta deve preservar esse estado. Os usuários confiam nessas distinções ao decidir se ainda precisam agir.

Permissions belong outside the conversation #

Authentication estabelece quem está fazendo a solicitação. Authorisation determina o que essa identidade tem permissão para fazer. O executor da ferramenta precisa de ambos quando a operação depende de acesso a uma conta ou registro. Um usuário digitando “Eu sou o gerente” não é um mecanismo de autenticação, e uma instrução dizendo “Ajudar apenas usuários autorizados” não implementa autorização.

Para um assistente de entregas, a aplicação pode limitar as consultas a pedidos pertencentes à sessão verificada. Ela pode expor uma operação de revisão sem expor aprovação ilimitada de reembolso. Isso segue o princípio de least privilege: fornecer apenas o acesso necessário para o trabalho. O modelo não deve receber poderes amplos apenas porque uma operação restrita é inconveniente de projetar.

Antes de uma ação consequente, esclareça exatamente o que o usuário deseja e o que será alterado. Uma mensagem pedindo informação não é permissão para enviar um e‑mail ou cancelar um pedido. A confirmação humana deve identificar a ação e o alvo, enquanto a aplicação ainda impõe acesso e validade. Authentication and permissions desenvolve esses controles com mais detalhes.

Handle failures without making them worse #

Uma resposta lenta pode deixar o resultado incerto. Se o envio de um e‑mail expirar, ele pode já ter sido enviado. Repetir automaticamente uma operação de escrita pode, portanto, criar mensagens ou registros duplicados. O software circundante precisa de um meio de verificar o status ou reconhecer uma solicitação repetida antes de tentar novamente. O modelo não deve inferir que silêncio significa que nada aconteceu.

Comece com um pequeno conjunto de ferramentas bem definidas e teste campos ausentes, acesso rejeitado, serviços indisponíveis e resultados incompletos. Um catálogo de ferramentas não é medida da qualidade do agente. Operações sobrepostas ou vagas criam mais oportunidades para o modelo escolher incorretamente. Adicione uma capacidade quando ela resolver uma tarefa específica e seu comportamento de falha for compreendido.

Related: Function calling explica a troca estruturada por trás das solicitações de ferramenta. No AIVAX, built-in tools fornecem capacidades mantidas, enquanto protocol functions conectam ações solicitadas pelo modelo a callbacks que você fornece.

What’s next: Ferramentas fornecem ações; Adding skills explica como empacotar o método para usá‑las bem.