Tutorial da OpenAI Agents API: crie um agente que escreve e executa código na nuvem

A maioria dos apps com LLM segue um padrão simples: você envia um prompt, recebe uma resposta e usa essa resposta no seu aplicativo.

Isso funciona bem para tarefas simples, mas complica quando o modelo precisa escrever código, executá-lo, checar o resultado, lidar com arquivos, corrigir erros e continuar até concluir de fato a tarefa.

É aí que a Agents API da OpenAI se torna realmente útil.

Em vez de construir cada etapa por conta própria, você pode dar ao agente a tarefa, os arquivos necessários e um ambiente de trabalho — e deixar que ele cuide do resto.

Neste tutorial, vou manter o exemplo simples. Vamos criar um pequeno dataset fictício de vendas de um café e entregá-lo ao agente. O agente vai escrever e executar a análise, verificar os resultados e criar três arquivos de saída para a gente.

Depois de ver tudo funcionando nos bastidores, você vai perceber quanta coisa do fluxo de trabalho de programação tradicional está sendo automatizada para você. 

Se você é novo em agentes de IA, recomendo conferir nossa trilha de aprendizado AI Agents Fundamentals. 

O que é a OpenAI Agents API?

A OpenAI Agents API permite que você dê a um agente uma tarefa, os arquivos de que ele precisa e o ambiente em que deve trabalhar — e deixe o restante por conta dele.

Em vez de criar manualmente uma sandbox, iniciar uma sessão, subir arquivos, executar código, checar erros e gerenciar cada etapa, você pode enviar uma única chamada de API com a tarefa, configuração, ambiente e arquivos de entrada.

A partir daí, a maior parte do trabalho é feita pela Agents API.

Por baixo dos panos, a OpenAI gerencia o Codex harness, incluindo orquestração, contexto, uso de ferramentas, execução e sessões de longa duração. É quase como ter o OpenAI Codex rodando na nuvem para o seu aplicativo. 

Você não precisa se preocupar tanto com provisionar computação, gerenciar o ambiente de trabalho, acompanhar a sessão ou construir sozinho todo o loop do agente.

Isso é especialmente útil para tarefas mais complexas e de longa duração, em que o agente precisa realmente fazer o trabalho — não apenas devolver uma resposta.

Para este tutorial, vamos usar uma sandbox hospedada pela OpenAI:

Enviamos uma solicitação com o arquivo CSV, a tarefa e a configuração do agente. 

A Agents API então cria e gerencia a sessão e a sandbox para a gente.

Dentro da sandbox, o agente pode olhar o arquivo, decidir a abordagem de análise, gerar código em Python, executá-lo, checar os resultados e corrigir o que for preciso se algo der errado.

Quando terminar, as saídas ficam salvas como artefatos da sessão. 

Eles podem ser gráficos, datasets limpos, relatórios ou qualquer outro arquivo que o agente criar. Depois, podemos recuperar esses arquivos e permitir que o usuário faça o download e revise.

A ideia central é simples: enviamos a tarefa uma vez e o agente cuida do trabalho de verdade a partir daí.

OpenAI Responses API vs Agents SDK vs Agents API: qual usar?

A principal diferença entre as três é quanto do fluxo de trabalho você quer gerenciar por conta própria.

Use a Responses API quando você precisa que o modelo conclua uma tarefa focada, como sumarização, extração, classificação, perguntas e respostas, saídas estruturadas ou algumas chamadas de ferramenta.

Use o Agents SDK quando for construir um app com agente por conta própria e quiser mais controle sobre agentes, ferramentas, handoffs, guardrails e fluxos multiagentes.

Use a Agents API quando a tarefa é mais complexa e precisa de um ambiente próprio. Isso é útil quando o agente precisa trabalhar com arquivos, executar código, inspecionar resultados, corrigir erros e avançar por várias etapas.

Passo a passo: construindo um agente de análise de dados com a OpenAI

Para este tutorial, usamos a Agents API porque o agente precisa trabalhar com um arquivo, raciocinar sobre a análise, rodar código, inspecionar os resultados e salvar os artefatos finais para o usuário.

Vamos começar

1. Configure seu ambiente Python para a Agents API

Neste tutorial, vamos usar um Jupyter Notebook para testar a Agents API passo a passo e entender como cada parte funciona. 

Vamos começar instalando o pacote da OpenAI e importando as bibliotecas necessárias para o restante do tutorial.

Primeiro, instale ou atualize o pacote openai para Python:

%pip install -q --upgrade openai

Depois, importe as bibliotecas que vamos usar:

import base64
import csv
import io
import os
import random
from datetime import date, timedelta
from pathlib import Path

from IPython.display import Markdown, display
from openai import OpenAI

Agora crie o cliente da OpenAI:

client = OpenAI()

