Ferramentas de função do cliente

Se você tiver funcionalidades acessíveis pelo código do cliente, mas não por ferramentas hospedadas, como OpenAPI ou MCP use as ferramentas de função do cliente. Elas 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. Bloco de sessão: a sessão de conversa é "bloqueada" no lado do servidor.
2. Execução do cliente: o aplicativo cliente precisa identificar a chamada de ferramenta e executar a lógica correspondente no ambiente local.
3. Fornecimento de resposta: quando a execução for concluída, o aplicativo cliente precisará enviar a resposta de volta ao agente usando os toolResponses campos.

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 o 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 interface/experiência do usuário: acionar mudanças na interface do aplicativo (por exemplo, "Navegar até a tela de suporte").
• Dados do dispositivo local: acessar informações que só estão disponíveis no contexto do app (por exemplo, "Receber o nível atual da bateria").
• APIs privadas: integrar 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"
          },
        }
      ]
    }
  }
]