Criando Assistants com a API da OpenAI

Se você está começando a explorar o mundo da Inteligência Artificial (IA) e quer entender como criar assistentes poderosos utilizando a API da OpenAI, você está no lugar certo! Neste tutorial, vamos abordar o que são os Assistants da OpenAI, como utilizá-los e como eles podem simplificar o desenvolvimento de aplicações de IA. Vamos lá!

O que são os Assistants da OpenAI?

Os Assistants da OpenAI são uma funcionalidade lançada no final de 2023 que permite criar assistentes de IA capazes de realizar uma variedade de tarefas complexas. Diferentemente dos modelos de linguagem tradicionais, os Assistants vêm equipados com ferramentas pré-construídas que podem ser utilizadas automaticamente, tornando o desenvolvimento mais ágil e eficiente.

Principais características dos Assistants

• Persistência: uma vez criado, um Assistant fica sempre disponível para acesso, a menos que seja deletado, mantendo suas configurações e instruções;
• Ferramentas pré-construídas: os Assistants podem acessar várias ferramentas em paralelo, incluindo aquelas hospedadas pela OpenAI;
• Threads persistentes: simplificam o desenvolvimento ao armazenar automaticamente o histórico de mensagens e gerenciar o contexto da conversa, truncando quando necessário.

Ferramentas disponíveis nos Assistants da OpenAI

Os Assistants da OpenAI oferecem três ferramentas principais que podem ser utilizadas simultaneamente:

1. Code Interpreter

O Code Interpreter é um recurso avançado capaz de interpretar e executar código Python conforme instruções em linguagem natural. Ele pode:

• Escrever e executar código para resolver problemas matemáticos e científicos;
• Explicar códigos existentes e traduzir entre linguagens de programação;
• Processar e analisar dados de arquivos;
• Gerar visualizações e gráficos;
• Realizar cálculos complexos e simulações.

2. File Search (Vector Store)

Uma ferramenta integrada que permite pesquisa semântica e acesso a arquivos específicos dentro do contexto do assistente. O File Search utiliza um ID de uma “Vector Store” para:

• Buscar informações relevantes em grandes volumes de documentos;
• Incorporar automaticamente os resultados na resposta do assistente;
• Proporcionar contexto enriquecido baseado em arquivos próprios.

3. Retrieval (Function Calling)

Um plugin que permite ao assistente fazer buscas em documentos pessoais ou corporativos, respondendo perguntas em linguagem natural com base em conteúdo atualizado e específico. É possível:

• Usar filtros de metadados como fonte, data e autor para refinar pesquisas;
• Manter bases de dados vetoriais atualizadas via webhooks;
• Integrar fontes de dados externas ao assistente.

Essas ferramentas podem ser usadas em paralelo, proporcionando um assistente multifuncional que oferece uma experiência avançada e personalizada de interação.

Entendendo a API da OpenAI

Uma API (Interface de Programação de Aplicações) é um conjunto de regras que permite a comunicação entre diferentes softwares. No caso da OpenAI, a API permite que você envie um texto e receba uma resposta gerada pelo modelo, facilitando a integração de funcionalidades de IA em seus aplicativos.

A documentação oficial da API é bem organizada e oferece um guia passo a passo para todas as funcionalidades disponíveis.

Exemplo prático: criando um Assistant tutor de matemática

Vamos criar um Assistant completo que funcione como tutor de matemática, utilizando o Code Interpreter para resolver problemas.

Passo 1: configuração inicial

Primeiro, importe as bibliotecas necessárias e configure o cliente da OpenAI:

import openai
import time
from dotenv import load_dotenv, find_dotenv

# Carrega variáveis de ambiente (API key)
_ = load_dotenv(find_dotenv())
client = openai.Client()

import openai
import time
from dotenv import load_dotenv, find_dotenv

# Carrega variáveis de ambiente (API key)
_ = load_dotenv(find_dotenv())
client = openai.Client()

Passo 2: criando o Assistant

