Como criar um AI Agent com OpenAI Agents SDK e JS

Não se fala em outra coisa ultimamente a não ser sobre IA, em especial as LLMs (Large Language Models) como ChatGPT e outros. E embora em algum momento próximo esse hype diminua para níveis mais saudáveis (o Hype Cycle do Gartner nunca erra), é inegável que dá para construir aplicações mais inteligentes com a ajuda delas ou até mesmo criando assistentes para suas aplicações atuais, os chamados AI Agents: inteligências artificiais que não apenas respondem perguntas mas realizam tarefas para o usuário. E o melhor: a maior parte do trabalho duro já foi feito por empresas como a OpenAI!

Com o Agents SDK da OpenAI você pode criar facilmente agentes usando Python ou JavaScript (eu uso este segundo) que raciocinam usam os modelos da OpenAI e se conectam a APIs e dados da sua empresa conforme a necessidade, de maneira extremamente simples de implementar, principalmente se comparado a soluções mais robustas como LangChain, que já explorei aqui em outro tutorial.

Então neste tutorial vou te mostrar um exemplo breve de como usar o referido SDK para criar seu primeiro agente, que usa um backend próprio como tool, para consultas e cadastros. É importante que este não seja o seu primeiro contato com Node.js e nem com as APIs e modelos da OpenAI, algo que introduzo neste outro tutorial.

Vamos lá!

#1 – Setup do Projeto

Comece criando o seu projeto Node.js com os comandos abaixo, um de cada vez.


mkdir aiagent-example
cd aiagent-example
npm init -y
npm install dotenv openai @openai/agents express morgan zod axios

mkdir aiagent-example

cd aiagent-example

npm init -y

npm install dotenv openai @openai/agents express morgan zod axios

As extensões que instalamos no último comando foram:

DotEnv: para configurações do projeto;
OpenAI: pacote de integração com os modelos da OpenAI;
@OpenAI/Agents: o SDK específico de agentes da OpenAI;
Express: webframework do nosso backend de exemplo;
Morgan: logger do backend;
Zod: usado para ajudar a configurar as tools dos agentes;
Axios: vou usar para as tools chamarem o backend;

Agora abra o projeto no VS Code e crie um arquivo .env na raiz do projeto com as variáveis que vamos usar, principalmente a sua chave da OpenAI e lembre-se de não subir esse .env para seu GitHub se for versionar o projeto.


# .env
OPENAI_API_KEY=xxxxxxx
PORT=3000

# .env

OPENAI_API_KEY=xxxxxxx

PORT=3000

Agora crie um arquivo server.js na raiz do seu projeto com o conteúdo abaixo, que é um backend fake de clientes. Caso possua um backend próprio que possa usar para testes, pode usá-lo também ao invés deste.


//server.js
import "dotenv/config";
import express from "express";
import morgan from "morgan";

const app = express();

let nextId = 1;
const customers = [];

app.use(express.json());
app.use(morgan("tiny"));

app.post("/customers", (req, res, next) => {
    const newCustomer = {
        id: nextId++,
        name: req.body.name,
        age: parseInt(req.body.age),
        uf: req.body.uf
    };

    customers.push(newCustomer);
    res.status(201).json(newCustomer);
});

app.get("/customers/:id", (req, res) => {
    const id = parseInt(req.params.id);
    const customer = customers.find(c => c.id === id);
    res.json(customer);
})

app.get("/customers/", (req, res) => {
    res.json(customers);
})

app.get("/", (req, res, next) => {
    res.json(customers);
});

const PORT = process.env.PORT;
app.listen(PORT, () => console.log(`Server listening at ${PORT}`));

//server.js

import "dotenv/config";

import express from "express";

import morgan from "morgan";

const app = express();

let nextId = 1;

const customers = [];

app.use(express.json());

app.use(morgan("tiny"));

app.post("/customers", (req, res, next) => {

const newCustomer = {

id: nextId++,

age: parseInt(req.body.age),

uf: req.body.uf

};

customers.push(newCustomer);

res.status(201).json(newCustomer);

});

app.get("/customers/:id", (req, res) => {

const id = parseInt(req.params.id);

const customer = customers.find(c => c.id === id);

res.json(customer);

})

app.get("/customers/", (req, res) => {

res.json(customers);

})

app.get("/", (req, res, next) => {

res.json(customers);

});

const PORT = process.env.PORT;

