Como Criar um Agente de IA com o OpenAI Agents SDK

O que é realmente um agente de IA

Um agente de IA é um modelo executado dentro de um loop de trabalho. Ele recebe um objetivo, decide qual é o próximo passo, aciona uma ferramenta autorizada quando necessário, processa o resultado e decide se continua ou encerra a execução.

Pense nisso como a contratação de um operador júnior. As instruções funcionam como a descrição do cargo. O modelo entra com o discernimento analítico. As ferramentas são as credenciais de acesso desse operador ao seu sistema de pedidos, calendário, base de conhecimento, navegador ou repositório de arquivos. A memória atua como o bloco de anotações. Guardrails e etapas de aprovação representam a supervisão direta.

Isso é totalmente diferente de um chatbot comum. Um chatbot apenas redige respostas. Um agente consegue consultar um pedido, confrontar o status em tempo real com as políticas vigentes, solicitar dados pendentes e direcionar o caso para um atendente humano. O loop de ação é o verdadeiro divisor de águas.

A visão geral atual sobre agentes da OpenAI descreve agentes como aplicações que planejam, invocam ferramentas, mantêm estado e, eventualmente, colaboram entre especialistas. No SDK, o objeto fundamental permanece intencionalmente enxuto: um modelo acompanhado de instruções, ferramentas e controles opcionais, como guardrails e transferências operacionais (handoffs).

Agents SDK ou Responses API?

Adote o Agents SDK quando preferir que o runtime gerencie automaticamente chamadas sequenciais de ferramentas, controle de estado, guardrails, handoffs e fluxos de aprovação. Use a Responses API de forma direta caso queira programar e manter controle absoluto sobre esse loop. A OpenAI recomenda o caminho da Responses API para controle granular do modelo, reservando o SDK para fluxos conversacionais ou transacionais delimitados com orquestração recorrente.

Se a sua preferência for plataformas no-code, a lógica estrutural não muda. Certifique-se de que a ferramenta ofereça definição explícita de ferramentas, etapa de aprovação humana, logs de execução detalhados e mecanismos confiáveis de interrupção do loop. Uma interface visual não elimina a necessidade desses controles.

Como criar um agente de IA: a primeira versão funcional

O caminho mais rápido consiste em diminuir o escopo da tarefa antes de expandir a complexidade técnica.

1. Escreva um contrato de trabalho de uma frase

Especifique o usuário, o gatilho, a ação e o critério de conclusão. Dizer "ajudar no suporte ao cliente" é amplo demais. "Responder a dúvidas sobre status de pedidos consultando a API de pedidos e transferir qualquer solicitação de reembolso ou alteração de endereço para um humano" é perfeitamente implementável.

Liste também as ações expressamente proibidas. Essa prática transforma uma autonomia vaga em uma decisão de produto delimitada.

2. Avalie se a tarefa realmente exige um agente

Agentes justificam sua complexidade quando a demanda envolve discernimento contextual, linguagem ou documentos desestruturados e exceções que tornam sistemas tradicionais baseados em regras frágeis. O guia prático da OpenAI recomenda soluções determinísticas caso essas condições não estejam presentes.

Um cálculo de impostos, a validação de um formulário fixo ou uma rotina agendada de cópia de dados devem continuar como software convencional. Já uma solicitação de reembolso que exige interpretar o histórico da conversa, checar a política interna, inspecionar o pedido e decidir se requer revisão humana encaixa-se perfeitamente no escopo de um agente.

3. Escolha o modelo para a tarefa, não para a demonstração

Por padrão, o SDK utiliza atualmente o gpt-5.4-mini sem esforço de raciocínio adicional e com verbosidade baixa para fluxos que exigem baixa latência. O guia de modelos recomenda o gpt-5.6-sol para cenários em que a qualidade do resultado é crítica e você possui acesso liberado.

Comece sempre pela opção de menor custo que passe com sucesso nos seus casos de teste salvos. Suba de nível apenas quando os erros decorrerem da capacidade analítica do modelo, e não da ausência de uma ferramenta, de uma instrução imprecisa ou de dados corrompidos. Nenhum modelo avançado compensa uma API de pedidos que entrega dados desatualizados.

4. Forneça apenas uma ferramenta de leitura

Sua primeira ferramenta deve exclusivamente consultar informações, nunca alterá-las. Uma consulta de pedidos, busca em políticas, checagem de estoque ou verificação de disponibilidade em agenda são ações muito mais simples de avaliar e seguras de reexecutar do que emitir reembolsos, cancelamentos, processar pagamentos ou enviar e-mails externos.

O SDK transforma funções tipadas em Python em ferramentas com geração automática de schemas de entrada. A biblioteca também disponibiliza ferramentas prontas para web search, file search, interpretador de código, MCP e geração de imagens. Ambientes locais de terminal, comandos shell ou edição direta de arquivos exigem um ambiente de execução que você controle rigorosamente.