Crie um novo Assistant com instruções específicas e a ferramenta Code Interpreter habilitada:

assistant = client.beta.assistants.create(
    name="Math Tutor",
    instructions="Você é um tutor pessoal de matemática. Escreva e execute códigos Python para responder perguntas de matemática com precisão.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-turbo-preview",
)

print(f"Assistant criado com ID: {assistant.id}")

assistant = client.beta.assistants.create(
    name="Math Tutor",
    instructions="Você é um tutor pessoal de matemática. Escreva e execute códigos Python para responder perguntas de matemática com precisão.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-turbo-preview",
)

print(f"Assistant criado com ID: {assistant.id}")

Passo 3: criando uma thread de conversa

Para interagir com o Assistant, crie uma Thread que armazenará o histórico de mensagens:

thread = client.beta.threads.create()

thread = client.beta.threads.create()

Passo 4: enviando uma mensagem

Adicione uma pergunta de matemática à Thread:

message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role='user',
    content='Se eu jogar um dado honesto 1000 vezes, qual é a probabilidade de obter exatamente 150 vezes o número 6? Resolva usando código Python.'
)

message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role='user',
    content='Se eu jogar um dado honesto 1000 vezes, qual é a probabilidade de obter exatamente 150 vezes o número 6? Resolva usando código Python.'
)

Passo 5: executando o assistant

Solicite ao Assistant que processe a Thread:

run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions='O nome do usuário é Adriano Soares e ele é um usuário Premium.'
)

run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions='O nome do usuário é Adriano Soares e ele é um usuário Premium.'
)

Passo 6: aguardando a execução

Aguarde até que o processamento seja concluído:

while run.status in ['queued', 'in_progress', 'cancelling']:
    time.sleep(1)
    run = client.beta.threads.runs.retrieve(
        thread_id=thread.id,
        run_id=run.id
    )

print(f"Status: {run.status}")

while run.status in ['queued', 'in_progress', 'cancelling']:
    time.sleep(1)
    run = client.beta.threads.runs.retrieve(
        thread_id=thread.id,
        run_id=run.id
    )

print(f"Status: {run.status}")

Passo 7: obtendo a resposta

Verifique e exiba a resposta do Assistant:

if run.status == 'completed':
    mensagens = client.beta.threads.messages.list(
        thread_id=thread.id
    )
    resposta = mensagens.data[0].content[0].text.value
    print(resposta)
else:
    print(f'Erro: {run.status}')

if run.status == 'completed':
    mensagens = client.beta.threads.messages.list(
        thread_id=thread.id
    )
    resposta = mensagens.data[0].content[0].text.value
    print(resposta)
else:
    print(f'Erro: {run.status}')

Resposta esperada:

A probabilidade de obter exatamente 150 vezes o número 6 ao lançar um dado honesto 1000 vezes é aproximadamente 0.0126, ou seja, cerca de 1.26%.

Passo 8: analisando os passos de processamento do Assistant

Uma funcionalidade extremamente útil é poder verificar todos os passos que o modelo percorreu até chegar à solução final. Isso é importante para:

• Depuração: identificar onde o processo pode ter falhado;
• Transparência: entender o raciocínio do Assistant;
• Auditoria: verificar quais códigos foram executados;
• Aprendizado: observar como o modelo resolve problemas.

Para isso, utilizamos o método runs.steps.list():

run_steps = client.beta.threads.runs.steps.list(
    thread_id=thread.id,
    run_id=run.id
)

for step in run_steps.data[::-1]:
    print('\n=== Step:', step.step_details.type)
    
    # Se o passo envolveu chamada de ferramentas (código)
    if step.step_details.type == 'tool_calls':
        for tool_call in step.step_details.tool_calls:
            print('-----')
            print(tool_call.code_interpreter.input)
            print('-----')
            print('Result')
            print(tool_call.code_interpreter.outputs[0].logs)
    
    # Se o passo foi criação de mensagem
    if step.step_details.type == 'message_creation':
        message = client.beta.threads.messages.retrieve(
            thread_id=thread.id,
            message_id=step.step_details.message_creation.message_id
        )
        print(message.content[0].text.value)

