Ferramentas de função do cliente

Se você tiver uma funcionalidade acessível pelo código do cliente, mas não pelas ferramentas hospedadas, como OpenAPI ou MCP, use as ferramentas de função do cliente. As ferramentas de função do cliente são sempre executadas no lado do cliente, não pelo agente.

Como funciona

Quando um agente aciona uma ferramenta de função do cliente:

1. Bloqueio de sessão: a sessão de conversa é efetivamente "bloqueada" no lado do servidor.
2. Execução do cliente: seu aplicativo cliente precisa identificar a chamada de função e executar a lógica correspondente no seu ambiente local.
3. Fornecer resposta: quando a execução for concluída, o aplicativo cliente precisa fornecer a resposta ao agente usando os campos toolResponses.

O agente aguarda essa resposta antes de continuar a conversa.

Configuração

Ao criar uma ferramenta de função do cliente, você define como o agente entende e interage com seu código do lado do cliente:

• Nome: um identificador exclusivo da ferramenta (por exemplo, open_settings).
• Descrição: uma breve descrição da finalidade da ferramenta. Os modelos de agente usam essa descrição para decidir quando chamar a função.
• Esquema de entrada/saída: definido no formato OpenAPI. Isso determina a estrutura dos dados que o agente envia e espera receber.

Casos de uso

As ferramentas de função do cliente são ideais para:

• Ações de UI/UX: acionam mudanças na interface do aplicativo (por exemplo, "Navegar até a tela de suporte").
• Dados locais do dispositivo: acesso a informações disponíveis apenas no contexto do app (por exemplo, "Verificar nível atual da bateria").
• APIs particulares: integração com serviços que só podem ser acessados no ambiente do lado do cliente.

Exemplo

O exemplo a seguir é uma resposta de sessão que indica que o aplicativo cliente precisa chamar uma função:

"outputs": [
  {
    "toolCalls": {
      "toolCalls": [
        {
          "id": "<execution id>",
          "tool": "<client function tool's resource name>",
          "args": {
            "zip_code": "92031"
          },
          "displayName": "get_nearest_store"
        }
      ]
    },
    "turnCompleted": true,
  }
]

O exemplo a seguir é uma execução de sessão subsequente com a saída da ferramenta anexada à solicitação. O aplicativo cliente precisa preencher esses campos e inserir os mesmos valores de id, tool e display_name da mensagem anterior.

"inputs": [
  {
    "toolResponses": {
      "toolResponses": [
        {
          "displayName": "get_nearest_store",
          "id": "<execution id>",
          "tool": "<client function tool's resource name>",
          "response": {
            "name": "Alibaba",
            "address": "43 Alpha Road, Mountain View, CA 92039, USA"
          },
        }
      ]
    }
  }
]