1. Apresentando o API de Assistentes da OpenAI

1.1 Definição e Propósito do API de Assistentes

O API de Assistentes permite que desenvolvedores construam assistentes de inteligência artificial dentro de suas próprias aplicações. Ao definir comandos personalizados e selecionar modelos, os assistentes podem usar modelos, ferramentas e conhecimento para responder às consultas dos usuários. Atualmente, o API de Assistentes suporta três tipos de ferramentas: Interpretador de Código, Recuperação e Chamada de Função.

1.2 Aplicações do API de Assistentes

O API de Assistentes é adequado para vários cenários que requerem suporte interativo de IA. Por exemplo:

  • Suporte ao Cliente: Responder automaticamente a perguntas comuns para reduzir a carga de trabalho do atendimento ao cliente humano.
  • Educação Online: Responder às perguntas dos alunos e fornecer suporte de aprendizado personalizado.
  • Análise de Dados: Analisar arquivos de dados enviados pelos usuários, gerar relatórios e visualizar gráficos.
  • Recomendações Personalizadas: Fornecer sugestões e serviços personalizados com base nas interações históricas dos usuários.

1.3 Conceitos Principais dos Assistentes

Os objetos principais do API de Assistentes incluem Assistente, Thread e Mensagem. Aqui estão introduções detalhadas sobre esses objetos e suas funções:

Assistente

O objeto Assistente é construído em cima dos modelos da OpenAI e pode chamar ferramentas de assistentes de IA. Você pode personalizar as instruções do Assistente para adaptar sua personalidade e funcionalidade. Por exemplo, você pode criar um Assistente chamado "Analista de Dados" que analisa dados e gera gráficos usando a ferramenta "code_interpreter".

Thread

O objeto Thread representa a sessão de conversação entre o usuário e o Assistente. Você pode criar um Thread para cada usuário e adicionar mensagens a ele quando o usuário interage com o Assistente. O objeto Thread armazena efetivamente o histórico de mensagens e trunca as mensagens quando necessário para cumprir o limite de comprimento do contexto do modelo.

Mensagem

O objeto Mensagem pode ser criado pelo usuário ou pelo Assistente. As mensagens podem conter texto, imagens e outros arquivos. As mensagens são armazenadas como uma lista no Thread. No uso real do API, os desenvolvedores podem adicionar mensagens do usuário ao Thread e acionar a resposta do Assistente conforme necessário.

Execução

O objeto Execução representa a execução de uma solicitação de assistente, chamando o assistente com base no conteúdo da mensagem no Thread. O assistente utiliza sua configuração e as mensagens do Thread para executar tarefas chamando modelos e ferramentas. Como parte da execução, o assistente acrescenta mensagens ao thread.

2. Processo de Desenvolvimento do API de Assistentes

2.1 Criar seu Assistente

Para criar um Assistente, você precisa enviar uma solicitação para o API com instruções, nome do modelo e configuração da ferramenta. Aqui está um exemplo simples de criar um assistente pessoal de matemática:

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Você é um tutor pessoal de matemática. Escreva e execute o código para responder a perguntas de matemática.",
    "name": "Tutor de Matemática",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4"
  }'

Parâmetros do API:

  • instructions - instruções do sistema dizendo ao assistente o que fazer.
  • name - o nome do assistente.
  • tools - define quais ferramentas o assistente pode usar. Cada assistente pode ter até 128 ferramentas. Os tipos de ferramentas atuais podem ser code_interpreter, retrieval ou function.
  • model - qual modelo o assistente deve usar?

Após criar o Assistente com sucesso, você receberá um ID de Assistente.

2.2 Criar um Thread de Sessão

Um Thread representa uma conversa, e recomendamos criar um Thread de sessão para cada usuário quando eles iniciam uma conversa. Você pode criar um Thread da seguinte forma:

curl https://api.openai.com/v1/threads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d ''