Garanta que seu OPENAI_API_KEY já esteja definido no seu ambiente. O cliente da OpenAI vai detectá-lo automaticamente.

2. Gere dados de exemplo para o agente de IA

Vamos criar um pequeno dataset falso de vendas para termos algo simples para entregar ao agente.

random.seed(42)

products = {
    "Latte": 4.50,
    "Tea": 3.00,
    "Cookie": 2.50,
    "Sandwich": 7.00
}

locations = ["Downtown", "Airport", "Campus"]
first_day = date(2026, 1, 1)
orders = []

for order_id in range(1, 51):
    product = random.choice(list(products))

    orders.append(
        {
            "order_id": order_id,
            "date": first_day + timedelta(days=random.randint(0, 89)),
            "location": random.choice(locations),
            "product": product,
            "units": random.randint(1, 5),
            "unit_price": products[product],
            "discount_rate": random.choice([0, 0, 0, 0.10]),
        }
    )

Isso cria 50 pedidos fictícios do café com diferentes produtos, locais, datas e descontos. Usamos uma semente aleatória fixa para gerar o mesmo dataset sempre que executarmos o notebook.

3. Crie e codifique o arquivo CSV para a sandbox do agente

Em seguida, vamos transformar os dados gerados em um arquivo CSV que pode ser enviado ao agente.

csv_buffer = io.StringIO()

writer = csv.DictWriter(
    csv_buffer,
    fieldnames=orders[0].keys()
)

writer.writeheader()
writer.writerows(orders)

csv_text = csv_buffer.getvalue()

csv_base64 = base64.b64encode(
    csv_text.encode()
).decode()

print("Preview:")
print("\n".join(csv_text.splitlines()[:6]))

Saída:

Preview:
order_id,date,location,product,units,unit_price,discount_rate
1,2026-01-04,Campus,Latte,3,4.5,0
2,2026-01-18,Campus,Tea,1,3.0,0
3,2026-01-05,Downtown,Sandwich,1,7.0,0
4,2026-03-06,Campus,Tea,1,3.0,0
5,2026-01-29,Airport,Sandwich,5,7.0,0

Também codificamos o CSV em Base64 porque vamos enviar o arquivo diretamente junto com a solicitação ao agente.

4. Defina a tarefa do agente e as saídas esperadas

Agora vamos descrever o que queremos que o agente faça com o arquivo CSV.

task = """
Analyze /workspace/cafe_sales.csv. Write /workspace/analyze_sales.py and run it.

Your job:
1. Check that the required columns exist and numeric values are valid.
2. Calculate gross_sales = units * unit_price.
3. Calculate net_sales = gross_sales * (1 - discount_rate).
4. Summarize net sales by location, product, and month.
5. Find the best-selling location and product by net sales.
6. Write these files:
   - /workspace/outputs/summary.json
   - /workspace/outputs/location_sales.csv
   - /workspace/outputs/morning_brief.md
7. Make the Morning Brief friendly and include three evidence-based insights.
8. Read the files back and verify that location totals equal total net sales.
9. Finish by reporting the verified total and the three output filenames.

Use only Python's standard library. Do not invent or silently change data.
""".strip()

O importante é descrever o objetivo e as saídas esperadas, em vez de escrever nós mesmos o código da análise.

O agente pode decidir como fazer o trabalho, executar o código e verificar os resultados antes de encerrar.

5. Execute o agente na sandbox hospedada pela OpenAI

Agora vamos enviar tudo para a Agents API em uma única solicitação e deixar o agente fazer o trabalho de verdade na nuvem.

session_id = None
turn_id = None
response_parts = []

live_output = display(
    Markdown(""),
    display_id=True
)

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "You are a careful data analyst. "
            "Write simple code, run it, and verify the results."
        ),
    },
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/cafe_sales.csv",
                "data": csv_base64,
            }
        ],
    },
    input=task,
    stream=True,
) as events:

    for event in events:

        if hasattr(event, "session_id"):
            session_id = event.session_id

        if event.type == "agent.session.turn.output_text.delta":
            response_parts.append(event.delta)

            live_output.update(
                Markdown("".join(response_parts))
            )

        elif event.type == "agent.session.turn.completed":
            turn_id = event.turn.id

        elif event.type.endswith(("failed", "cancelled")):
            raise RuntimeError(
                event.model_dump_json(indent=2)
            )

assert session_id and turn_id

live_output.update(
    Markdown("".join(response_parts))
)

print("✅ Analysis complete")
print(f"Session: {session_id}")
print(f"Turn: {turn_id}")

É aqui que a maior parte do trabalho acontece.

Fazemos uma solicitação contendo a configuração do agente, o ambiente hospedado, o arquivo CSV e a tarefa. 

