Herramientas de funciones del cliente

Si tienes funciones a las que se puede acceder con tu código de cliente, pero no con herramientas alojadas, como OpenAPI o MCP, puedes usar herramientas de funciones del cliente. Las herramientas de funciones del cliente siempre se ejecutan en el cliente, no en el agente.

Cómo funciona

Cuando un agente activa una herramienta de función del cliente, sucede lo siguiente:

1. Bloqueo de sesión: La sesión de conversación se "bloquea" de manera efectiva en el servidor.
2. Ejecución del cliente: Tu aplicación cliente debe identificar la llamada a la herramienta y ejecutar la lógica correspondiente en tu entorno local.
3. Proporciona una respuesta: Una vez que se complete la ejecución, tu aplicación cliente debe proporcionar la respuesta al agente con los campos toolResponses.

El agente espera esta respuesta antes de continuar con la conversación.

Configuración

Cuando creas una herramienta de función del cliente, defines cómo el agente comprende tu código del cliente y cómo interactúa con él:

• Nombre: Es un identificador único para la herramienta (por ejemplo, open_settings).
• Descripción: Es una breve descripción del propósito de la herramienta. Los modelos de agentes usan esta descripción para decidir cuándo llamar a la función.
• Esquema de entrada y salida: Se define en formato OpenAPI. Esto determina la estructura de los datos que el agente envía y espera recibir.

Casos de uso

Las herramientas de funciones del cliente son ideales para lo siguiente:

• Acciones de UX/IU: Desencadenan cambios en la interfaz de tu aplicación (por ejemplo, "Navegar a la pantalla de asistencia").
• Datos locales del dispositivo: Acceder a información que solo está disponible en el contexto de la app (por ejemplo, "Obtener el nivel de batería actual")
• APIs privadas: Integración con servicios a los que solo se puede acceder desde el entorno del cliente

Ejemplo

El siguiente ejemplo es una respuesta de sesión que indica que la aplicación cliente debe llamar a una función:

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

El siguiente ejemplo es una ejecución de sesión posterior con el resultado de la herramienta adjunto a la solicitud. La aplicación cliente debe completar esos campos y colocar los mismos valores de id, tool y display_name que en el mensaje 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"
          },
        }
      ]
    }
  }
]