Após criar o Thread, você receberá um ID de Thread.

2.3 Adicionar Mensagens ao Tópico

Você pode adicionar mensagens a um Tópico específico, contendo texto e, opcionalmente, permitindo o envio de arquivos pelo usuário. Por exemplo:

curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SUA_CHAVE_DA_API_OPENAI" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "Preciso resolver esta equação `3x + 11 = 14`. Você pode me ajudar?"
    }'

Parâmetros da API:

  • thread_id - representa o ID do tópico da conversa, que você pode obter ao criar o Tópico.

O corpo da requisição da API é uma mensagem do usuário, geralmente representando a pergunta do usuário, semelhante à estrutura da mensagem do modelo de conversa.

2.4 Executar o Assistente para Gerar uma Resposta

Para fazer o assistente responder às mensagens do usuário, você precisa criar um Run. Isso permite que o assistente leia o Tópico e decida se deve usar ferramentas (se estiverem habilitadas) ou simplesmente usar o modelo para responder melhor à consulta.

Nota: Até este ponto, o assistente não respondeu à pergunta do usuário. Apenas quando você chama a API Run é que o assistente de IA responderá à pergunta do usuário.

curl https://api.openai.com/v1/threads/{thread_id}/runs \
  -H "Authorization: Bearer SUA_CHAVE_DA_API_OPENAI" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "id_do_assistente",
    "instructions": "Trate o usuário como Jane Doe. O usuário é uma conta premium."
  }'

Parâmetros da API:

  • thread_id - representa o ID do tópico da conversa, que você pode obter ao criar o Tópico.
  • assistant_id - representa o ID do assistente, que você pode obter ao criar o Assistente.
  • instructions - instruções do assistente que podem substituir as instruções definidas ao criar o Assistente.

Uma solicitação bem-sucedida da API irá retornar um ID de Run.

2.5 Verificar Status da Execução do Assistente

Após iniciar uma tarefa (Run) no Assistente, a execução da tarefa é assíncrona. Isso significa que precisamos verificar regularmente o status da Run para determinar se ela foi concluída. Para verificar o status da Run, uma solicitação HTTP pode ser feita usando o CURL. Abaixo está uma introdução específica a este processo.

Exemplo de Solicitação CURL:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Explicação dos Parâmetros da API:

  • https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123: Este é o URL de solicitação da API, onde thread_abc123 é o identificador exclusivo do tópico (Thread), e run_abc123 é o identificador exclusivo da Run.

Exemplo de Corpo da Resposta:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "completed",
  "created_at": 1699073585,
  ...
}

Explicação dos Parâmetros de Resposta da API:

  • id: O identificador exclusivo da Run.
  • object: Indica o tipo do objeto retornado, que é thread.run aqui.
  • status: O status da Run, os valores possíveis incluem queued, em_progresso, completado, requer_ação, falhou, etc.
  • created_at: O carimbo de data/hora de quando a Run foi criada.

2.6 Obter Resultados da Resposta do Assistente

Após a conclusão da Execução do Assistente, podemos ler os resultados da resposta do Assistente verificando as mensagens adicionadas ao tópico (Thread). Abaixo está uma demonstração de como fazer a solicitação através do CURL e uma explicação detalhada dos parâmetros da API.

Dica: Similar a uma conversa com um Assistente, quando o Assistente termina de processar a pergunta do usuário, o Assistente anexará uma mensagem ao tópico da conversa (Thread). Portanto, só precisamos consultar a última mensagem no tópico da conversa (Thread) para obter a resposta do Assistente.

Exemplo de Solicitação CURL:

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Explicação dos Parâmetros da API:

  • https://api.openai.com/v1/threads/thread_abc123/messages: O URL de solicitação da API, onde thread_abc123 é o identificador único do tópico (Thread).
  • Igual aos cabeçalhos de solicitação usados para verificar o status da Execução anterior, incluindo informações de autenticação e informações da versão da API.