run_steps = client.beta.threads.runs.steps.list(
    thread_id=thread.id,
    run_id=run.id
)

for step in run_steps.data[::-1]:
    print('\n=== Step:', step.step_details.type)
    
    # Se o passo envolveu chamada de ferramentas (código)
    if step.step_details.type == 'tool_calls':
        for tool_call in step.step_details.tool_calls:
            print('-----')
            print(tool_call.code_interpreter.input)
            print('-----')
            print('Result')
            print(tool_call.code_interpreter.outputs[0].logs)
    
    # Se o passo foi criação de mensagem
    if step.step_details.type == 'message_creation':
        message = client.beta.threads.messages.retrieve(
            thread_id=thread.id,
            message_id=step.step_details.message_creation.message_id
        )
        print(message.content[0].text.value)

Exemplo avançado: análise de dados com Code Interpreter

Agora vamos explorar um caso de uso real e prático: criar um Assistant que analisa dados de vendas de um supermercado. Este exemplo demonstra o verdadeiro poder do Code Interpreter ao trabalhar com arquivos e realizar análises complexas.

Contexto do exemplo

Imagine que você tem um arquivo CSV (supermarket_sales.csv) contendo dados de vendas de um supermercado.

Passo 1: upload do arquivo para a OpenAI

Primeiro, precisamos fazer o upload do arquivo CSV para os servidores da OpenAI. O arquivo fica armazenado e associado ao Assistant:

import openai
from dotenv import load_dotenv, find_dotenv

# Carrega a API key do arquivo .env
_ = load_dotenv(find_dotenv())
client = openai.Client()

# Faz upload do arquivo CSV
file = client.files.create(
    file=open('arquivos/supermarket_sales.csv', 'rb'),
    purpose='assistants'  # Indica que o arquivo será usado com Assistants
)

print(f"Arquivo enviado com ID: {file.id}")

import openai
from dotenv import load_dotenv, find_dotenv

# Carrega a API key do arquivo .env
_ = load_dotenv(find_dotenv())
client = openai.Client()

# Faz upload do arquivo CSV
file = client.files.create(
    file=open('arquivos/supermarket_sales.csv', 'rb'),
    purpose='assistants'  # Indica que o arquivo será usado com Assistants
)

print(f"Arquivo enviado com ID: {file.id}")

O que está acontecendo aqui:

• purpose='assistants': define que este arquivo será usado especificamente com a API de Assistants;
• O arquivo fica hospedado na OpenAI e pode ser reutilizado em múltiplas conversas;
• O file.id é a referência que o Assistant usará para acessar o arquivo.

Passo 2: criando o Assistant especializado

Agora criamos um Assistant com personalidade e instruções específicas para análise financeira:

assistant = client.beta.assistants.create(
    name="Analista Financeiro Supermercados Asimov",
    instructions="""Você é um analista financeiro sênior especializado em varejo.
    Você utiliza os dados CSV de vendas do supermercado para realizar análises detalhadas.
    
    Suas responsabilidades incluem:
    - Calcular métricas financeiras e estatísticas
    - Identificar padrões e tendências nos dados
    - Fornecer insights acionáveis baseados em dados
    - Criar visualizações quando apropriado
    
    Sempre explique seu raciocínio e mostre os cálculos realizados.""",
    tools=[{'type': 'code_interpreter'}],
    file_ids=[file.id],  # Associa o arquivo ao Assistant
    model='gpt-4-turbo-preview'
)

print(f"Assistant criado: {assistant.name}")

