Strumenti per le funzioni del client

Se hai funzionalità accessibili dal codice client, ma non dagli strumenti ospitati, come OpenAPI o MCP, puoi utilizzare gli strumenti per le funzioni client. Gli strumenti delle funzioni client vengono sempre eseguiti sul lato client, non dall'agente.

Come funziona

Quando un agente attiva uno strumento di funzione client:

  1. Blocco della sessione: la sessione di conversazione viene effettivamente "bloccata" sul lato server.
  2. Esecuzione del client: la tua applicazione client deve identificare la chiamata allo strumento ed eseguire la logica corrispondente nel tuo ambiente locale.
  3. Fornire la risposta: una volta completata l'esecuzione, l'applicazione client deve fornire la risposta all'agente utilizzando i campi toolResponses.

L'agente attende questa risposta prima di procedere con la conversazione.

Configurazione

Quando crei uno strumento di funzione client, definisci il modo in cui l'agente comprende e interagisce con il tuo codice lato client:

  • Nome: un identificatore univoco per lo strumento (ad esempio: open_settings).
  • Descrizione: una breve descrizione dello scopo dello strumento. I modelli di agenti utilizzano questa descrizione per decidere quando chiamare la funzione.
  • Schema di input/output: definito in formato OpenAPI. Questo determina la struttura dei dati che l'agente invia e si aspetta di ricevere.

Casi d'uso

Gli strumenti per le funzioni client sono ideali per:

  • Azioni UI/UX: attivazione di modifiche nell'interfaccia dell'applicazione (ad esempio, "Vai alla schermata di assistenza").
  • Dati del dispositivo locale: accesso a informazioni disponibili solo nel contesto dell'app (ad esempio "Ottieni il livello attuale della batteria").
  • API private: integrazione con servizi raggiungibili solo dall'ambiente lato client.

Esempio

L'esempio seguente è una risposta di sessione che indica che l'applicazione client deve chiamare una funzione:

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

L'esempio seguente è una sessione successiva eseguita con l'output dello strumento allegato alla richiesta. L'applicazione client deve compilare questi campi e inserire gli stessi valori di id, tool e display_name del messaggio precedente.

"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"
          },
        }
      ]
    }
  }
]