Pular para o conteúdo principal

Criar e Executar Remote Quick Commands

Você pode usar os Quick Commands que criou no Portal da StackSpot AI além das IDEs. Esses comandos podem ajudá-lo a usar a infraestrutura da StackSpot, como Workspaces, Stack AI e Knowledge Sources, para acelerar casos de uso de GenAI via API.

Quando usados remotamente, os Quick Commands devem aproveitar sem problemas a infraestrutura da StackSpot, incluindo Stack AI e Knowledge Sources. Além disso, Remote Quick Commands suportam o tratamento de parâmetros, permitindo que você insira variáveis ou argumentos para personalizar o comportamento dos comandos.

O objetivo do Remote Quick Command é utilização e integração por software de terceiros.

Dica!

Qual é a principal diferença entre Quick Command IDE e Remote Quick Command?

Quick Command é um recurso personalizado que funciona apenas no seu IDE. Você pode usá-lo clicando com o botão direito do mouse. Por outro lado, você pode executar Remote Quick Command via API e gerar payloads úteis para serviços externos através da internet. É perfeito para integrações e processamento além do ambiente local.

Criar um Remote Quick Command

Pré-requisitos

Passo 1. Criar e executar um Remote Quick

1. Navegue até o ‘Contents > Quick Command’;

2. Clique em ‘Create Quick Command’ e selecione a opção ‘Remote’. Preencha os campos para adicionar informações sobre o seu Quick Command:

  • Nome do Quick Command: adicione um nome para o seu comando

  • Comando: adicione um nome que você usará mais tarde; ele deve seguir o padrão de slug. Para mais informações sobre Slugs, confira o padrão do slug.

  • Descrição: adicione uma descrição do que o seu comando pode fazer.

Você pode criar um RQC utilizando um template ou criar um em branco. Pode ser prompt ou web request.

Prompt

Clique na caixa de Prompt e arraste-a para a caixa 'Iniciar', conectando-a usando a linha.

Na caixa de Prompt, preencha os campos:

  • Nome do prompt: adicione um identificador slug seguindo o padrão de slug.
  • Adicione o prompt: escreva o que você quer que seu comando faça. Inclua a variável Jinja {{input_data}} para passar dados dinâmicos.
  • Selecione um Knowledge Source e/ou um Agente.
  • Use a Stack atual para gerar código: Esta opção depende do que você precisa.
    • Quando habilitada, considera o contexto da sua Stack e gera código baseado se você tem uma Stack de Java ou Python, por exemplo. Se você requer geração de código, então esta opção é recomendada.
    • No entanto, se você precisa gerar texto, como traduções, é melhor não habilitar esta opção, pois não deve produzir os melhores resultados.
  • Incluir os arquivos enviados: Para permitir que as pessoas usuárias enviem arquivos em uma etapa específica do Quick Command, ative a opção Incluir arquivos enviados em cada etapa desejada. Quando essa opção estiver ativada, as pessoas usuárias poderão fazer upload de arquivos durante a execução do comando.
  • Continuar mesmo com erro: permite definir qual será o próximo passo de acordo com o sucesso ou erro de um step. Assim, você controla o fluxo do Quick Command conforme necessário.
    • Para configurar, clique na caixa do prompt e marque a opção 'Continuar mesmo com erro'. Clique em 'Sucesso'' e conecte a caixa desejada. Faça o mesmo para 'Erro'.
    • Você pode tratar erros exibindo o status, mensagem de erro ou outras informações usando variáveis Jinja no campo de Resultado Final. Para mais detalhes, confira a documentação.
Informações Adicionais
  • Se um step não tiver essa opção ativada, qualquer erro interrompe a execução do Quick Command.
  • Se a opção estiver ativada e ocorrer um erro, o fluxo segue o caminho definido para Erro. A StackSpot AI só continua a execução se houver um fluxo definido para erros.

Essa opção está disponível apenas para steps do tipo Prompt, não para Web Request.

Web Request

Clique na caixa de Web Request e arraste-a para a caixa 'Iniciar', conectando-a usando a linha.

