Pular para o conteúdo principal

Upload de Arquivos para Contextualizar Suas Chamadas de Agentes

API de chat com Agente

Na StackSpot AI, você pode enviar arquivos ou imagens no chat da StackSpot AI para usar em suas interações com os Agentes.

Portal

Passo 1. No Portal da StackSpot AI, acesse o Chat;

Passo 2. Clique no botão de 'Mais Opções' e selecione Upload File;

Passo 3. Escolha a imagem ou os arquivos que você desejar adicionar;

Passo 4. Agora a StackSpot AI terá o contexto do arquivo que você fez o upload para executar o mesmo no seu chat.

IDE

Passo 1. Na IDE da StackSpot AI, acesse o Chat;

Passo 2. Clique no botão de 'Mais Opções' e selecione Upload File;

Passo 3. Escolha a imagem ou os arquivos que você desejar adicionar;

Passo 4. Agora a StackSpot AI terá o contexto do arquivo que você fez o upload para executar o mesmo no seu chat.

API de upload de arquivos (para uso em Agents API)

Como fazer esse upload

Pré-requisitos

Você precisa se autenticar para utilizar essa funcionalidade. Você tem duas opções:

1. Autenticar com Credencial de Serviço

  • Devido às restrições de autenticação, o envio diretamente via API está disponível apenas para contas Enterprise.
  • Autentique-se para usar o script.

Siga os passos para autenticar na página de Credenciais de Serviço. E para mais detalhes, acesse a documentação da StackSpot EDP.

Informação Adicional

Você precisa ativar as seguintes permissões:

  • ai_dev and ai_admin.

Se você não conseguir criar uma Credencial de Serviço, entre em contato com o administrador da sua conta.

  • Copie os campos 'client id', 'client key', e 'realm' para usar como variáveis de ambiente (os dois primeiros devem ser segredos) ou no exemplo curl a parte inferior da página na seção 'como usar'. Você não poderá visualizá-los novamente.
Atenção!

Se você perder alguma delas, revogue a credencial e crie uma nova.

  • Os exemplos a seguir consideram que o token de acesso está definido como a variável de ambiente JWT. Você pode extrair isso da autenticação curl com o comando jq para obter o valor para a chave access_token do JSON retornado, depois salvá-lo como uma variável de ambiente usando o comando export, como:
export JWT=$(curl -s "https://idm.stackspot.com/$REALM/oidc/oauth/token" -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials' -d "client_id=$CLIENT_ID" -d "client_secret=$CLIENT_KEY" | jq -r '.access_token')
Dica!

Para fazer a execução da requisição, adicione o x-account-id nos headers.

Autenticar com Personal Access Token

Se você possui uma conta Freemium, faça a autenticação a seguir:

  1. No Portal da StackSpot AI, clique no seu avatar e depois em 'Meu Perfil';
  2. Na seção Token de Acesso, clique no botão 'Gerar Client Key';
  3. Copie o Client Key.

Para mais detalhes, acesse a documentação de Personal Access Token.

Como fazer a chamada da API para fazer o upload do arquivo

Exemplo de script:

file_paths=(
  "/path/to/file1.pdf"
  "/path/to/file2.pdf"
  "/path/to/file3.pdf"
)

upload_ids=()

for file in "${file_paths[@]}"; do
  upload_data=$(curl -s 'https://data-integration-api.stackspot.com/v2/file-upload/form' \
      -H 'Content-Type: application/json' \
      -H "Authorization: Bearer $JWT" \
      -d "{\"file_name\": \"$(basename "$file")\", \"target_type\": \"CONTEXT\", \"expiration\": 60 }")

  curl -s "$(jq -r '.url' <<< "$upload_data")" \
    -F "key=$(jq -r '.form.key' <<< "$upload_data")" \
    -F "x-amz-algorithm=$(jq -r '.form["x-amz-algorithm"]' <<< "$upload_data")" \
    -F "x-amz-credential=$(jq -r '.form["x-amz-credential"]' <<< "$upload_data")" \
    -F "x-amz-date=$(jq -r '.form["x-amz-date"]' <<< "$upload_data")" \
    -F "x-amz-security-token=$(jq -r '.form["x-amz-security-token"]' <<< "$upload_data")" \
    -F "policy=$(jq -r '.form.policy' <<< "$upload_data")" \
    -F "x-amz-signature=$(jq -r '.form["x-amz-signature"]' <<< "$upload_data")" \
    -F "file=@$file"

  upload_ids+=("$(jq -r '.id' <<< "$upload_data")")
done

Utilize o script para fazer a integração de onde você precisa utilizar essa API; por exemplo, um GitHub Actions, Postman, etc.

Exemplo

Confira um exemplo de uma integração via terminal:

  1. Abra o terminal e faça o credenciamento com JWT.
  2. Execute o comando:

 echo$JWT

  1. Execute o script que a StackSpot AI retornou (esse é um exemplo com duas imagens):

# Authenticate
export JWT=$(curl -s "https://idm.stackspot.com/$REALM/oidc/oauth/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_KEY" | jq -r '.access_token')

# Upload files and keep their ids
file_paths=(
  '/home/user/Pictures/StackSpot.png'
  '/home/user/Pictures/StackSpot.jpg'
)

upload_ids=()

for file in "${file_paths[@]}"; do
  upload_data=$(curl -s 'https://data-integration-api.stackspot.com/v2/file-upload/form' \
      -H 'Content-Type: application/json' \
      -H "Authorization: Bearer $JWT" \
      -d "{\"file_name\": \"$(basename "$file")\", \"target_type\": \"CONTEXT\", \"expiration\": 60 }")

  curl -s "$(jq -r '.url' <<< "$upload_data")" \
    -F "key=$(jq -r '.form.key' <<< "$upload_data")" \
    -F "x-amz-algorithm=$(jq -r '.form["x-amz-algorithm"]' <<< "$upload_data")" \
    -F "x-amz-credential=$(jq -r '.form["x-amz-credential"]' <<< "$upload_data")" \
    -F "x-amz-date=$(jq -r '.form["x-amz-date"]' <<< "$upload_data")" \
    -F "x-amz-security-token=$(jq -r '.form["x-amz-security-token"]' <<< "$upload_data")" \
    -F "policy=$(jq -r '.form.policy' <<< "$upload_data")" \
    -F "x-amz-signature=$(jq -r '.form["x-amz-signature"]' <<< "$upload_data")" \
    -F "file=@$file"

  upload_ids+=("$(jq -r '.id' <<< "$upload_data")")
done

# Chat with this agent
curl 'https://genai-inference-app.stackspot.com/v1/agent/01JS0SSFDKPYXATPQ1J9RAW3B2/chat' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $JWT" \
  -d "{
      \"streaming\": false,
      \"user_prompt\": \"Quais informações estão contidas nessas imagens?\",
      \"stackspot_knowledge\": false,
      \"return_ks_in_response\": true,
      \"upload_ids\": $(jq -c -n '$ARGS.positional' --args "${upload_ids[@]}")
  }"
  1. Execute o comando a seguir para salvar os IDs no array:

echo$upload_ids

A resposta é o ID dos arquivos ou imagens:


> echo $upload_ids
01JFAKEIDEXAMPLE

> echo ${upload_ids[@]}
02XFAKEIDEXAMPLE 01XFAKEIDEXAMPLE


  1. Utilize esse upload_ids retornados para fazer as requisições da API.