assistant = client.beta.assistants.create(
    name="Analista Financeiro Supermercados Asimov",
    instructions="""Você é um analista financeiro sênior especializado em varejo.
    Você utiliza os dados CSV de vendas do supermercado para realizar análises detalhadas.
    
    Suas responsabilidades incluem:
    - Calcular métricas financeiras e estatísticas
    - Identificar padrões e tendências nos dados
    - Fornecer insights acionáveis baseados em dados
    - Criar visualizações quando apropriado
    
    Sempre explique seu raciocínio e mostre os cálculos realizados.""",
    tools=[{'type': 'code_interpreter'}],
    file_ids=[file.id],  # Associa o arquivo ao Assistant
    model='gpt-4-turbo-preview'
)

print(f"Assistant criado: {assistant.name}")

Passo 3: verificando a resposta do Assistant

Após aguardar a execução da thread, precisamos verificar se tudo correu bem e obter a resposta. Veja o código detalhadamente:

if run.status == 'completed':
    messages = client.beta.threads.messages.list(
        thread_id=thread.id
    )
    print(messages)
else:
    print('Erro', run.status)

if run.status == 'completed':
    messages = client.beta.threads.messages.list(
        thread_id=thread.id
    )
    print(messages)
else:
    print('Erro', run.status)

Passo 4: analisando a resposta

print(messages.data[0].content[0].text.value)

O rating médio das vendas do seu supermercado é de aproximadamente 6.97. Se precisar de mais informações ou análises adicionais, por favor, me avise!

print(messages.data[0].content[0].text.value)

O rating médio das vendas do seu supermercado é de aproximadamente 6.97. Se precisar de mais informações ou análises adicionais, por favor, me avise!

Passo 5: verificando os passos

Para verificar os passos necessários para chegar à resposta, execute o trecho de código do capítulo anterior.

run_steps = client.beta.threads.runs.steps.list(
  thread_id=thread.id,
  run_id=run.id
)

for step in run_steps.data[::-1]:
    print('======= Step >', step.step_details.type)
    if step.step_details.type == 'tool_calls':
        for tool_call in step.step_details.tool_calls:
            print('```')
            print(tool_call.code_interpreter.input)
            print('```')
            if tool_call.code_interpreter.outputs[0].type == 'logs':
                print('Result')
                print(tool_call.code_interpreter.outputs[0].logs)
    if step.step_details.type == 'message_creation':
        message = client.beta.threads.messages.retrieve(
            thread_id=thread.id,
            message_id=step.step_details.message_creation.message_id
        )
        if message.content[0].type == 'text':
            print(message.content[0].text.value)

run_steps = client.beta.threads.runs.steps.list(
  thread_id=thread.id,
  run_id=run.id
)

for step in run_steps.data[::-1]:
    print('======= Step >', step.step_details.type)
    if step.step_details.type == 'tool_calls':
        for tool_call in step.step_details.tool_calls:
            print('```')
            print(tool_call.code_interpreter.input)
            print('```')
            if tool_call.code_interpreter.outputs[0].type == 'logs':
                print('Result')
                print(tool_call.code_interpreter.outputs[0].logs)
    if step.step_details.type == 'message_creation':
        message = client.beta.threads.messages.retrieve(
            thread_id=thread.id,
            message_id=step.step_details.message_creation.message_id
        )
        if message.content[0].type == 'text':
            print(message.content[0].text.value)

Continue sua jornada em IA

Quer dominar completamente a criação de agentes avançados de IA e se tornar um Engenheiro de IA?

Trilha Formação Engenheiro de IA

Saia do zero e aprenda a construir agentes avançados de IA usando Python e os mais modernos modelos de inteligência artificial do mundo. Na Asimov Academy, você terá acesso a:

• Projetos práticos com Assistants da OpenAI;
• Integração com ferramentas de RAG (Retrieval-Augmented Generation);
• Desenvolvimento de agentes autônomos;
• Deploy de aplicações de IA em produção;
• Certificado reconhecido pelo mercado.

Conheça a Formação Engenheiro de IA →

Formação Engenheiro de Agentes de IA

Domine os frameworks de criação de agentes de IA mais avançados da atualidade e aprenda a transformar qualquer LLM em um agente!

Comece agora