Exemplo de Resultados da Resposta do Assistente:

Neste exemplo, o usuário fez uma pergunta de matemática ao Assistente, e o Assistente adicionou uma Mensagem de resposta ao Tópico após processá-la.

Usuário: Eu preciso resolver a equação `3x + 11 = 14`. Você pode me ajudar?
Assistente: Claro, Jane Doe. Para resolver a equação `(3x + 11 = 14)`, você precisa isolar o `(x)` de um lado da equação. Deixe-me calcular o valor de `(x)` para você.
Assistente: A solução da equação `(3x + 11 = 14)` é `(x = 1)`.

Após obter os resultados da resposta do Assistente, pode ser apresentado ao usuário para ajudá-los a entender e utilizar melhor os serviços fornecidos pelo Assistente.

3. Ferramentas: Ferramentas Integradas Fornecidas pela OpenAI

3.1 Ferramenta de Interpretação de Código

A ferramenta de Interpretação de Código permite que a API do Assistente escreva e execute código Python em um ambiente de execução isolado. Esta ferramenta pode lidar com vários formatos de dados e arquivos e gerar arquivos com dados e imagens gráficas. O Interprete de Código permite que seu Assistente execute iterativamente o código para resolver problemas complexos de codificação e matemáticos. Quando o código escrito pelo Assistente falha ao executar, ele pode iterar este código tentando diferentes códigos até que o código execute com sucesso.

Habilitando o Interprete de Código

Para habilitar o Interprete de Código, passe code_interpreter no parâmetro tools ao criar o objeto do Assistente:

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Você é um tutor de matemática pessoal. Quando questionado sobre uma questão de matemática, escreva e execute código para respondê-la.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-turbo-preview"
  }'

Então, o modelo decidirá quando invocar o Interprete de Código em tempo de execução com base na natureza da solicitação do usuário. Você pode facilitar esse comportamento por meio das instruções do Assistente (por exemplo, "Escreva código para resolver este problema").

Utilizando o Interprete de Código para Processar Arquivos

O Interprete de Código pode analisar dados de arquivos. Isso é útil quando você deseja fornecer uma grande quantidade de dados ao Assistente ou permitir que seus usuários façam upload de seus próprios arquivos para análise. Observe que os arquivos carregados para o Interprete de Código não serão indexados para recuperação. Para informações detalhadas sobre como indexar arquivos para recuperação, consulte a seção Ferramenta de Recuperação abaixo.

Arquivos passados ao nível do Assistente podem ser acessados por todas as Execuções associadas a este Assistente:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/mydata.csv"

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Você é um tutor de matemática pessoal. Quando questionado sobre uma questão de matemática, escreva e execute código para respondê-la.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

Leitura de Imagens e Arquivos Gerados pelo Interpretador de Código

O Interpretador de Código também pode gerar arquivos na API, como a geração de gráficos de imagem, arquivos CSV e PDF. Existem dois tipos de arquivos gerados: imagens e arquivos de dados (por exemplo, um arquivo CSV com dados gerados pelo Assistente).

Quando o Interpretador de Código produz uma imagem, você pode encontrar e baixar esse arquivo no campo file_id da resposta de mensagem do Assistente:

{
    "id": "msg_abc123",
    "object": "thread.message",
    "created_at": 1698964262,
    "thread_id": "thread_abc123",
    "role": "assistant",
    "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "file-abc123"
      }
    }
  ]
  // ...
}

3.2 Ferramenta de Recuperação

A Ferramenta de Recuperação aprimora as capacidades do Assistente adicionando conhecimento de fora do modelo (como informações de produto proprietárias ou documentos fornecidos pelo usuário). Uma vez que o arquivo é carregado e passado para o Assistente, a OpenAI automaticamente fatiará, indexará, armazenará embeddings do seu documento e implementará busca vetorial para recuperar conteúdo relevante para responder às consultas do usuário.

Habilitar Recuperação

