Add tools to the character

Tool calling lets the character use your application’s capabilities. The model requests an operation; your application validates it, executes it, and returns the result.

1. Define an available operation

change_outfit is an application-defined function. This example offers a pink skirt and a floral dress. Add the definition to conversation.tools in the session request.

{
  "conversation": {
    "tools": [
      {
        "type": "function",
        "name": "change_outfit",
        "description": "Switch to a prepared outfit image when the viewer explicitly requests an available outfit. Ask which outfit they mean if the choice is unclear. Do not switch after a casual mention or a request not to change.",
        "parameters": {
          "type": "object",
          "properties": {
            "outfit": {
              "type": "string",
              "enum": [
                "pink_skirt",
                "floral_dress"
              ]
            }
          },
          "required": [
            "outfit"
          ],
          "additionalProperties": false
        }
      }
    ]
  }
}

2. Receive and execute the call

Handle the function_call in response.output_item.done. Parse arguments as a JSON string, validate the tool name and allowed values, then execute your business function. Deduplicate by session ID and call_id.

{
  "type": "response.output_item.done",
  "response_id": "resp_outfit_01",
  "output_index": 0,
  "item": {
    "type": "function_call",
    "name": "change_outfit",
    "call_id": "call_outfit_01",
    "arguments": "{\"outfit\":\"floral_dress\"}"
  }
}

For this example, map the outfit to a registered image and call the image-change API. See Change the image for registration and update steps. Tool calling does not execute the business operation automatically.

3. Return the actual result

Return a string result as function_call_output using the original call_id. For image changes, wait for the corresponding session.update.done status; session.updated only confirms acceptance. Return failures, cancellations, and unconfirmed timeouts as such.

{
  "event_id": "tool_result_01",
  "type": "conversation.item.create",
  "item": {
    "id": "outfit_result_01",
    "type": "function_call_output",
    "call_id": "call_outfit_01",
    "output": "{\"status\":\"completed\",\"outfit\":\"floral_dress\",\"source_image_id\":\"look_floral_dress\"}"
  }
}

4. Continue the reply

Wait for the original response.done and the matching conversation.item.created acknowledgement for every tool result in that response, then send response.create once. Track continuation by response_id rather than continuing after each tool.

{
  "event_id": "continue_outfit_01",
  "type": "response.create",
  "response": {
    "scheduling_policy": "after_current_response"
  }
}

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation

1. Define an available operation

2. Receive and execute the call

3. Return the actual result

4. Continue the reply