diogodev_

Voltar à listagem

Conteúdo

Criando agentes com OpenAI

Os modelos da OpenAI evoluíram muito além de simples chatbots. Hoje é possível criar agentes capazes de utilizar ferramentas, acessar APIs externas e executar tarefas complexas. Neste artigo veremos como criar um agente simples utilizando o SDK da OpenAI e explorar alguns conceitos importantes.

O que é um agente?

Um agente é uma aplicação que combina um modelo de linguagem com ferramentas externas para executar tarefas.

Ao contrário de um chatbot tradicional, um agente pode:

  • Consultar APIs;
  • Executar funções;
  • Pesquisar documentos;
  • Acessar bancos de dados;
  • Trabalhar com memória e contexto;
  • Interagir com outros agentes.

Instalando o SDK

Primeiro, instale a biblioteca da OpenAI:

pip install openai-agents

Configure sua chave da API:

export OPENAI_API_KEY=SEU_TOKEN

Criando o primeiro agente

Com poucas linhas é possível criar um agente simples:

from agents import Agent

agent = Agent(
    name="Assistant",
    instructions="Responda perguntas de forma objetiva."
)

Agora o agente já pode responder perguntas dos usuários.

Adicionando ferramentas

Uma das principais vantagens dos agentes é a capacidade de executar funções.

Vamos criar uma ferramenta simples:

def get_current_year():
    return 2026

Registrando a ferramenta:

agent = Agent(
    name="Assistant",
    instructions="Use as ferramentas quando necessário.",
    tools=[get_current_year]
)

Se o usuário perguntar:

Em que ano estamos?

O modelo poderá chamar essa função automaticamente.

Exemplo prático

Imagine um sistema de e-commerce.

Podemos disponibilizar funções para:

get_customer()

get_orders()

get_invoice()

Fluxo:

Usuário
     ↓
Agente
     ↓
Tool
     ↓
API ou Banco
     ↓
Resposta

Quando o usuário perguntar:

Quais pedidos o cliente 20 possui?

O agente poderá utilizar a função responsável por consultar os pedidos e montar uma resposta.

Function Calling

Function Calling permite que o modelo identifique quando precisa executar uma ação.

Exemplo:

def get_weather(city: str):
    """
    Retorna a temperatura atual da cidade.
    """

Ao receber:

Como está o clima em São Paulo?

O agente pode chamar automaticamente essa função.

Trabalhando com contexto

O contexto é fundamental para manter conversas mais naturais.

Exemplo:

Usuário:
Meu nome é Diogo.

Usuário:
Qual é o meu nome?

O agente utilizará o histórico para responder corretamente.

Em aplicações maiores, esse contexto pode ser armazenado em:

  • Redis;
  • PostgreSQL;
  • Bancos vetoriais;
  • Memória customizada.

Streaming de respostas

Outra funcionalidade importante é o streaming.

Ao invés de esperar toda a resposta ser gerada, ela é enviada aos poucos para o usuário.

Isso melhora a experiência em:

  • Chats;
  • Assistentes;
  • Aplicações web.

Estrutura do projeto

Uma organização simples poderia ser:

project/
│
├── main.py
├── agents/
│     ├── support_agent.py
│     ├── sales_agent.py
│
├── tools/
│     ├── customer_tool.py
│     ├── order_tool.py
│     └── weather_tool.py
│
├── prompts/
│     └── system_prompt.txt
│
└── .env

Multiagentes

Em sistemas maiores, podemos ter agentes especializados.

Exemplo:

Supervisor Agent
        ↓
┌────────────┬─────────────┬────────────┐
│ Financeiro │ Atendimento │ Vendas     │
└────────────┴─────────────┴────────────┘

Cada agente possui responsabilidades específicas.

Boas práticas

Crie tools específicas

Prefira:

get_orders()

get_customer()

get_products()

Ao invés de:

process_everything()

Escreva boas descrições

As docstrings ajudam o modelo a decidir quando utilizar cada função.

def get_orders(customer_id: int):
    """
    Retorna os pedidos do cliente informado.
    """

Mantenha prompts simples

Prompts muito longos podem gerar comportamentos inesperados.

Monitore chamadas de ferramentas

Logs e observabilidade ajudam a identificar problemas e custos desnecessários.

Casos de uso

Agentes podem ser utilizados em:

  • Chatbots;
  • Atendimento ao cliente;
  • Assistentes internos;
  • Automação de tarefas;
  • Sistemas corporativos;
  • Busca em documentos;
  • Integração com APIs.

Vantagens

  • Facilidade de integração;
  • Function Calling nativo;
  • Streaming de respostas;
  • Suporte a múltiplas ferramentas;
  • Grande ecossistema.

Desvantagens

  • Custos podem crescer rapidamente;
  • Necessidade de monitorar tokens;
  • Fluxos complexos exigem planejamento.

Quando utilizar?

Agentes fazem sentido quando:

  • Existem tarefas repetitivas;
  • É necessário acessar sistemas externos;
  • Há necessidade de contexto e memória;
  • O modelo precisa executar ações além de responder texto.

Conclusão

Os agentes da OpenAI permitem construir aplicações inteligentes capazes de interagir com ferramentas, APIs e bases de dados. Com poucas linhas de código já é possível criar assistentes bastante poderosos.

Combinando Function Calling, memória e boas práticas de arquitetura, é possível desenvolver agentes para diversos cenários, desde chatbots simples até sistemas mais complexos envolvendo múltiplos agentes.

Saiba mais