Pular para o conteúdo principal

Criar Toolkits

Você pode integrar suas ferramentas com a StackSpot AI utilizando especificações OpenAPI ou Swagger. Ao fazer isso, suas APIs ficam disponíveis para os Agentes da StackSpot AI, permitindo que eles interajam diretamente com sistemas externos e qualquer API HTTP.

Essa integração expande as capacidades dos Agentes, possibilitando que eles busquem informações em tempo real e realizem ações além das funcionalidades nativas do modelo de linguagem.

Por que usar essa integração?

Registrar suas APIs com OpenAPI/Swagger permite que os Agentes se conectem a serviços externos, acessem dados atualizados e automatizem tarefas complexas. Isso garante que seus Agentes possam fornecer respostas mais precisas e lidar com cenários avançados que exigem informações em tempo real ou operações personalizadas.

Criar Toolkit

O Toolkit reúne todas as ferramentas em um só lugar. Você pode criar Ferramentas personalizadas para atender às necessidades específicas do seu projeto.

Siga as etapas a seguir para criá-las:

Passo 1. Acesse o Portal da StackSpot AI;

Passo 2. Clique na seção Toolkit;

Passo 3. Clique no botão ‘Criar Toolkit‘. Adicione as seguintes informações:

  • Nome: adicione um nome para o Toolkit.
  • Descrição do Toolkit: descreva o objetivo do seu Toolkit.
  • Logo do Toolkit: adicione um logo (Opcional).

Em seguida, clique no botão ‘Criar‘.

Passo 4. Configure as funções da sua Ferramenta. Depois, clique no botão ‘Adicionar Ferramentas‘;

Passo 5. Você tem duas opções para registrar suas Ferramentas:

Opção 1. Fazer upload de arquivos: Swagger/OpenAPI

Siga as instruções para adicionar uma Ferramenta que faz requisições para o endpoint desejado:

Cuidado!

Esta opção está disponível apenas para serviços com acesso à internet.

  1. Clique para soltar arquivos ou procure pelos arquivos;
  2. Escolha seu arquivo OpenAPI YAML;
  3. A StackSpot AI processa os arquivos;
  4. Para cada endpoint presente no seu Swagger, a StackSpot AI cria uma Ferramenta. Essas Ferramentas são serviços, e você conseguirá acessar:
    • Nome da Ferramenta
    • Método: GET, POST, DELETE
    • Descrição da Ferramenta
    • URL
    • Parâmetros: você pode adicionar os parâmetros de entrada para chamar o serviço desejado.

A sintaxe segue a convenção OpenAPI. Os tipos de parâmetros podem ser:

  • Header: um parâmetro enviado nos headers do HTTP

  • Path: um parâmetro incluído no caminho da URL

  • Query: um parâmetro anexado à URL após o ?

  • Exemplo de query para URL /states?size={size_number}:


parameters:
  - in: query
    name: size
    schema:
      type: integer

  • Path da URL /users/{id}:

  parameters:
        - name: id
          in: path
          description: User ID
          required: true

  • Header:

     parameters:
        - in: header
          name: Content-Type
          schema:
            type: string
          required: true

Para mais detalhes sobre a sintaxe, confira a documentação da OpenAPI.

A sintaxe segue a convenção OpenAPI. Pode ser em formato JSON.

  • Corpo da requisição:
requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - age
              properties:
                name:
                  type: string
                age:
                  type: integer
                  format: int32
                breed:
                  type: string

Para mais detalhes sobre a sintaxe, confira a documentação da OpenAPI.

Opção 2. Adicionar manualmente

Você pode adicionar os endpoints manualmente, preenchendo as informações a seguir:

  • Nome: informe um nome para a ferramenta;
  • Descrição da Ferramenta: explique de qual é a função da sua ferramenta. Este campo é importante porque ajuda o Agente a decidir se deve ou não usar essa ferramenta em determinadas situações.
  • Método HTTP: selecione o método HTTP (GET, POST, PUT, DELETE, etc.) que será utilizado;
  • URL do endpoint: indique a URL que será chamada para executar a função;
  • Parâmetros: liste os parâmetros aceitos pela função, informando:

Exemplo:

Notas:
O campo "in" define a localização do parâmetro (path, header, query, etc.).
O campo "schema" define o tipo do parâmetro conforme o OpenAPI 3.0.
Todos os campos seguem a estrutura esperada pela Especificação OpenAPI.

