The Create Custom Model API provides developers and administrators with the power to seamlessly integrate proprietary or third-party Large Language Models (LLMs) and other AI models directly into AI Agent Studio.

  • It requires a JSON payload schema, which encapsulates information about the model. The schema defines attributes such as the vendor's name, the specific model's name, authentication protocols, API endpoint details (including path parameters, query parameters, and required headers), and the structure of the request and response bodies.
  • The API allows users to define variables within the request and response bodies that can be dynamically populated during runtime. These variables can be designated for different purposes using specific annotations:
    • PROMPT_QUERY (Mandatory): This annotation signifies that the corresponding variable should be replaced with the prompt provided by the user in the AI Skills page. This is essential for passing user input prompts to the model.
    • REQUEST_PARAMETER(Mandatory): This annotation indicates that the variable should be exposed as a configurable parameter on the Model connections page.
    • MODEL_PARAMETER: Similar to REQUEST_PARAMETER, this annotation designates the variable for configuration on the AI Skills page.
    • RESPONSE_PARAMETER(Mandatory): This annotation signifies that the variable will be returned in the response from the AI model.
  • The API returns a 200 OK response with the created model upon successful creation.
POST https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel
Request body:
{
   "name":"Azure OpenAI reasoning models",
   "version":"0",
   "authAction":{
      "authType":"CUSTOM_KEYS",
      "customKeys":{
         "keys":[
            {
               "location":"header",
               "keyName":"Authorization",
               "prefix":"Bearer "
            }
         ]
      }
   },
   "apiType":"REST",
   "actions":[
      {
         "name":"o3-mini",
         "displayName":"o3-mini",
         "description":"The o1 and o3 series models are specifically designed to tackle reasoning 
          and problem-solving tasks with increased focus and capability. These models spend more time 
          processing and understanding the user's request, making them exceptionally strong in areas 
          like science, coding, math and similar fields. For example, o1 can be used by healthcare researchers 
          to annotate cell sequencing data, by physicists to generate complicated mathematical formulas needed 
          for quantum optics, and by developers in all fields to build and execute multi-step workflows.",
         "method":"POST",
         "uri":"https://{deployment}.openai.azure.com/openai/deployments/o3-mini/chat/completions?api-version=2025-01-01-preview",
         "params":[
            {
               "type":"HEADERS"
            },
            {
               "type":"PATH_PARAM",
               "attribute":[
                  {
                     "name":"deployment",
                     "label":"Deployment",
                     "value":{
                        "type":"TEXT",
                        "string":"aai-openai2"
                     }
                  }
               ]
            }
         ],
         "request":{
            "raw":{
               "body":"{\n        \"messages\": [\n            {\n                \"role\": \"user\",
                \n                \"content\": \"I am going to       Paris, what should I see?\"\n            
                 }\n        ],\n        \"max_completion_tokens\": 100000,\n        \"model\": \"o3-mini\"\n    }",
               "variables":[
                  {
                     "path":"$.max_completion_tokens",
                     "attribute":{
                        "name":"max_completion_tokens",
                        "label":"max_completion_tokens",
                        "value":{
                           "type":"INTEGER",
                           "number":"100000"
                        },
                        "annotations":[
                           "REQUEST_PARAMETER"
                        ]
                     }
                  },
                  {
                     "path":"$.messages.content",
                     "attribute":{
                        "name":"prompt",
                        "label":"prompt",
                        "value":{
                           "type":"TEXT"
                        },
                        "annotations":[
                           "PROMPT_QUERY"
                        ]
                     }
                  }
               ]
            }
         },
         "response":{
            "body":"{\n    \"id\": \"chatcmpl-APwQdLa9WCQAdZg0dO5OjGr2ER4sX\",\n    \"object\": \"chat.completion\",\n
                   \"created\": 1730746163,\n    \"model\": \"o3-mini-2025-01-31\",\n    \"choices\": [\n        {\n
                   \"index\": 0,\n            \"message\": {\n                \"role\": \"assistant\",\n                
                   \"content\": \"Sure! They are one of the most mysterious and exciting objects in space.\",\n
                   \"refusal\": null\n            },\n            \"finish_reason\": \"stop\"\n        }\n    ],\n
                   \"usage\": {\n                \"prompt_tokens\": 17,\n        \"completion_tokens\": 959,\n
                   \"total_tokens\": 976,\n        \"prompt_tokens_details\": {\n            \"cached_tokens\": 0\n
                    },\n        \"completion_tokens_details\": {\n            \"reasoning_tokens\": 64\n        }\n
                    },\n    \"system_fingerprint\": \"fp_35c19d48ca\"\n}",
            "variables":[
               {
                  "path":"$.usage.completion_tokens",
                  "attribute":{
                     "name":"completion_tokens",
                     "label":"completion_tokens",
                     "value":{
                        "type":"INTEGER"
                     },
                     "annotations":[
                        "RESPONSE_PARAMETER"
                     ],
                     "canonicalName":"choices[0].completionTokens"
                  }
               },
               {
                  "path":"$.choices.message.content",
                  "attribute":{
                     "name":"content",
                     "label":"content",
                     "value":{
                        "type":"TEXT",
                        "string":"Some response from LLM"
                     },
                     "annotations":[
                        "RESPONSE_PARAMETER"
                     ],
                     "canonicalName":"choices[0].value"
                  }
               },
               {
                  "path":"$.model",
                  "attribute":{
                     "name":"model",
                     "label":"model",
                     "value":{
                        "type":"TEXT"
                     },
                     "annotations":[
                        "RESPONSE_PARAMETER"
                     ],
                     "canonicalName":"model_name"
                  }
               },
               {
                  "path":"$.usage.prompt_tokens",
                  "attribute":{
                     "name":"prompt_tokens",
                     "label":"prompt_tokens",
                     "value":{
                        "type":"INTEGER"
                     },
                     "annotations":[
                        "RESPONSE_PARAMETER"
                     ],
                     "canonicalName":"choices[0].promptTokens"
                  }
               },
               {
                  "path":"$.usage.total_tokens",
                  "attribute":{
                     "name":"total_tokens",
                     "label":"total_tokens",
                     "value":{
                        "type":"INTEGER"
                     },
                     "annotations":[
                        "RESPONSE_PARAMETER"
                     ],
                     "canonicalName":"choices[0].totalTokens"
                  }
               }
            ]
         }
      }
   ]
}