A OpenAI cria a sessão gerenciada e executa o agente dentro da sandbox hospedada. O agente pode então inspecionar o arquivo, escrever o analyze_sales.py, executá-lo, checar os resultados, corrigir o que der errado e criar os arquivos finais de saída. 

O endpoint de criação de sessão suporta tanto o ambiente quanto a entrada inicial na mesma solicitação.

Há três partes principais na solicitação:

• agent informa à OpenAI qual modelo usar e como o agente deve se comportar.
• environment fornece ao agente seu espaço de trabalho hospedado e coloca nosso arquivo CSV lá dentro.
• input passa ao agente a tarefa que definimos na seção anterior.

Também definimos stream=True. 

Isso não muda como a tarefa é concluída. Apenas permite receber eventos enquanto o agente trabalha, em vez de esperar o turno inteiro terminar para ver algo.

Neste exemplo, ouvimos eventos agent.session.turn.output_text.delta e vamos atualizando o notebook com o texto mais recente.

Ou seja, o texto que aparece acima é o agente relatando seu progresso e a resposta final. 

A tarefa em si continua rodando no ambiente hospedado até recebermos o evento agent.session.turn.completed.

Na minha execução, o agente criou e rodou o analyze_sales.py, conferiu os arquivos gerados e verificou o total de vendas líquidas de 600,55.

O ponto importante é que o modelo não apenas disse qual código Python rodar. O agente realmente escreveu o código, executou, inspecionou o resultado e verificou a saída por conta própria.

6. Recupere e baixe os artefatos de arquivos do agente

Agora que o agente terminou, podemos baixar os arquivos que ele criou nesse turno.

download_dir = Path("cloud_bean_results")
download_dir.mkdir(exist_ok=True)

downloaded = []

for artifact in client.beta.agents.sessions.artifacts.list(
    session_id
):
    if artifact.turn_id == turn_id:

        destination = (
            download_dir / Path(artifact.path).name
        )

        with (
            client.beta.agents.sessions.artifacts
            .with_streaming_response
            .content(
                artifact.id,
                session_id=session_id
            )
        ) as response:
            response.stream_to_file(destination)

        downloaded.append(destination)

assert downloaded

print("Downloaded:")

for path in downloaded:
    print(f"- {path}")

Saída:

Downloaded:
- cloud_bean_results/summary.json
- cloud_bean_results/morning_brief.md
- cloud_bean_results/location_sales.csv

Aqui, listamos os artefatos da sessão, mantemos os criados no turno concluído e baixamos para a pasta local cloud_bean_results.

7. Exclua a sessão para economizar custos de computação da sandbox

Quando terminarmos com os arquivos, devemos excluir a sessão para não manter o ambiente gerenciado ativo por mais tempo do que o necessário.

result = client.beta.agents.sessions.delete(
    session_id
)

print(f"Session deleted: {result.deleted}")

Saída:

Session deleted: True

Isso remove a sessão gerenciada da API. 

A OpenAI observa que a limpeza física dos recursos subjacentes pode continuar de forma assíncrona após o retorno da solicitação de exclusão.

Essa etapa é especialmente importante ao usar uma sandbox hospedada pela OpenAI. 

A sandbox é o ambiente de computação onde o agente executa código e trabalha com arquivos, e sandboxes hospedadas usam computação em contêiner cobrada separadamente do uso do modelo. 

Então, se você mantiver sessões e ambientes rodando além do necessário, poderá acumular custos de computação.

Considerações finais: vale a pena o custo da OpenAI Agents API?

O que mais me chamou atenção na Agents API é o quanto ela consegue fazer a partir de uma única chamada de API.

Entregamos o arquivo, a tarefa, a configuração do modelo e o ambiente hospedado. 

A partir daí, ela cuidou do resto: criou o workspace, inspecionou os dados, escreveu o código Python, executou, conferiu as saídas, corrigiu o que fosse preciso e produziu os artefatos finais.

A sensação é mesmo de ter o Codex rodando na nuvem para o seu aplicativo. 

Não precisei me preocupar em provisionar computação, gerenciar o loop de execução, lidar com arquivos intermediários ou acompanhar cada etapa. Basicamente, bastou definir bem a tarefa e depois olhar o resultado.

A execução levou cerca de dois minutos, mas nesse tempo o agente fez bastante coisa nos bastidores.

É isso que a diferencia de uma solicitação comum de API. 

Você não está só esperando um modelo gerar texto. Está esperando um agente concluir uma parte real do trabalho.

Nos meus testes, três execuções deste exemplo custaram em torno de US$ 1,52 no total, incluindo o uso do modelo e do ambiente hospedado. 

Para uma tarefa tão pequena, não é barato; então, em produção, eu certamente testaria primeiro modelos menores ou mais baratos.

Mas para trabalhos mais complexos envolvendo codificação, depuração, arquivos, raciocínio e várias etapas dependentes, o custo extra pode fazer bem mais sentido.