Tool Calling

Process a tool calling request.

POST /api/ai/v1/messages/tools

cURL

Initial Tool Call

curl --request POST \
  --url https://{subdomain}.domo.com/api/ai/v1/messages/tools \
  --header 'Content-Type: application/json' \
  --header 'X-DOMO-Developer-Token: <api-key>' \
  --data '
{
  "input": [
    {
      "role": "USER",
      "content": [
        {
          "type": "TEXT",
          "text": "Do you have any blue coats available?"
        }
      ]
    }
  ],
  "tools": [
    {
      "name": "get_product_recommendations",
      "description": "Searches for products matching certain criteria in the database",
      "parameters": {
        "type": "object",
        "properties": {
          "categories": {
            "description": "categories that could be a match",
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "coats & jackets",
                "accessories",
                "tops",
                "jeans & trousers",
                "skirts & dresses",
                "shoes"
              ]
            }
          },
          "colors": {
            "description": "colors that could be a match, empty array if N/A",
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "black",
                "white",
                "brown",
                "red",
                "blue",
                "green",
                "orange",
                "yellow",
                "pink",
                "gold",
                "silver"
              ]
            }
          },
          "keywords": {
            "description": "keywords that should be present in the item title or description",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "price_range": {
            "type": "object",
            "properties": {
              "min": {
                "type": "number",
                "minimum": 100
              },
              "max": {
                "type": "number",
                "maximum": 200
              }
            },
            "required": [
              "min",
              "max"
            ],
            "additionalProperties": false
          },
          "limit": {
            "type": "integer",
            "description": "The maximum number of products to return, use 5 by default if nothing is specified by the user",
            "const": 100
          },
          "today": {
            "type": "string",
            "format": "date-time",
            "description": "todays date"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "confirmation email"
          },
          "phone": {
            "type": "string",
            "description": "user phone number"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "categories",
          "colors",
          "keywords",
          "price_range",
          "limit",
          "today",
          "id"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "get_product_details",
      "description": "Fetches more details about a product",
      "parameters": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string",
            "description": "The ID of the product to fetch details for"
          }
        },
        "required": [
          "product_id"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "add_to_cart",
      "description": "Add items to cart when the user has confirmed their interest.",
      "parameters": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "product_id": {
                  "type": "string",
                  "description": "ID of the product to add to the cart"
                },
                "quantity": {
                  "type": "integer",
                  "description": "Quantity of the product to add to the cart"
                }
              },
              "required": [
                "product_id",
                "quantity"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "items"
        ],
        "additionalProperties": false
      }
    }
  ],
  "toolChoice": {
    "type": "AUTO"
  }
}
'

200

Tool Calling Response

{
  "content": [
    {
      "type": "TEXT",
      "text": "Certainly! I'd be happy to help you find a blue coat. I'll use the product recommendation tool to search for that."
    },
    {
      "type": "TOOL_USE_REQUEST",
      "toolInput": {
        "categories": [
          "coats & jackets"
        ],
        "colors": [
          "blue"
        ],
        "keywords": [
          "coat"
        ],
        "price_range": {
          "min": 100,
          "max": 200
        },
        "limit": 5,
        "today": "2023-06-10T12:00:00.000Z",
        "id": "550e8400-e29b-41d4-a716-446655440000"
      },
      "name": "get_product_recommendations",
      "toolCallId": "toolu_bdrk_01Tnc9RttRWSwvKHd5JA1sRk"
    }
  ],
  "modelId": "domo.domo_ai.domogpt-medium-v1.2:anthropic",
  "isCustomerModel": false,
  "sessionId": "526bb9ee-02d0-4717-a83d-946715b5fa82",
  "requestId": "c765dc33-9f3e-4f23-84e5-cf7aa2cd3f63",
  "stopReason": "TOOL_USE"
}

Authorizations

X-DOMO-Developer-Token · string · header · required

Body

application/json

Request for making tool calls using AI.

input · object[]

The list of input messages to be processed by the AI.

Show child attributes

sessionId · string<uuid>

The unique identifier for the AI session associated with this request.

system · object[]

System-level messages or configurations to guide the AI's response.

Show child attributes

model · string

The identifier of the AI model to be used for generating a response.

modelConfiguration · object

Specific parameters or settings that configure the AI model behavior.

Show child attributes

temperature · number<double>

A parameter for controlling the randomness of the model's output.

maxTokens · integer<int32>

The maximum number of tokens to generate in the response.

tools · object[]

The list of tools the model can call.

Show child attributes

toolChoice · object

How the model should use the provided tools.

Show child attributes

validateSchema · boolean

A flag to determine whether to validate the AI response against the provided schema.

reasoningConfig · object

Configuration for reasoning behavior and effort level.

Show child attributes

Response

200

application/json

Successful tool calling response.

Response from a Messages API.

content · object[]

The list of content generated by the model.

Text-based message content.

Option 1

Option 2

Option 3

Option 4

Option 5

Show child attributes

modelId · string

The id of the model used to generate the response.

sessionId · string<uuid>

The id of the AI Session associated with this request.

stopReason · enum<string>

The reason that the model stopped.

Available options: TOOL_USE, MAX_TOKENS, STOP_SEQUENCE, END_TURN, CONTENT_FILTERED, SAFETY, UNKNOWN

modelProviderUsage · object

The token usage from the model provider.

Show child attributes