Pular para o conteúdo principal

Agentes API

A StackSpot AI oferece uma API que permite acionar diretamente um Agente e receber respostas via Server-Sent Events (SSE) ou REST. Com essa funcionalidade, você pode:

  • Utilizar a API de qualquer sistema, serviço ou pipeline.
  • Fazer chamadas autenticadas usando um Personal Access Token (PAT) ou uma Credencial de Serviço.
  • Obter respostas de uma LLM usando os vários recursos de enriquecimento da StackSpot AI.

Quando usar Agents API?

  • Para integrar um Agente StackSpot AI em outros sistemas, aplicações ou automações.
  • Para acionar Agentes em fluxos de CI/CD, pipelines ou esteiras de desenvolvimento.
  • Para criar integrações personalizadas, recebendo respostas contextualizadas no seu ecossistema.
Informação Adicional

Todas as configurações do seu Agente são consideradas nas chamadas feitas pela API, como por exemplo LLM, Knowledge Source, etc.

Como integrar a Agents API

Pré-requisitos

Dica!
  • Depois de gerar o seu token (PAT ou Credencial de Serviço), você pode reutilizá-lo sempre que precisar executar integrações via API na StackSpot AI. Não é necessário criar um novo token a cada uso.

No Portal da StackSpot

Passo 1. Acesse e faça login no Portal da StackSpot AI;

Passo 2. Na seção 'Contents', clique em 'Agentes' e selecione o seu Agente. Acesse a aba API Usage;

Se você ainda não criou um Agente, confira como criar.

Passo 3. Você irá visualizar os exemplos de código prontos para uso. Habilite os parâmetros conforme a sua necessidade:

  • Streaming: recebe as respostas em tempo real.
  • Return Knowledge Sources: inclui os IDs do Knowledge Sources usados nas respostas.
  • Upload arquivos: para adicionar os seus arquivos no chat que gera IDs desses arquivos e os insere no snippet no Portal - demonstrando como você pode fazer seus requests aos Agentes e também utilizar upload de arquivos.
Dica!

A StackSpot AI gera scripts apenas em shell script por padrão. Se você precisar do script em outra linguagem, basta pedir para a StackSpot AI converter para a linguagem desejada.

Passo 4. Copie o código gerado e utilize-o na sua aplicação para fazer a integração.

Exemplo via API

  • Exemplo de Requisição:
curl -X POST "{{agent-app-url}}/v1/agent/{{agentId}}/chat" \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "streaming": true,
       "user-prompt": "What is an API?",
       "stackspot_knowledge": "true",
       "return_ks_in_response": false
     }'
  • Exemplo de Resposta:
{
  "message": "Uma API (sigla para Application Programming Interface) é um conjunto de regras e definições que permitem que diferentes sistemas, aplicações ou componentes de software se comuniquem entre si.",
  "stop_reason": "stop",
  "tokens": {
    "user": 8,
    "enrichment": 3083,
    "output": 413
  }
}
  • Campos da resposta: stop_reason: indica o motivo pelo qual a resposta foi finalizada. Esse campo é útil quando você utiliza respostas em streaming. No exemplo apresentado, o streaming não foi usado, por isso o campo aparece primeiro na resposta.
  • tokens: mostra o consumo de tokens na requisição, detalhado em três partes:
    • user: quantidade de tokens usados para processar o prompt enviado.
    • enrichment: tokens utilizados para enriquecer a resposta, como buscas em Knowledge Sources.
    • output: Tokens gastos para gerar a resposta final do Agente.

Exemplo via API com conversation_id

conversation_id: se o parâmetro use_conversation for definido como true, a resposta irá retornar um conversation_id. Este ID mantém o contexto da conversa para as próximas interações.

  • Request:
curl -X POST "{{agent-app-url}}/v1/agent/{{agentId}}/chat" \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "streaming": true,
       "user-prompt": "What is an API?",
       "stackspot_knowledge": "true",
       "return_ks_in_response": false
       "use_conversation": true
     }'
  • Exemplo da response:
{
  "message": "An API (short for Application Programming Interface) is a set of rules and definitions that allow different systems, applications, or software components to communicate with each other.",
  "stop_reason": "stop",
  "tokens": {
    "user": 8,
    "enrichment": 3083,
    "output": 413
  },
    "upload_ids": {},
    "knowledge_source_id": [],
    "source": [],
    "cross_account_source": [],
    "tools_id": [],
    "conversation_id": "01K9T3D5752EMVMDJTSEW536AP"
}

  • Inclua o conversation_id na sua próxima requisição para manter o contexto, confira o exemplo a seguir:

  • Request:

curl -X POST "{{agent-app-url}}/v1/agent/{{agentId}}/chat" \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "streaming": true,
       "user-prompt": "And what are the types?",
       "stackspot_knowledge": "true",
       "return_ks_in_response": false
       "use_conversation": true,
       "conversation_id": "01K9T3D5752EMVMDJTSEW536AP"
     }'
  • Resposta:
{
  "message": "1. Web APIs: Enable communication between servers and clients using protocols like HTTP/HTTPS, commonly used in web applications and online services. 2. Operating System APIs: Allow applications to interact with the operating system, such as Windows APIs or POSIX for Unix/Linux systems. 3. Library or Framework APIs: Provide specific functionalities of a library or framework, like jQuery APIs in JavaScript or TensorFlow APIs in Python. 4. Hardware APIs: Facilitate interaction with hardware devices, enabling applications to control peripherals like printers and cameras. 5. Database APIs: Allow applications to access and manipulate data stored in a database, such as SQL or MongoDB APIs. 6. Service APIs: Used to interact with external services, such as payment APIs (Stripe, PayPal) or social media APIs (Facebook, Twitter).",
  "stop_reason": "stop",
  "tokens": {
    "user": 8,
    "enrichment": 3083,
    "output": 413
  },
    "upload_ids": {},
    "knowledge_source_id": [],
    "source": [],
    "cross_account_source": [],
    "tools_id": [],
    "conversation_id": "01K9T3D5752EMVMDJTSEW536AP"
}

Exemplo em Python com Flask API

O código a seguir é um exemplo com dois serviços, um para autenticar com a sua Conta StackSpot e outro para enviar uma mensagem para um Agente da sua Conta. Considere que a API será o "projeto-agente-api", a estrutura da API:

Estrutura do projeto
projeto-agente-api/
├── src/
│   ├── routes/
│   │   ├── stackspot_agent.py
│   │   └── stackspot_service.py
│   └── models/
├── .env
├── main.py
└── requirements.txt

Serviço de Autenticação

stackspot_auth.py
import requests

url = "https://idm.stackspot.com/{{your_account_realm}}/oidc/oauth/token"

payload = 'client_id={{client_id}}&grant_type=client_credentials&client_secret={{client_secret}}'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Key': 'Authorization',
  'Value': 'Bearer your_token'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Envio de mensagem para o Agente

stackspot_agent.py
import requests
import json

url = "https://genai-inference-app.stackspot.com/v1/agent/{{Agent-ID}}/chat"

payload = json.dumps({
  "streaming": True,
  "user_prompt": "como eu crio um app no stk cli?",
  "stackspot_knowledge": True,
  "return_ks_in_response": False
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{your_token}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Lembre-se de usar variáveis de ambiente para teste local e secrets para ambiente de produção para os dados sensíveis de autenticação na StackSpot e Autorização do Agente.

Próximo Passo