Abaixo está o menor padrão funcional:

from agents import Agent, Runner, function_tool

@function_tool
def lookup_order(order_id: str) -> str:
    """Return the current order status from the order system."""
    return "Order 123 is packed and awaiting carrier pickup."

agent = Agent(
    name="Order status agent",
    instructions=(
        "Answer order-status questions with lookup_order. "
        "Never change or cancel an order. Escalate anything else."
    ),
    tools=[lookup_order],
)

result = Runner.run_sync(agent, "Where is order 123?")
print(result.final_output)

Instale o SDK em Python executando pip install openai-agents e armazene sua chave de API na variável de ambiente OPENAI_API_KEY. A mesma estrutura arquitetural pode ser reproduzida no TypeScript SDK atual, caso seja a linguagem principal do seu stack.

5. Estabeleça um critério de parada para o loop

O Runner aciona o modelo, executa a ferramenta solicitada, retorna os dados obtidos e repete o processo. O ciclo termina quando o modelo entrega a resposta final sem invocar novas ferramentas. Ele também encerra ao atingir um limite fixo de interações, gerando a exceção MaxTurnsExceeded.

Todo agente em produção precisa de um teto de passos operacionais, timeout configurado e uma definição clara de falha controlada. Encerrar com "não foi possível validar as informações, caso encaminhado a um atendente" é uma finalização válida e segura. Insistir em retentativas infinitas não é persistência: é incidente operacional.

6. Escolha uma única estratégia de memória

Memória significa transportar contexto relevante para a próxima iteração do diálogo. O SDK permite salvar o histórico no lado do cliente por meio de uma sessão, ou você pode delegar a continuidade à infraestrutura da OpenAI utilizando um conversation_id ou previous_response_id.

Defina estritamente uma abordagem por conversa. O SDK bloqueia intencionalmente o uso simultâneo de sessões locais e gerenciamento de estado no servidor em uma mesma execução, evitando duplicidade e inconsistências de contexto. Avalie também o volume real de histórico necessário: um agente de suporte precisa do contexto do ticket aberto, não da transcrição completa de anos de relacionamento do cliente.

7. Implemente verificações em todas as fronteiras críticas

Utilize um guardrail de entrada para barrar solicitações fora do escopo definido. Adicione guardrails de ferramentas em cada função personalizada capaz de consultar ou alterar dados de negócio. Aplique guardrails de saída para validar a resposta final gerada. Mantenha aprovação humana obrigatória antes de qualquer ação irreversível ou onerosa.

Um aspecto técnico relevante: os guardrails de entrada são processados em paralelo por padrão. Isso reduz a latência geral, mas o agente pode consumir tokens ou disparar uma ferramenta antes que a checagem aponte a violação. Configure o modo bloqueante caso a requisição possa gerar efeitos colaterais ou expor informações confidenciais.

Para uma arquitetura avançada de proteção, consulte o blast-radius guardrail playbook. O princípio central é direto: passe todas as operações pagas, com mutação de dados ou que exijam permissões elevadas por uma fronteira única e auditável.

8. Monitore com tracing, avalie e integre sandboxes apenas se necessário

O tracing vem habilitado por padrão no Agents SDK. Ele registra gerações do modelo, execuções de funções, ativações de guardrails e transferências de contexto, facilitando a identificação exata da causa de sucessos ou erros. Avalie esses traces frente a uma base de testes reais com saídas esperadas antes de incluir mais ferramentas.

Traces capturam entradas e saídas de modelos e funções; portanto, desative a captura de dados sensíveis sempre que necessário. O serviço de tracing da OpenAI não está disponível sob políticas de Zero Data Retention.

Recorra a sandboxes exclusivamente quando o trabalho demandar arquivos locais, execução de comandos, bibliotecas externas ou persistência longa no espaço de trabalho. A atualização de abril de 2026 do SDK da OpenAI introduziu ambientes controlados nativos, manifestos de workspace portáteis, snapshots e integração com diversos provedores de sandbox. Um agente de triagem de suporte não precisa de um container; um analista automatizado de relatórios ou um agente de código quase sempre exigem.

Custos reais de operação

O SDK e a Responses API não cobram taxas de plataforma adicionais. A cobrança baseia-se no consumo de tokens do modelo selecionado e no uso de ferramentas hospedadas.

