A API Criar modelo personalizado oferece aos desenvolvedores e administradores a capacidade de integrar perfeitamente grandes modelos de linguagem (LLMs) proprietários ou de terceiros e outros modelos de IA diretamente no AI Agent Studio.

  • Requer um esquema de payload JSON, que encapsula informações sobre o modelo. O esquema define atributos como o nome do fornecedor, o nome do modelo específico, protocolos de autenticação, detalhes do ponto de extremidade da API (incluindo parâmetros de caminho, parâmetros de consulta e cabeçalhos necessários) e a estrutura dos corpos de solicitação e resposta.
  • A API permite que os usuários definam variáveis nos corpos de solicitação e resposta que podem ser preenchidas dinamicamente durante o tempo de execução. Essas variáveis podem ser designadas para diferentes finalidades usando anotações específicas:
    • PROMPT_QUERY (Obrigatório): Essa anotação indica que a variável correspondente deve ser substituída pelo prompt fornecido pelo usuário na página AI Skills. Isso é essencial para passar os prompts de entrada do usuário para o modelo.
    • REQUEST_PARAMETER (Obrigatório): Essa anotação indica que a variável deve ser exposta como um parâmetro configurável na página Model connections.
    • MODEL_PARAMETER : Semelhante a REQUEST_PARAMETER, essa anotação designa a variável para configuração na página AI Skills.
    • RESPONSE_PARAMETER (Obrigatório): Essa anotação indica que a variável será retornada na resposta do modelo de IA.
  • A API retorna uma resposta 200 OK com o modelo criado após a criação bem-sucedida.
POST https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel
Corpo da solicitação:
{
   "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"
                  }
               }
            ]
         }
      }
   ]
}

Parâmetros da solicitação
Parâmetro Tipo Obrigatório Descrição
nome String Sim Nome do modelo personalizado
descrição String Não Descrição do modelo personalizado
authAction Objeto Sim Define as opções de autenticação para a chamada do modelo de IA. Para obter mais detalhes, consulte a seguir
apiType String Sim Especifica o tipo de API (por exemplo, "REST")
ações Matriz Sim Contém uma matriz de objetos, em que cada objeto define um endpoint de modelo específico ou uma ação dentro do modelo personalizado.

Objeto authAction 

{
   "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":[
      {
         .... 
      }
   ]
}
Parâmetro Tipo Obrigatório Descrição
authType String Sim Tipo de autenticação. API_KEY para Chave de API, OAUTH2 para OAuth2, CUSTOM_KEYS para múltiplas chaves e AWS_SIGNATURE_V4 para autenticação específica da AWS.
API_KEY, OAUTH2 ou CUSTOM_KEYS Objeto Sim Define as chaves de autenticação personalizadas. Seus atributos são descritos abaixo em keys.
  • API_KEY é obrigatório, se authType for API_KEY.
  • OAUTH2 é obrigatório, se authType for OAUTH2.
  • CUSTOM_KEYS é obrigatório, se authType for CUSTOM_KEYS.
↳↳ chaves Matriz Sim Uma matriz de objetos-chave para autenticação.
↳↳↳ local String Sim Onde a chave deve ser colocada (por exemplo, "cabeçalho").
↳↳↳keyName String Sim O nome da chave (por exemplo, "Autorização", "x-api-key").
↳↳↳ prefixo Objeto Não Um prefixo opcional a ser adicionado ao valor da chave (por exemplo, “Bearer” para tokens de portador).
awsSignatureV4 Objeto Sim AWS_SIGNATURE_V4 é obrigatório se authType for AWS_SIGNATURE_V4. Esse objeto define as credenciais do AWS (ID da chave de acesso, chave de acesso secreta, chave de sessão) para autenticação do AWS Signature.
↳↳ accessKey Objeto Sim Define o ID da chave de acesso do AWS.
↳↳↳ local String Sim Onde a chave de acesso deve ser colocada (por exemplo, “cabeçalho”, “consulta”).
↳↳↳ keyName String Sim O nome do parâmetro para a chave de acesso (por exemplo, “aws_sign_access_key”).
↳↳ secretkey Objeto Sim Define a chave de acesso secreta do AWS.
↳↳↳ local String Sim Onde a chave secreta deve ser colocada.
↳↳↳ keyName String Sim O nome do parâmetro para a chave secreta.
↳↳ sessionkey Objeto Não Define a chave de sessão do AWS (opcional).
↳↳↳ local String Sim Onde a chave de sessão deve ser colocada.
↳↳↳ keyName String Sim O nome do parâmetro para a chave de sessão.