Para habilitar a recuperação no parâmetro tools do Assistente, passe retrieval:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Você é um chatbot de suporte ao cliente. Use sua base de conhecimento para responder às consultas dos clientes de forma eficaz.",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
  }'

Enviar Arquivos para Recuperação

Assim como no Interpretador de Código, os arquivos podem ser carregados no nível do Assistente ou nos níveis individuais de Mensagem.

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/caminho/para/conhecimento.pdf"

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Você é um chatbot de suporte ao cliente. Use sua base de conhecimento para responder às consultas dos clientes de forma eficaz.",
    "name": "Tutor de Matemática",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
    "file_ids": ["file_123abc456"]
  }'

3.3 Ferramenta de Chamada de Função

Assim como a API de Completude de Conversas, a API de Assistentes suporta a chamada de funções. A chamada de função permite que você descreva funções para o Assistente e retorne de forma inteligente a função a ser chamada juntamente com seus parâmetros. Quando uma chamada de função é executada, a API de Assistentes pausará a execução, e você pode fornecer o resultado da chamada da função para continuar a execução.

Definir Funções

Ao criar um Assistente, você pode definir um conjunto de funções para o assistente chamar. Essas funções precisam ser explicitamente especificadas ao criar o objeto do assistente. Cada função deve ter um nome único, descrição e especificação de parâmetros.

O código a seguir demonstra como definir duas funções usando o comando curl ao criar um assistente:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Você é um bot de previsão do tempo. Use as funções fornecidas para responder perguntas.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "getCurrentWeather",
        "description": "Obtenha as condições meteorológicas para uma localização específica",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Cidade e estado, por exemplo, São Francisco, CA"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "getNickname",
        "description": "Obtenha o apelido de uma cidade",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Cidade e estado, por exemplo, São Francisco, CA"}
          },
          "required": ["location"]
        }
      }
    }],
    "model": "gpt-4-turbo-preview"
  }'

Lendo as funções chamadas pelo Assistente

Quando um usuário envia uma mensagem para o assistente e o conteúdo da mensagem aciona uma chamada de função, você precisa ler as informações dessa chamada de função. Durante esse processo, o assistente gerará um run com status requires_action. Neste ponto, você pode recuperar o objeto Run para obter informações detalhadas sobre a chamada da função.

Aqui está um exemplo de como recuperar o objeto Run, mostrando como obter as informações das chamadas de função:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "getCurrentWeather",
            "arguments": "{\"location\":\"São Francisco\"}"
          }
        },
        {
          "id": "call_abc456",
          "type": "function",
          "function": {
            "name": "getNickname",
            "arguments": "{\"location\":\"Los Angeles\"}"
          }
        }
      ]
    }
  },
  ...
}

O parâmetro tool_calls contém as informações da chamada da função, e você só precisa chamar a função correspondente em seu programa local.

Enviando saídas de função

Após executar a chamada da função localmente e obter os resultados, você precisa enviar esses resultados para o assistente Assistants para que o assistente possa continuar processando a solicitação do usuário. Ao enviar as saídas da função, você precisa garantir que as saídas estejam associadas às chamadas de função originais.

Aqui está um exemplo de como enviar os resultados de saída da função:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_123/submit_tool_outputs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_abc123",
        "output": "{\"temperatura\": \"22\", \"unidade\": \"celsius\"}"
      }, 
      {
        "tool_call_id": "call_abc456",
        "output": "{\"apelido\": \"LA\"}"
      }
    ]
  }'

Explicação dos parâmetros:

  • thread_abc123 representa o ID do thread de conversação
  • run_123 representa o ID do objeto Run
  • tool_call_id representa o ID de uma chamada de função específica, que é obtido do parâmetro tool_calls anterior.

Ao enviar com sucesso todas as saídas da função, o status do objeto Run será atualizado novamente, e o assistente continuará processando e retornará a resposta final ao usuário.