Na caixa de Web Request, configure a URL, os headers e o corpo da requisição para uma requisição HTTP.

  • Nome do Web request: adicione o nome da requisição seguindo o padrão do slug.
  • Método HTTP: escolha o método HTTP.
  • URL Endpoint: adicione a URL do endpoint.
  • Headers: Clique no botão 'Secret' para criar uma nova secret;
  • Clique no botão 'Adicionar' para adicionar uma secret existente. Para mais informações, confira a página de Secrets.
  • Body da requisição

A conectividade é limitada a StackSpot AI, e seu serviço ficará disponível online. Ao usar um Quick Command na extensão do IDE, o web request opera dentro dele, habilitando funcionalidade apenas em redes privadas. Se este for o seu caso, opte pelo Quick Command.

3. Clique em 'Finalizar' e preencha a Utilização do Quick Command. Adicione:

{{o-nome-do-seuQC.answer}}

Ele representa o resultado esperado exibido no serviço.

Informação Adicional

Você pode incorporar condicionais ao fluxo dos seus Quick Commands. Para mais detalhes, confira a página de Condicionais.

Passo 3. Execute o Remote Quick Command via API

Você pode executar o Quick Command via API na aba ‘Como usar’. Siga os passos:

3.1. Autenticar e obter um Bearer Token

  1. Abra seu cliente de API (por exemplo, Postman);
  2. Crie uma nova requisição POST para a seguinte URL:
POST https://idm.stackspot.com/stackspot/oidc/oauth/token

  1. Adicione os seguintes headers: Content-Type: application/x-www-form-urlencoded

  2. No corpo da requisição, inclua suas credenciais de cliente::

{
  "grant_type": "client_credentials",
  "client_id": "seu_client_id",
  "client_secret": "seu_client_secret"
}
  1. Envie a requisição e copie o access_token da resposta.

3.2. Criar uma execução

  1. Crie uma nova requisição POST para o endpoint da API StackSpot para o seu Quick Command:
POST https://data-integration-api.stackspot.com/v1/quick-commands/create-execution/{{quick_command_slug}}

  1. Substitua o {{quick_command_slug}} pelo slug do seu Quick Command (por exemplo, meu-comando-remoto).

  2. Adicione os seguintes headers:

  • Authorization: Bearer seu_access_token
  • Content-Type: application/json
  1. No corpo da requisição, inclua os dados de entrada para o Quick Command:
{
  "input_data": "Adicione seu input data aqui"
  "execution_tag": "[Opcional] Sua tag aqui"
   "upload_ids": "Lista dos IDs de uploads"
}

  • input_data: este campo define a informação dinâmica ou o conteúdo que você irá processar usando o seu Quick Command. O valor inserido aqui é uma variável passada para o prompt ou para a requisição web especificada no seu QC.
  • execution_tag: este campo opcional permite que você atribua um identificador personalizado para cada execução do Quick Command. Usar essa tag facilita o rastreamento de uso, análises e auditoria, permitindo categorizar de forma eficiente de acordo com tags ou fluxos de trabalho específicos.
  • upload_ids: Uma lista dos IDs de upload gerados quando você faz upload de arquivos via API.
  1. Envie a requisição. A resposta incluirá um execution_id.

3.3. Monitorar o status da execução

  1. Crie uma nova requisição GET para a seguinte URL:
GET https://data-integration-api.stackspot.com/v1/quick-commands/callback/{{execution_id}}

Substitua o execution_id pelo ID retornado na etapa anterior.

  1. Adicione o seguinte header:
  • Authorization: Bearer seu_access_token
  1. Envie a requisição. A resposta incluirá o status da execução e o resultado.

Monitore a resposta na página para status de progresso, horários de início e fim, duração, porcentagem de execução e status.

Você receberá atualizações sobre o status em cada etapa, incluindo o resultado final, que você pode usar em qualquer lugar.

Informação Adicional

Se o seu Quick Command encontrar algum erro com o provedor do LLM, como limite de uso, tempo de resposta esgotado (timeout) ou falha de conexão, a StackSpot AI tentará executar a chamada novamente de forma automática. São feitas até três novas tentativas além da chamada original, totalizando quatro tentativas para cada step de LLM.

Você não pode alterar ou configurar a quantidade de tentativas.

Dica!

O que é o header Content-Type?