Considerando os valores padrão para contextos curtos, o gpt-5.6-sol custa $5 por milhão de tokens de entrada e $30 por milhão de tokens de saída. O gpt-5.6-terra custa $2 e $12. O gpt-5.6-luna opera a $0.20 e $1.20. Chamadas de web search custam $10 por 1,000 requisições, acrescidas dos tokens do conteúdo retornado. As consultas via file-search na Responses API saem a $2.50 por 1,000 chamadas, com armazenamento a $0.10 por GB ao dia após o primeiro GB gratuito. Um container hospedado de 1 GB para shell ou interpretação de código parte de $0.03 por sessão de 20 minutos.

Esses valores unitários não revelam o custo final de um trabalho concluído. Seus logs de tracing revelam. Monitore a quantidade de turnos do modelo, chamadas de ferramentas, retentativas e transbordos para atendimento humano em cada desfecho bem-sucedido. Com esses dados em mãos, equilibre o orçamento de modelos e ferramentas mantendo o padrão de qualidade.

Sete tarefas de agentes que valem a pena construir, ranqueadas

As melhores aplicações para agentes contam com um comprador claro, um fluxo de trabalho restrito e um resultado facilmente auditável.

1. Agente de resolução de atendimento ao cliente

Uma equipe de suporte para e-commerce pode fornecer a um agente acesso a conteúdos de ajuda aprovados e permissão de leitura sobre dados de pedidos. O agente autentica o cliente, consulta o rastreio da entrega, instrui sobre os próximos passos e delega reembolsos ou alterações cadastrais para a equipe humana. O ganho real está na redução do tempo de primeira resposta e na consistência das anotações de transbordo, não na demissão de atendentes.

2. Agente de pesquisa analítica baseada em evidências

Um time de estratégia pode carregar uma série de relatórios em um workspace controlado e solicitar uma análise comparativa referenciando os nomes dos arquivos de origem em cada afirmação. O agente pesquisa, extrai dados, cruza referências e consolida um relatório estruturado. A economia acontece liberando analistas da caça manual por documentos para focar em julgamento crítico.

3. Agente de qualificação comercial e preparação de reuniões

Uma equipe de vendas B2B pode deixar um agente analisar mensagens recebidas, enriquecer os dados corporativos via fontes confiáveis, validar regras de qualificação e estruturar um resumo pré-reunião. O agendamento é disparado apenas quando o prospect atende aos critérios pré-estabelecidos. A vantagem reside em padronizar a preparação e reduzir trabalho manual no CRM, mantendo a negociação sob o comando do vendedor.

4. Agente de triagem de operações

Uma administradora predial pode filtrar e-mails de manutenção por meio de um agente que extrai condomínio, unidade, defeito relatado, urgência e horário de preferência para visita técnica. Ele checa os dados do morador, gera um rascunho de ordem de serviço e sinaliza riscos estruturais. O benefício prático é diminuir a digitação manual e evitar ordens de serviço incompletas.

5. Agente de comparação de contratos e conformidade

Um time de compras pode usar um agente para confrontar minutas de fornecedores com os termos-padrão da empresa, destacando divergências e indicando as páginas das cláusulas conflitantes. Ele monta o dossiê de análise sem autorizar acordos. Isso acelera a primeira revisão sem transferir o parecer jurídico final para a IA.

6. Agente interno para triagem de TI

Uma equipe de suporte interno de TI pode conectar um agente voltado aos colaboradores ao inventário de equipamentos, status dos servidores e tutoriais oficiais de solução de problemas. O agente coleta diagnósticos técnicos, propõe testes seguros e abre o chamado com os logs pertinentes anexados. O ganho imediato é encurtar as trocas preliminares de mensagens antes da intervenção técnica.

7. Agente controlado para código e documentos

Equipes de engenharia ou finanças podem alocar repositórios ou planilhas em um sandbox, liberar uma lista fechada de comandos e determinar uma pasta de saída específica. O agente inspeciona arquivos, executa cálculos ou testes, ajusta rascunhos e gera os artefatos para homologação. É aqui que a infraestrutura de sandboxes se faz necessária, viabilizando um ambiente isolado com histórico auditável.

Três produtos que você pode construir a partir disso

O conceito genérico de "agente de IA" não constitui um mercado em si. Estas três soluções atacam dores com intenção comprovada de compra.

Maior potencial: agente vertical de resolução de suporte

Desenvolva um agente de atendimento especializado em um nicho ou ecossistema específico, como lojas Shopify, administradoras de imóveis ou empresas de serviços em campo. O cliente paga por chamados efetivamente solucionados e transbordos bem-estruturados, não pelo acesso a uma caixa de chat vazia.

O indicativo comercial é inequívoco. O termo "AI customer service agent" registra cerca de 720 pesquisas mensais no Google, possui forte apelo comercial e alcança um CPC de $264.61. Além disso, assistentes de IA recebem dúvidas sobre esse mesmo serviço cerca de 69 vezes por mês. No cenário atual, o Intercom precifica em $0.99 cada resolução bem-sucedida em chat ou e-mail, encaminhamento estruturado ou desqualificação de lead.