Exemplo de preenchimento dos parâmetros da Tool.
  [
    {
      "name": "userId",
      "in": "path",
      "description": "ID do usuário",
      "required": true,
      "schema": {
        "type": "integer"
      }
    },
    {
      "name": "X-Request-Id",
      "in": "header",
      "description": "Identificador único da requisição",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "active",
      "in": "query",
      "description": "Filtra usuários ativos",
      "required": false,
      "schema": {
        "type": "boolean"
      }
    }
  ]
  • Corpo da Requisição: descreva a estrutura do corpo da requisição, caso necessário. Inclua os campos, tipos (por exemplo, string, integer, object) e explique a finalidade de cada um. Use este campo para definir o payload em requisições POST, PUT ou PATCH.

Exemplo:

Notes:
name (string): nome completo do usuário (obrigatório).
email (string, formato email): endereço de e-mail do usuário (obrigatório).
age (integer): idade do usuário (opcional).

TEste exemplo pode ser usado como valor do campo requestBody em uma operação POST, PUT ou PATCH na sua especificação OpenAPI.
{
  "description": "Payload to create a new user",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "User's full name."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "User's email address."
          },
          "age": {
            "type": "integer",
            "description": "User's age."
          }
        },
        "required": ["name", "email"]
      }
    }
  }
}
Dica!

Preencha todos os campos com atenção para garantir que a integração funcione corretamente.

Confira o exemplo a seguir:

5. Habilite a transformação da resposta: Os Large Language Models (LLMs) possuem uma janela de contexto que determina o número de tokens que você pode enviar para eles.

Alguns serviços retornam respostas com grande volume de informações; por exemplo, agregar notícias do Google pode gerar mais dados do que o seu limite de tokens permite. Para resolver isso, ao habilitar essa opção, a StackSpot AI utiliza Jinja para condensar a resposta extensa em um tamanho mais gerenciável, garantindo que você não exceda seus limites de tokens.

Habilite essa opção para que os modelos recebam a resposta transformada. Você também pode visualizar os valores transformados nos passos detalhados.

  • Confira um exemplo a seguir:
status_code: int
"headers": dict[string, string]
"raw_data": string
"json": dict[string, any]
  • Exemplo do corpo da resposta da API:
{
"id": 1,
"name": "Stackspot",
"order": 4,
"foo": "bar"
}

Quando a resposta da API for bem-sucedida (status 200), você pode simplificar o processo utilizando apenas o campo order do JSON de resposta.


{% if response.status_code == 200 %}{{ response.json.order }}{% else %}Error: {{ response.raw_data }}{% endif %}

Para mais detalhes sobre Jinja, acesse a página Jinja no Toolkit.

Passo 6. A maioria dos serviços precisa de autenticação, então clique no botão ‘Autenticação’ e siga as instruções.

Você pode escolher uma Secret existente ou criar uma nova. Clique para aprender os passos

Escolhendo uma Secret existente

  1. Na seção Autenticação, clique no botão Secret;
  2. Escolha Organização ou Pessoal para o Local de Armazenamento da Secret;
  3. Selecione o Tipo de Credencial (API Key, Client Credentials ou Key/Value) e, em seguida, escolha o nome da Secret.

Criar uma Secret

Passo 1. Adicione o Local de Armazenamento da Secret:

  • Escolha Organização para uma Secret da sua empresa;
  • Pessoal para uma Secret de uso individual.

Passo 2. Escolha o Tipo de Credencial e adicione as seguintes informações:

  • API Key

    • Adicione um nome para a Secret;
    • Adicione o nome e o valor do header;
    • Adicione uma data de expiração (opcional).

  • Client Credentials (OAuth)

    • Adicione a URL;
    • Adicione o Client ID;
    • Adicione o Client Secret;
    • Adicione os Scopes (opcional).

O uso de Client Credentials permite autenticação interna segura no endpoint. Ao selecionar a Secret, você receberá tanto o token de autorização quanto o de acesso.

  • Key/Value
    • Adicione um nome;
    • Adicione a chave (Key) e o valor (Value);
    • Adicione a data de expiração (opcional).

Passo 3. Clique no botão 'Criar e adicionar'.

Passo 7. Depois de registrar o Toolkit com suas Ferramentas, você pode acessar a seção de Agentes e escolher a partir da aba Pessoal;

Atenção!

Você não precisa selecionar o Toolkit inteiro; a ideia é ser mais assertivo adicionando apenas as ferramentas essenciais para seus Agentes. A StackSpot AI recomenda não utilizar mais do que 20 ferramentas.

Vídeo: Como criar Toolkit