Client function tools

If you have functionality accessible by your client code, but not accessible by hosted tools, such as OpenAPI or MCP you can use client function tools. Client function tools are always executed on the client side, not by the agent.

How it works

When an agent triggers a client function tool:

1. Session Block: The conversation session is effectively "blocked" on the server side.
2. Client Execution: Your client application must identify the tool call and execute the corresponding logic in your local environment.
3. Providing Response: Once the execution is complete, your client application must provide the response back to the agent using the toolResponses fields.

The agent waits for this response before proceeding with the conversation.

Configuration

When creating a client function tool, you define how the agent understands and interacts with your client-side code:

• Name: A unique identifier for the tool (for example: open_settings).
• Description: A brief description of the tool's purpose. Agent models use this description to decide when to call the function.
• Input/Output Schema: Defined in OpenAPI format. This determines the structure of the data the agent sends and expects to receive.

Use cases

Client function tools are ideal for:

• UI/UX Actions: Triggering changes in your application's interface (for example, "Navigate to the support screen").
• Local Device Data: Accessing information that is only available within the app's context (for example, "Get current battery level").
• Private APIs: Integrating with services that are only reachable from the client-side environment.

Example

The following example is a session response indicating that the client application should call a function:

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

And the following example is a subsequent session run with the tool output attached to the request. The client application must populate those fields, and put the same id, tool, and display_name values as in the previous message.

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