app.listen(PORT, () => console.log(`Server listening at ${PORT}`));

Para que sintaxe ES6 seja reconhecida, abra seu package.json e altere o type para module, como abaixo, criando também dois scripts, um para o backend e outro para o index, onde estará nosso agente.


"type": "module",
"scripts": {
  "server": "node server",
  "start": "node index"
},

"type": "module",

"scripts": {

"server": "node server",

"start": "node index"

Também crie um index.js e coloque nele o carregamento do .env.


//index.js
import "dotenv/config";

//index.js

import "dotenv/config";

Você já pode subir seu server com “npm run server” e até mesmo “brincar” com ele, sendo que temos apenas rotas para cadastrar, listar e consultar cliente por id.

Agora sim, temos tudo pronto para programar nosso exemplo de AI Agente, usando qualquer um dos modelos de reasoning da OpenAI.

#2 – Criando as Tools

Para começar a programar nosso agente, vamos no index.js carregar alguns pacotes e definir a URL do nosso backend, pois no nosso caso o agente usará essa URL nas tools para chamá-lo.


import axios from "axios";
import { Agent, tool, run } from '@openai/agents';
import { z } from 'zod';

const API_URL = `http://localhost:${process.env.PORT}`;

import axios from "axios";

import { Agent, tool, run } from '@openai/agents';

import { z } from 'zod';

const API_URL = `http://localhost:${process.env.PORT}`;

Depois, vamos criar nossa primeira tool. Uma tool é literalmente uma ferramenta que um agente pode decidir usar de acordo com a situação. Ela pode ser:

uma busca na web;
uma busca em arquivos;
a manipulação de um computador ou browser;
ou uma função JS;

Usaremos tools do último tipo, pois queremos que o agente use o nosso backend nas tarefas que solicitarmos. Vou começar com uma tool bem simples, que obtém os dados dos clientes no backend.


const getCustomersTool = tool({
    name: 'get_customers',
    description: 'Obtém a lista de clientes do sistema CRM',
    parameters: {
        type: "object",
        properties: {},
        additionalProperties: false,
    },
    async execute({ }) {
        const response = await axios.get(`${API_URL}/customers`)
        return response.data;
    },
});

const getCustomersTool = tool({

description: 'Obtém a lista de clientes do sistema CRM',

parameters: {

type: "object",

properties: {},

additionalProperties: false,

async execute({ }) {

const response = await axios.get(`${API_URL}/customers`)

return response.data;

});

A função tool é usada para criar uma nova tool, sendo que cada tool tem os seguintes campos:

name: o nome da tool, para uso interno do agente;
description: a descrição de quando o agente deve usar esta tool, o que ela faz;
parameters: os parâmetros que devem ser passados pra que a tool funcione;
execute: a função de execução da tool, que pode ter qualquer lógica JS no seu interior;

Neste meu exemplo, a lógica de execução não requer parâmetros para que funcione mas coloquei um objeto vazio por obrigatoriedade do SDK. Já o código de execução em si é apenas uma chamada HTTP via Axios para o backend, retornando os dados obtidos. É um exemplo simples, então não estou esperando toneladas de dados, mas é algo que deve se preocupar em situações reais porque consomem seus tokens da API.

Agora vamos criar mais duas tools como exemplo, para as outras duas rotas do nosso backend que queremos expor ao agente.


const getCustomerTool = tool({
    name: 'get_customer',
    description: 'Obtém os detalhes de um cliente por id no banco de dados do sistema CRM',
    parameters: z.object({ id: z.number() }),
    async execute({ id }) {
        const response = await axios.get(`${API_URL}/customers/${id}`)
        return response.data;
    },
});

const addCustomerTool = tool({
    name: 'add_customer',
    description: 'Adiciona um novo cliente no sistema CRM',
    parameters: z.object({ name: z.string(), age: z.number(), uf: z.string() }),
    async execute(customer) {
        const response = await axios.post(`${API_URL}/customers`, customer)
        return response.data;
    },
});

const getCustomerTool = tool({

description: 'Obtém os detalhes de um cliente por id no banco de dados do sistema CRM',

parameters: z.object({ id: z.number() }),

async execute({ id }) {

const response = await axios.get(`${API_URL}/customers/${id}`)

return response.data;

});

const addCustomerTool = tool({

description: 'Adiciona um novo cliente no sistema CRM',

parameters: z.object({ name: z.string(), age: z.number(), uf: z.string() }),

async execute(customer) {

const response = await axios.post(`${API_URL}/customers`, customer)

return response.data;

});

Aqui nós temos as tools para pesquisar cliente por ID e também para adicionar um novo cliente na base. Como estas tools requerem parâmetros, usei o zod para configurar mais facilmente, de maneira menos verbosa, sendo que sempre deve ser um objeto passado no parâmetro do execute. As chamadas internas dispensam explicações, mas é interessante ver como escrevi as descrições das tools, de maneira que o agente consiga saber como usá-las depois.

Com as tools criadas, agora é a vez de criarmos o agente.

#3 – Criando o Agente

Nesse meu exemplo estou criando um assistente de CRM, ou seja, alguém que ajude a equipe do suporte ou de vendas a fazer a gestão dos clientes da empresa. Então o próximo passo após criar as tools é configurar o agente com elas, além de instrui-lo de como deve se comportar, usando a classe Agent que importamos mais cedo.


const crmAssistant = new Agent({
    name: 'CRM Assistant',
    model: "gpt-4.1-nano",
    instructions: 'Você é um assistente de sistema CRM, ajudando o usuário a lidar com a gestão dos clientes.',
    tools: [getCustomersTool, addCustomerTool, getCustomerTool]
});

const crmAssistant = new Agent({

model: "gpt-4.1-nano",

instructions: 'Você é um assistente de sistema CRM, ajudando o usuário a lidar com a gestão dos clientes.',

tools: [getCustomersTool, addCustomerTool, getCustomerTool]

});

O construtor da classe Agent espera um objeto com as seguintes propriedades:

name: o nome do agente, para uso interno;
model: o modelo a ser usado no reasoning;
instructions: como o agente deve se comportar, o que ele deve fazer, qual o contexto em que irá atuar, etc;
tools: array de tools que ele pode usar, além da base normal de treinamento do modelo;

Um ponto importante aqui sobre o campo model. Existem vários modelos disponíveis para reasoning, com diferentes preços e não é à toa. O modelo “flagship” da OpenAI (atualmente o GPT 4.1) é o mais caro e mais inteligente e é ele que você vai usar se não passar o campo model. No exemplo acima eu passei o mais baratinho de todos que é burro pra caramba. Quanto mais burro o modelo, mais inteligente tem de ser o usuário, ou seja, mais completo tem de ser o prompt que o usuário vai enviar ou o agente não saberá o que fazer com ele.

Entendido esse ponto, agora vamos escrever o código que roda uma vez nosso agente, passando a ele um prompt simples.


const result = await run(
    crmAssistant,
    'Cadastre um novo cliente chamado Luiz, 37 anos, do RS',
);
console.log(result.finalOutput);

const result = await run(

crmAssistant,

'Cadastre um novo cliente chamado Luiz, 37 anos, do RS',

);

console.log(result.finalOutput);

O resultado da execução, com o GPT 4.1 você vê abaixo (usei o modelo mais completo).

Ao realizar esse cadastro, eu sabia que o cliente havia recebido o id 1, então pedi que me trouxesse os detalhes do cliente com id 1. O resultado abaixo (ainda com o modelo mais completo).

Repare como ele conseguiu interpretar o prompt e usar a tool certa com sucesso, em ambos os casos, então logo depois, eu mandei cadastrar mais um, uma criança em Santa Catarina, e na sequência pedi que me dissesse quem era o cliente mais jovem (GPT 4.1 ainda).

Depois eu pedi que me dissesse qual cliente morava mais ao norte. Repare a nuance da pergunta, pois ambos são sulistas, mas ainda assim, SC fica mais ao norte do que RS. Veja a resposta.

Aí eu decidi fazer um teste com exatamente a mesma pergunta, mas usando o modelo mais caro x mais barato. A pergunta foi “Me informe qual é a capital do cliente mais velho da base”, a primeira resposta é do modelo barato, enquanto a segunda, do mais caro.

Agora, mesmo com o modelo mais barato, se eu mudar a pergunta para “Me informe qual é a capital da UF do cliente mais velho da base”, aí o agente consegue me trazer a resposta certa. Isso ilustra bem o que citei antes sobre “modelo burro requer usuário inteligente”.

E com isso finalizamos este tutorial inicial de desenvolvimento de AI Agents usando o OpenAI Agents SDK.

Até a próxima!