O header (cabeçalho) Content-Type é usado em requisições HTTP para indicar o formato dos dados que estão sendo enviados no corpo (body) da requisição. Ele informa ao servidor como interpretar os dados recebidos.

  • Content-Type: especifica o formato dos dados enviados.
  • application/x-www-form-urlencoded: formato padrão de envio de dados de formulários (chave=valor, separados por &).

Confira um exemplo a seguir no Quick Command:

Como fazer o upload de arquivos no Remote Quick Command

Quando um Remote Quick Command requer o upload de um arquivo, você precisa enviar o arquivo para a API de upload da StackSpot. Confira o exemplo a seguir para autenticar, gerar o formulário de upload e fazer o upload do seu arquivo.

  1. Autentique-se usando suas credenciais de cliente para obter um token de acesso:
curl --location 'https://iam-auth-ssr.stackspot.com/stackspot-dev/oidc/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=<client_id>' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_secret=<client-secret>' \
  -o auth.json
  1. Gerar dados do formulário de upload Solicite os dados do formulário de upload à API. Isso retornará os campos necessários e uma URL para o envio do seu arquivo.
curl https://genai-data-integration-api.stackspot.com/v2/file-upload/form \
  -H "accept: application/json" \
  -H "authorization: Bearer $(cat auth.json | jq -r .access_token)" \
  -H "content-type: application/json" \
  --data-raw '{"file_name":"teste.pdf","target_type":"CONTEXT","target_id":""}' \
  -o response.json
  1. Fazer upload do arquivo
    Utilize a URL e os campos do formulário retornados para enviar o seu arquivo:
curl 'https://300543077521-genai-file-ingestor-v2-bucket.s3.amazonaws.com/' \
  -F key=$(cat response.json | jq '.form.key') \
  -F x-amz-algorithm=$(cat response.json | jq '.form."x-amz-algorithm"') \
  -F x-amz-credential=$(cat response.json | jq '.form."x-amz-credential"') \
  -F x-amz-date=$(cat response.json | jq '.form."x-amz-date"') \
  -F x-amz-security-token=$(cat response.json | jq '.form."x-amz-security-token"') \
  -F x-amz-signature=$(cat response.json | jq '.form."x-amz-signature"') \
  -F policy=$(cat response.json | jq '.form.policy') \
  -F file=@./teste.pdf
  1. Exemplo de resposta da API A API retorna um objeto JSON com as informações do upload. Exemplo:
{
    "id": "01K2000",
    "url": "https://300543077521-genai-file-ingestor-v2-bucket.s3.amazonaws.com/",
    "form": {
        "key": "01GR7B000/CONTEXT/01000/teste.pdf",
        "x-amz-algorithm": "AWS4-HMAC-SHA256",
        "x-amz-credential": "ASIA0000/2025/sa-east-1/s3/aws4_request",
        "x-amz-date": "20250818T",
        "x-amz-security-token": "0000=",
        "policy": "ey0000==",
        "x-amz-signature": "671593e000"
    }
}
Informação Adicional
  • Remote Quick Command Rate Limit

Existe um limite no número de vezes que você pode usar o Remote Quick Command dentro de um período de 24 horas. O limite varia com base no tipo de token que você está usando.

  1. Personal Access Token (PAT)

Se você já o usou mais de 100 vezes nas últimas 24 horas, não poderá usá-lo novamente até que o limite de tempo tenha expirado. Neste caso, você receberá um erro HTTP status 429. Confira o exemplo:

{
    "type": "TooManyRequests",
    "code": "CODEBUDDY_1044_QUICK_COMMAND_RATE_LIMIT_EXCEEDED",
    "details": "Maximum number of requests reached. Your limit is 100 requests in the last 1440 minutes"
}

Aguarde até que o limite de tempo tenha expirado antes de usar o Remote Quick Command novamente.

  1. Credencial de Serviço: se você usar uma Credencial de Serviço para a Conta, você tem um limite de 20 requisições por minuto e até 6.000 requisições diárias.

Apenas Account Holders podem criar Credenciais de Serviço e o limite é para toda a Conta.

Compartilhar o seu Quick Command

Você pode compartilhar um Quick Command que criou com outras pessoas usuárias. Isso permitirá o uso direto dentro das IDEs da Conta.

  • Na tela de 'Quick Commands' clique no botão 'Compartilhar'.

Vídeo: Como criar um Remote Quick Command

Próximos Passos