JSONPlaceholder

JSONPlaceholder é um site que contém uma série de rotas de API que retornam informações fictícias sobre pessoas fictícias. É uma ótima ferramenta de teste para chamadas de API e, neste exemplo de uso de competências, veremos como criar um agente capaz de recuperar informações sobre uma pessoa utilizando esta API.

Sobre a criação do Agente

Os passos para criação do agente que vai comportar nossas habilidades já são abordados detalhadamente na aba de Tutoriais, portanto estes exemplos se iniciam com o agente já criado e utilizando o modelo "INTELLI-3.5-Turbo-16K", devido à sua janela mais vasta de tokens, o que permite lidar com a potencial quantidade de tokens no retorno de uma API.

Criando a habilidade

Para iniciar o processo de criação, precisamos criar uma nova lista de competências ou encontrar uma já criada. Tendo a lista de competências, podemos criar a habilidade de fazer chamadas de API clicando em "Habilidades" e em "+ Criar Habilidade", que nos levará ao menu de criação de habilidades.

No menu de criação de habilidades, insira as seguintes informações:

• Nome da habilidade - API de usuários.

• Descrição - Sempre que receber qualquer pegunta sobre usuário, deve seguir suas instruções. Perguntar qual o id do usuario que precisa de informação e então fazer a consulta no endpoint. Use o id informado para consultar o endpoint.

• Instrução:

Para obter informações sobre o usuário, siga as instruções a seguir.
Você vai solicitar o id e seguir as etapas a seguir:
    ```fetch
    GET https://jsonplaceholder.org/users?id={id}
    Accept: application/json
    ```
O parâmetro {id} pode ser qualquer numero inteiro, por exemplo:
    ```fetch
    https://jsonplaceholder.org/users?id=2
    Accept: application/json
    ```
Onde 2 será o valor substituído pelo id informado.

Coloque a informação solicitada em negrito seguindo o formato markdown.

Feito isso, salve as informações. Agora já é possível utilizar essa habilidade.

Como funciona a chamada para a API

É possível simular a chamada para essa API e observar o que ela retorna utilizando as mesmas regras que passamos ao agente e com a ajuda de um navegador de internet.

Para realizar a chamada de API, copie o endpoint informado ao agente e cole-o na barra de endereço da URL, substituindo {id} por um número (imagem 1). Utilizaremos id=3 para esse exemplo e, mais à frente, pediremos ao agente para retornar as informações com esse mesmo id a fim de realizar uma validação dos dados retornados.

Imagem 1: Resultado da chamada de API com parâmetro ID 2, realizada em um navegador de internet

O que esperar do retorno

Ao requisitar que o agente faça a chamada, é muito importante observar o tamanho da resposta, já que a maioria das APIs têm os dados retornado em formato JSON. Isso pode ser um problema ao lidar com a quantidade de tokens, já que a identação (espaçamento) do formato JSON consome tokens e, caso o limite de tokens por interação seja excedido, o agente pode não responder ou dar um resposta incompleta.

Abaixo (imagem 2), está uma representação da separação de tokens realizada na resposta que obtivemos com a chamada de API realizada acima.

Imagem 2: "Tokenização" do resultado da chamada de API em formato JSON

Perceba que os espaços em branco resultantes da identação contam como tokens individuais, portanto uma resposta em JSON que contém muitos campos aninhados pode comprometer a resposta da IA.

Resultados

Agora, vamos pedir que o agente faça a chamada e nos traga informações específicas sobre o usuário com id 3.

Atenção! O número passado ao parâmetro id foi escolhido arbitrariamente, portanto ao reconstruir esse exemplo, recomendamos que experimente com outros IDs.

Primeiro, encontramos nosso agente na listagem de Agentes e clicamos em "Conversar". Ao chegar à janela de chat, podemos requisitar que seja feita a chamada (imagem 3).

Imagem 3: Resultado da chamada que o agente fez à API que especificamos.

Ao comparar os dados, podemos concluir que a chamada foi feita corretamente, já que o agente nos trouxe exatamente as mesmas informações que obtivemos ao fazer a chamada de API diretamente.