Request parameters
Parameter Type Required Description
name String Yes Name of the custom model
description String No Description of the custom model
authAction Object Yes Defines the authentication options for the AI model call. See below for more details
apiType String Yes Specifies the API type (e.g., "REST")
actions Array Yes Contains an array of objects, where each object defines a specific model endpoint or action within the custom model.

authAction Object

{
   "name":"Azure OpenAI reasoning models",
   "description":"string",
   "version":"0",
   "authAction":{
      "authType":"CUSTOM_KEYS",
      "customKeys":{
         "keys":[
            {
               "location":"header",
               "keyName":"Authorization",
               "prefix":"Bearer "
            }
         ]
      }
   }

{
   "name":"Bedrock - Claude2.1",
   "description":"string",
   "version":"string",
   "authAction":{
      "authType":"AWS_SIGNATURE_V4",
      "awsSignatureV4":{
         "accessKey":{
            "location":"header",
            "keyName":"aws_sign_access_key"
         },
         "secretkey":{
            "location":"header",
            "keyName":"aws_sign_access_key"
         },
         "sessionkey":{
            "location":"header",
            "keyName":"aws_sign_session_key"
         }
      }
   },
   "api_type":"REST",
   "actions":[
      {
         .... 
      }
   ]
}
Parameter Type Required Description
authType String Yes Type of authentication. API_KEY for API Key, OAUTH2 for OAuth2, CUSTOM_KEYS for multiple keys and AWS_SIGNATURE_V4 for AWS-specific authentication.
API_KEY, OAUTH2, or CUSTOM_KEYS Object Yes Defines the custom authentication keys. Its attributes are described below under keys.
  • API_KEY is required, if authType is API_KEY.
  • OAUTH2 is required, if authType is OAUTH2.
  • CUSTOM_KEYS is required, if authType is CUSTOM_KEYS.
↳↳ keys Array Yes An array of key objects for authentication.
↳↳↳ location String Yes Where the key should be placed (e.g., "header").
↳↳↳keyName String Yes The name of the key (e.g., "Authorization", "x-api-key").
↳↳↳ prefix Object No An optional prefix to be added to the key value (e.g., "Bearer " for bearer tokens).
awsSignatureV4 Object Yes AWS_SIGNATURE_V4 is required if authType is AWS_SIGNATURE_V4. This object defines the AWS credentials (Access Key ID, Secret Access Key, Session Key) for AWS Signature authentication.
↳↳ accessKey Object Yes Defines the AWS Access Key ID.
↳↳↳ location String Yes Where the Access Key should be placed (e.g., "header", "query").
↳↳↳ keyName String Yes The name of the parameter for the Access Key (e.g., "aws_sign_access_key").
↳↳ secretkey Object Yes Defines the AWS Secret Access Key.
↳↳↳ location String Yes Where the Secret Key should be placed.
↳↳↳ keyName String Yes The name of the parameter for the Secret Key.
↳↳ sessionkey Object No Defines the AWS Session Key (optional).
↳↳↳ location String Yes Where the Session Key should be placed.
↳↳↳ keyName String Yes The name of the parameter for the Session Key.

actions Array

{
   "actions":[
      {
         "name":"o3-mini",
         "displayName":"o3-mini",
         "description":"The o1 and o3 series models are specifically designed to tackle reasoning 
          and problem-solving tasks with increased focus and capability. These models spend more time 
          processing and understanding the user's request, making them exceptionally strong in areas 
          like science, coding, math and similar fields. For example, o1 can be used by healthcare researchers 
          to annotate cell sequencing data, by physicists to generate complicated mathematical formulas needed 
          for quantum optics, and by developers in all fields to build and execute multi-step workflows.",
         "method":"POST",
         "uri":"https://{deployment}.openai.azure.com/openai/deployments/o3-mini/chat/completions?api-version=2025-01-01-preview",
         "params":[
            {
               "type":"string",
               "attribute":[
                  {
                     "name":"string",
                     "label":"string",
                     "value":{
                        "type":"string",
                        "string":"string",
                        "number":"string"
                     }
                  }
               ]
            }
         ],
         "request":{
            "raw":{
               "body":"string",
               "variables":[
                  {
                     ....
                  }
               ]
            }
         },
         "response":{
            "body":"string",
            "variables":[
               {
                  ....
               }
            ]
         }
      }
   ]
}
Parameter Type Required Description
name String Yes The programmatic name of the specific model endpoint/action.
displayName String Yes A user-friendly name for the model endpoint, displayed in the UI.
description String No A detailed description of the model endpoint and its capabilities.
method String Yes The HTTP method for the API call. Should typically be POST for most generative AI models.
uri String Yes The full URI of the AI model endpoint. Dynamic parameters in the URI.
params Array No Contains a collection of parameters that are used when configuring the Model connection and will be inserted in the to URI when calling the AI model API at runtime. Parameter can either be a PATH_PARAM variable or a QUERY_PARAM variable. You can also add HEADERS that are associated with this API request. In the example, deploymentId and projectId are a PATH_PARAM variable and apiVersion is a QUERY_PARAM variable.
Request Object Yes Defines the format and structure of the data that needs to be sent to the model, including variables and their annotations. The body specifies the structure and content of the request. The variables array defines the dynamic elements within the body, using path to specify the variable location in the JSON structure.
Response Object Specifies the format and structure of the data that the model will return, including variables, their annotations, and their canonical names . The body specifies the structure and content of the response. The variables array defines the dynamic elements within the body, using path to specify the variable location in the JSON structure.

params Array

{
   "params":[
      {
         "type":"HEADERS"
      },
      {
         "type":"PATH_PARAM",
         "attribute":[
            {
               "name":"deployment",
               "label":"Deployment",
               "value":{
                  "type":"TEXT",
                  "string":"aai-openai2"
               }
            }
         ]
      }
   ]
Parameter Type Required Description
type String Yes The type of parameter (e.g., HEADERS, PATH_PARAM, QUERY_PARAM).
attribute Array Yes An array of attribute objects defining the parameter details. Required for PATH_PARAM and QUERY_PARAM.
↳ name String Yes The name of the parameter (e.g., "deployment", "api-version").
↳ label String No A user-friendly label for the parameter, displayed in the UI.
↳value Object No An object containing the default or initial value of the parameter. Following are the attributes:
  • type (string): The data type of the parameter value (e.g., TEXT, INTEGER).
  • string (string): The string value if type is TEXT.
  • number (string): The numeric value if type is INTEGER.

request Object

{
    "request":{
      "raw":{
         "body":"{\n        \"messages\": [\n            {\n                \"role\": \"user\",
                \n                \"content\": \"I am going to       Paris, what should I see?\"\n            
                 }\n        ],\n        \"max_completion_tokens\": 100000,\n        \"model\": \"o3-mini\"\n    }",
         "variables":[
            {
               "path":"$.max_completion_tokens",
               "attribute":{
                  "name":"max_completion_tokens",
                  "label":"max_completion_tokens",
                  "value":{
                     "type":"INTEGER",
                     "number":"100000"
                  },
                  "annotations":[
                     "REQUEST_PARAMETER"
                  ]
               }
            },
            {
               "path":"$.messages.content",
               "attribute":{
                  "name":"prompt",
                  "label":"prompt",
                  "value":{
                     "type":"TEXT"
                  },
                  "annotations":[
                     "PROMPT_QUERY"
                  ]
               }
            }
         ]
      }
   }
Parameter Type Required Description
raw Object Yes Defines the raw request body and its dynamic variables.
↳ body String Yes The raw JSON string representing the request body structure. This string should contain placeholders for variables.
↳ variables Array No An array of objects defining dynamic elements within the body.
↳↳ path String Yes The JSONPath to the variable's location within the body JSON structure.
↳↳ attribute Object Yes An object describing the variable's properties.
↳↳↳ name String Yes The internal name of the variable.
↳↳↳label String No A user-friendly label for the variable.
↳↳↳ value Object No An object containing the default or initial value of the variable.
↳↳↳ annotations Array No An array of strings specifying the variable's purpose. Supported annotations: PROMPT_QUERY, REQUEST_PARAMETER, MODEL_PARAMETER.

response Object

{
      "response":{
      "body":"{\n    \"id\": \"chatcmpl-APwQdLa9WCQAdZg0dO5OjGr2ER4sX\",\n    \"object\": \"chat.completion\",\n
                   \"created\": 1730746163,\n    \"model\": \"o3-mini-2025-01-31\",\n    \"choices\": [\n        {\n
                   \"index\": 0,\n            \"message\": {\n                \"role\": \"assistant\",\n                
                   \"content\": \"Sure! They are one of the most mysterious and exciting objects in space.\",\n
                   \"refusal\": null\n            },\n            \"finish_reason\": \"stop\"\n        }\n    ],\n
                   \"usage\": {\n                \"prompt_tokens\": 17,\n        \"completion_tokens\": 959,\n
                   \"total_tokens\": 976,\n        \"prompt_tokens_details\": {\n            \"cached_tokens\": 0\n
                    },\n        \"completion_tokens_details\": {\n            \"reasoning_tokens\": 64\n        }\n
                    },\n    \"system_fingerprint\": \"fp_35c19d48ca\"\n}",
      "variables":[
         {
            "path":"$.usage.completion_tokens",
            "attribute":{
               "name":"completion_tokens",
               "label":"completion_tokens",
               "value":{
                  "type":"INTEGER"
               },
               "annotations":[
                  "RESPONSE_PARAMETER"
               ],
               "canonicalName":"choices[0].completionTokens"
            }
         },
         {
            "path":"$.choices.message.content",
            "attribute":{
               "name":"content",
               "label":"content",
               "value":{
                  "type":"TEXT",
                  "string":"Some response from LLM"
               },
               "annotations":[
                  "RESPONSE_PARAMETER"
               ],
               "canonicalName":"choices[0].value"
            }
         },
         {
            "path":"$.model",
            "attribute":{
               "name":"model",
               "label":"model",
               "value":{
                  "type":"TEXT"
               },
               "annotations":[
                  "RESPONSE_PARAMETER"
               ],
               "canonicalName":"model_name"
            }
         },
         {
            "path":"$.usage.prompt_tokens",
            "attribute":{
               "name":"prompt_tokens",
               "label":"prompt_tokens",
               "value":{
                  "type":"INTEGER"
               },
               "annotations":[
                  "RESPONSE_PARAMETER"
               ],
               "canonicalName":"choices[0].promptTokens"
            }
         },
         {
            "path":"$.usage.total_tokens",
            "attribute":{
               "name":"total_tokens",
               "label":"total_tokens",
               "value":{
                  "type":"INTEGER"
               },
               "annotations":[
                  "RESPONSE_PARAMETER"
               ],
               "canonicalName":"choices[0].totalTokens"
            }
         }
      ]
   }
}
Parameter Type Required Description
body String Yes The raw JSON string representing the expected response body structure from the model.
variables Array No An array of objects defining how to extract dynamic elements from the response body.
↳ path String Yes The JSONPath to the variable's location within the body JSON structure.
↳ attribute Object Yes An object describing the variable's properties.
↳↳ name String Yes The internal name of the variable.
↳↳label String No A user-friendly label for the variable.
↳↳ value Object No An object containing the default or initial value of the variable.
↳↳ annotations Array No An array of strings specifying the variable's purpose. Supported annotation: RESPONSE_PARAMETER.
↳↳ canonicalName String No JSON path to the variable in the Automation Anywhere canonical schema.
  • Use choices[0].completionTokens to populate number of tokens consumed for generating response.
  • Use choices[0].value to populate LLM response.
  • Use model_name to populate the name or identifier of the AI model.
  • Use choices[0].promptTokens to populate number of tokens consumed by prompt.
  • Use choices[0].totalTokens to populate total tokens consumed to fulfill the request.