Matriz ações 

{
   "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":[
               {
                  ....
               }
            ]
         }
      }
   ]
}
Parâmetro Tipo Obrigatório Descrição
nome String Sim O nome programático do endpoint/ação do modelo específico.
displayName String Sim Um nome de fácil utilização para o endpoint do modelo, exibido na interface do usuário.
descrição String Não Uma descrição detalhada do endpoint do modelo e de seus recursos.
método String Sim O método HTTP para a chamada de API. Normalmente, deve ser POST para a maioria dos modelos de IA generativa.
uri String Sim O URI completo do endpoint do modelo de IA. Parâmetros dinâmicos no URI.
params Matriz Não Contém um conjunto de parâmetros que são usados ao configurar a Model connection e serão inseridos no URI ao chamar a API do modelo de IA em tempo de execução. O parâmetro pode ser uma variável PATH_PARAM ou uma variável QUERY_PARAM. Você também pode adicionar HEADERS associados a essa solicitação de API. No exemplo, deploymentId e projectId são uma variável PATH_PARAM e apiVersion é uma variável QUERY_PARAM.
Solicitação Objeto Sim Define o formato e a estrutura dos dados que precisam ser enviados ao modelo, incluindo variáveis e suas anotações. O corpo especifica a estrutura e o conteúdo da solicitação. O array variables define os elementos dinâmicos dentro do corpo, usando path para especificar a localização da variável na estrutura JSON.
Resposta Objeto Especifica o formato e a estrutura dos dados que o modelo retornará, incluindo variáveis, suas anotações e seus nomes canônicos. O body especifica a estrutura e o conteúdo da resposta. O array variables define os elementos dinâmicos dentro do corpo, usando path para especificar a localização da variável na estrutura JSON.

Matriz params 

{
   "params":[
      {
         "type":"HEADERS"
      },
      {
         "type":"PATH_PARAM",
         "attribute":[
            {
               "name":"deployment",
               "label":"Deployment",
               "value":{
                  "type":"TEXT",
                  "string":"aai-openai2"
               }
            }
         ]
      }
   ]
Parâmetro Tipo Obrigatório Descrição
tipo String Sim O tipo de parâmetro (por exemplo, HEADERS, PATH_PARAM, QUERY_PARAM).
atributo Matriz Sim Uma matriz de objetos de atributo definindo os detalhes do parâmetro. Obrigatório para PATH_PARAM e QUERY_PARAM.
↳ nome String Sim O nome do parâmetro (por exemplo, “implantação”, “versão da API”).
↳ rótulo String Não Um rótulo de fácil utilização para o parâmetro, exibido na interface do usuário.
↳valor Objeto Não Um objeto que contém o valor padrão ou inicial do parâmetro. A seguir estão os atributos:
  • tipo (string): O tipo de dado do valor do parâmetro (por exemplo, TEXT, INTEGER).
  • string (string): O valor da string se tipo for TEXT.
  • número (string): O valor numérico se tipo for INTEGER.

Objeto de solicitação 

{
    "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"
                  ]
               }
            }
         ]
      }
   }
Parâmetro Tipo Obrigatório Descrição
bruto Objeto Sim Define o corpo bruto da solicitação e suas variáveis dinâmicas.
↳ corpo String Sim A string JSON bruta que representa a estrutura do corpo da solicitação. Essa string deve conter espaços reservados para variáveis.
↳ variáveis Matriz Não Uma matriz de objetos que define elementos dinâmicos dentro do corpo.
↳↳ caminho String Sim O JSONPath para o local da variável dentro da estrutura JSON do corpo.
↳↳ atributo Objeto Sim Um objeto que descreve as propriedades da variável.
↳↳↳ nome String Sim O nome interno da variável.
↳↳↳rótulo String Não Um rótulo de fácil utilização para a variável.
↳↳↳ valor Objeto Não Um objeto que contém o valor padrão ou inicial da variável.
↳↳↳ anotações Matriz Não Uma matriz de strings que especifica a finalidade da variável. Anotações compatíveis: PROMPT_QUERY, REQUEST_PARAMETER, MODEL_PARAMETER.