A versão mínima comercializável demanda um canal único, base de conhecimento autorizada, ferramenta de leitura de dados de clientes, transbordo para humanos e um painel com métricas de resolução. A barreira de entrada não reside na chamada de API do modelo, mas na solidez das integrações verticais, base de testes, regras de transbordo e comprovação de que o atendimento foi verdadeiramente satisfatório para o usuário.

Esta é a oportunidade mais promissora: a atividade é restrita, o contratante é claro e o sucesso é matematicamente quantificável. O CPC elevado confirma a intensa disputa de fornecedores por esse perfil de cliente.

Assistente analítico de pesquisa para nichos regulados

Construa um ambiente de pesquisa para profissionais com demandas de alta precisão, como analistas de compliance, redatores de editais públicos, pesquisadores de mercado da saúde ou auditores de due diligence. O sistema pesquisa em uma base proprietária, atrela fontes oficiais a cada conclusão, confronta evidências divergentes e gera relatórios reproduzíveis.

A expressão "AI powered research assistant" conta com aproximadamente 18,100 buscas mensais no Google com intenção comercial. O termo correlato "AI research assistant" soma outras 2,400 pesquisas. O Elicit cobra atualmente $49 por usuário ao mês no plano Pro e $169 no Scale, validando a disposição das empresas em pagar por fluxos estruturados de síntese analítica.

O produto mínimo viável requer suporte a um formato específico de documento, um modelo fixo de relatório, tabela de fontes citadas e fila de conferência. O perigo aqui é a falta de foco: assistentes genéricos colidem diretamente com soluções consolidadas de mercado. A alternativa sustentável reside em integrar bases de dados exclusivas, regras específicas do setor e padrões de auditoria que softwares genéricos ignoram.

Agente de qualificação e follow-up comercial

Crie um agente receptivo (inbound) que sane dúvidas de produto, valide o perfil do lead, atualize o CRM, elabore o briefing da oportunidade e só agende chamadas se todos os critérios forem preenchidos. Comece obrigatoriamente por tráfego inbound: fluxos outbound não supervisionados ampliam riscos jurídicos e danos à reputação da marca.

A busca "AI sales agent" mobiliza cerca de 1,000 pesquisas mensais no Google, com foco comercial e CPC de $74.89. O Intercom estabeleceu a precificação de cada qualificação bem-sucedida em $9.99, oferecendo uma referência de mercado concreta.

O MVP exige chat no site ou integração por e-mail, conexão somente-leitura com o CRM, regras formais de qualificação, leitura de agenda e validação humana antes de disparar comunicações sensíveis. A maior armadilha reside em dados sujos de origem: um agente ágil alimentado com registros incompletos qualificará perfis inadequados com extrema convicção.

Limites fundamentais que você deve respeitar

Agentes não convertem software probabilístico em mecanismos determinísticos. O que fazem é encapsular essa incerteza dentro de um ciclo que você pode monitorar e regular.

• Jamais adote agentes para solucionar lógicas fixas que o código convencional resolve com eficiência.
• Não conceda permissões de escrita antes que a versão de leitura esteja plenamente homologada com dados reais.
• Não confie apenas em um guardrail global. As proteções do agente não cobrem nativamente todas as ferramentas hospedadas; portanto, o controle de acessos deve ser aplicado também no nível da sua aplicação e das APIs internas.
• Evite misturar estruturas de memória sem critério. Duplicar o histórico dispersa o contexto e gera gastos inúteis com tokens.
• Não inicie seus testes com arquiteturas multiagente. A própria OpenAI recomenda esgotar o potencial de um único agente munido de ferramentas antes de tentar orquestrações complexas entre múltiplos agentes.
• Nunca delegue a um modelo a aprovação final de operações irreversíveis. Tarefas de risco crítico exigem supervisão humana direta até que métricas consistentes justifiquem uma flexibilização.

Mecanismos de segurança externos têm seu valor, mas o design da arquitetura é quem sustenta a operação. A comparação das melhores ferramentas de segurança em IA traz um bom direcionamento depois de mapeados os riscos efetivos do seu projeto.

A constatação pragmática é que o modelo em si costuma ser a etapa mais simples. O verdadeiro desafio de engenharia e produto reside na parametrização de ferramentas, governança de acessos, integridade de dados, avaliação contínua, transbordo operacional e viabilidade financeira. Domine esses fundamentos e seu agente entregará valor real; negligencie-os e o que parecia uma demonstração brilhante logo se tornará um funcionário desgovernado com permissões de produção.

Caso precise de uma solução sob medida integrada aos seus sistemas internos e políticas de aprovação, conheça nosso serviço de desenvolvimento de agentes de IA.