For more details of the create custom model API including the response and response parameters, see AI Agent Studio API

Other Custom model APIs

Get Custom model information API
GET https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel/vendors/{vendorName}/models/{modelName}
  • This API retrieves the definition of the existing custom models.
  • It requires the vendor name (vendorName) and the model name (modelName) as path parameters.
  • The API returns a 200 OK response containing the objects representing the requested model.
Update Custom model definition API
PUT https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel
  • This API updates an existing custom model definition.
    Note: This API can only update custom models that have no associated Model connections.
  • It requires the vendor name (vendorName) and the model name (modelName) to identify the model that will be updated.
  • The API returns a 200 OK response with the updated model upon successful update.
Update name and description of the Custom model definition API
PATCH https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel
  • This API updates the name and description of the custom model definition.
  • It requires the vendor name (vendorName) and the model name (modelName) to identify the model that will be updated.
  • The API returns a 200 OK response with the updated model details upon successful update.
Delete Custom model API
DELETE https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel/vendors/{vendorName}/models/{modelName}
  • This API deletes an existing custom model.
  • Similar to the GET API, it uses (vendorName) and (modelName) as path parameters to identify the target model.
    Note: The model can only be deleted if it is not currently associated with any active Model connections. This means you must first remove any AI Skills and Task Bots that rely on the Model connection before attempting to delete the model definition.
  • The API returns a returns a 204 No Content response upon successful deletion.
List Custom models API
POST https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel/list
  • This API retrieves a list of all custom models defined for all vendors within the Control Room.
  • It accepts an optional request body containing a FilterRequest object, enabling users to filter the results based on specific criteria.
  • The API returns a 200 OK response with objects containing the requested models.

For more details about the above APIs, see AI Agent Studio API. You can download here a Postman collection for AI Agent Studio - custom model definitions which contain example API calls to connect to the custom models.