Herramientas de funciones del cliente

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

Cómo funciona

Cuando un agente activa una herramienta de función de 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. Proporcionar respuesta: Una vez que se complete la ejecución, tu cliente aplicación debe proporcionar la respuesta al agente con los toolResponses campos.

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

Configuración

Cuando creas una herramienta de función de 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/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 de cliente son ideales para lo siguiente:

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

Ejemplo

En el siguiente ejemplo, se muestra 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,
  }
]

En el siguiente ejemplo, se muestra una ejecución de sesión posterior con el resultado de la herramienta adjunto a la solicitud. La aplicación cliente debe propagar esos campos y colocar los mismos valores 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"
          },
        }
      ]
    }
  }
]