Objeto de resposta 

{
      "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"
            }
         }
      ]
   }
}
Parâmetro Tipo Obrigatório Descrição
corpo String Sim A string JSON bruta que representa a estrutura do corpo da resposta esperada do modelo.
variáveis Matriz Não Uma matriz de objetos que define como extrair elementos dinâmicos do corpo da resposta.
↳ caminho String Sim O JSONPath para o local da variável dentro da estrutura JSON do corpo.
↳ atributo Objeto Sim Um objeto que descreve as propriedades da variável.
↳↳ nome String Sim O nome interno da variável.
↳↳rótulo String Não Um rótulo de fácil utilização para a variável.
↳↳ valor Objeto Não Um objeto que contém o valor padrão ou inicial da variável.
↳↳ anotações Matriz Não Uma matriz de strings que especifica a finalidade da variável. Anotação compatível: RESPONSE_PARAMETER..
↳↳ canonicalName String Não Caminho JSON para a variável no esquema canônico da Automation Anywhere.
  • Use choices[0].completionTokens para preencher o número de tokens consumidos para gerar a resposta.
  • Use choices[0].value para preencher a resposta do LLM.
  • Use model_name para preencher o nome ou identificador do modelo de IA.
  • Use choices[0].promptTokens para preencher o número de tokens consumidos pelo prompt.
  • Use choices[0].totalTokens para preencher o total de tokens consumidos para atender à solicitação.

Para mais detalhes da API de criação de modelo personalizado, incluindo a resposta e os parâmetros de resposta, consulte API do AI Agent Studio

Outras APIs de modelo personalizado

Obter API de informações do modelo personalizado
GET https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel/vendors/{vendorName}/models/{modelName}
  • Esta API recupera a definição dos modelos personalizados existentes.
  • É necessário o nome do fornecedor (vendorName) e o nome do modelo (modelName) como parâmetros de caminho.
  • A API retorna uma resposta 200 OK contendo os objetos que representam o modelo solicitado.
Atualizar API de definição de modelo personalizado
PUT https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel
  • Essa API atualiza uma definição de modelo personalizado existente.
    Nota: Essa API só pode atualizar modelos personalizados que não têm Model connections associadas.
  • É necessário o nome do fornecedor (vendorName) e o nome do modelo (modelName) para identificar o modelo que será atualizado.
  • A API retorna uma resposta 200 OK com o modelo atualizado após uma atualização bem-sucedida.
Atualizar o nome e a descrição da API de definição do modelo personalizado
PATCH https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel
  • Essa API atualiza o nome e a descrição da definição do modelo personalizado.
  • É necessário o nome do fornecedor (vendorName) e o nome do modelo (modelName) para identificar o modelo que será atualizado.
  • A API retorna uma resposta 200 OK com os detalhes do modelo atualizado após a atualização bem-sucedida.
Excluir API de modelo personalizado
DELETE https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel/vendors/{vendorName}/models/{modelName}
  • Esta API exclui um modelo personalizado existente.
  • Semelhante à API GET, ela usa (vendorName) e (modelName) como parâmetros de caminho para identificar o modelo de destino.
    Nota: O modelo só pode ser excluído se não estiver atualmente associado a quaisquer Model connections ativas. Ou seja, você deve primeiro remover qualquer AI Skills e Task Bots que dependam da Model connection antes de tentar excluir a definição do modelo.
  • A API retorna uma resposta 204 Sem conteúdo após a exclusão bem-sucedida.
Listar API de modelos personalizados
POST https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel/list
  • Essa API recupera uma lista de todos os modelos personalizados definidos para todos os fornecedores na Control Room.
  • Ela aceita um corpo de solicitação opcional que contém um objeto FilterRequest, permitindo que os usuários filtrem os resultados com base em critérios específicos.
  • A API retorna uma resposta 200 OK com objetos contendo os modelos solicitados.

Para obter mais detalhes sobre as APIs acima, consulte API do AI Agent Studio. Você pode baixar aqui uma coleção do Postman para o AI Agent Studio - definições de modelos personalizados que contêm exemplos de chamadas de API para se conectar aos modelos personalizados.