Como transformar um script Python em um agente de IA com o OpenAI Agents SDK

Você não precisa reescrever suas aplicações Python para começar a usar agentes de IA. Se o seu script já contém funções úteis, basta expor essas funções como ferramentas e deixar um LLM decidir quando chamá-las, com quais argumentos e o que fazer com os resultados. Este guia transforma um script simples de monitoramento de sites em um agente funcional usando o OpenAI Agents SDK.

O ponto de partida: um script Python comum

Antes do agente, começamos com um programa que verifica se um site responde e mede a latência da requisição:

from time import perf_counter
import requests

def check_website(url: str) -> str:
    start = perf_counter()
    try:
        response = requests.get(url, timeout=10)
        latency = perf_counter() - start
        return (
            f"{url}\n"
            f"Status: {response.status_code}\n"
            f"Response time: {latency:.2f}s"
        )
    except requests.RequestException as error:
        return f"{url}\nError: {error}"

print(check_website("https://www.python.org"))

Esse código faz exatamente o que foi programado: envia uma requisição HTTP, coleta o código de status, mede o tempo de resposta e retorna o resultado. O problema é que o fluxo é completamente fixo — para checar cinco sites ou comparar tempos de resposta, você precisa escrever essa lógica manualmente. É aí que o agente muda o jogo: em vez de codificar cada decisão, você expõe a função como ferramenta e dá um objetivo ao modelo.

Prós e contras da abordagem

• ✅ Reutiliza funções existentes sem reescrever o código
• ✅ O SDK converte a assinatura da função em JSON Schema automaticamente
• ✅ O modelo decide o fluxo — incluindo quais URLs checar e quantas vezes
• ✅ Escala fácil: adicionar ferramentas é só decorar mais funções
• ⚠️ Você passa a depender de um provedor de LLM (custo e latência)
• ⚠️ O modelo pode interpretar instruções de forma inesperada
• ⚠️ Ferramentas mal documentadas geram chamadas ruins

Passo 1: instalar o Agents SDK

Crie um projeto e instale os pacotes necessários:

mkdir website-agent
cd website-agent

# com uv (recomendado)
uv init
uv add openai-agents requests

# ou com pip
pip install openai-agents requests

Defina sua chave de API da OpenAI:

export OPENAI_API_KEY="sua-chave-aqui"

O Agents SDK fornece um runtime leve para agentes, ferramentas, handoffs, sessões e tracing.

Passo 2: transformar a função em ferramenta

Mantemos quase toda a função original. A mudança principal é adicionar o decorador @function_tool:

from time import perf_counter
import requests
from agents import function_tool

@function_tool
def check_website(url: str) -> str:
    """Check a website's HTTP status and response time."""
    start = perf_counter()
    try:
        response = requests.get(url, timeout=10)
        latency = perf_counter() - start
        return (
            f"URL: {url}\n"
            f"Status: {response.status_code}\n"
            f"Response time: {latency:.2f}s"
        )
    except requests.RequestException as error:
        return f"URL: {url}\nError: {error}"

O SDK converte a assinatura da função no JSON Schema que o modelo espera e usa o nome e a docstring para descrever a ferramenta. Não é preciso montar o schema manualmente.

Passo 3: criar o agente

Agora criamos um Agent, definimos o que ele deve fazer e damos acesso à ferramenta:

from agents import Agent, Runner

agent = Agent(
    name="Website Monitor",
    model="gpt-5.6-luna",
    instructions="""
    Monitor websites using the available tool.
    Compare results and explain problems clearly.
    """,
    tools=[check_website],
)

result = Runner.run_sync(
    agent,
    "Check python.org, github.com, and openai.com. "
    "Which one has the slowest response?"
)
print(result.final_output)

O resultado sai assim:

python.org is the slowest, responding in 1.59 seconds.
- github.com: 0.83s
- openai.com: 0.49s
All returned HTTP 200.

Antes, seria preciso escrever o loop e a comparação manualmente. Agora o modelo interpreta o pedido, chama check_website() para os três sites, recebe os resultados, compara e produz a resposta.

Como o loop do agente funciona

Nos bastidores, o Runner gerencia a interação entre o modelo e as ferramentas: o modelo decide que precisa de informação, chama a ferramenta com os argumentos corretos, recebe o resultado e continua até ter uma resposta final. Se precisar de mais dados, chama a ferramenta de novo — o loop se repete até o modelo encerrar.

Troubleshooting: erros comuns

• ❌ Erro de chave de API → OPENAI_API_KEY não exportada ou inválida. Confirme com echo $OPENAI_API_KEY e reexporte.
• ❌ “model not found” → o nome do modelo não existe na sua conta. Troque model= por um disponível no seu plano.
• ❌ Função não é chamada → a docstring da ferramenta é vaga. Descreva exatamente quando o modelo deve usá-la.
• ❌ Timeout nas requisições → o timeout=10 dentro da função pode ser curto demais para sites lentos. Aumente para 20-30.
• ❌ Resposta fora do esperado → refine as instructions com exemplos do formato desejado.

FAQ

Preciso pagar pelo Agents SDK? Não. O SDK é gratuito; você paga apenas pelas chamadas de API do modelo que usar.

Posso usar outro modelo além da OpenAI? Sim — o SDK suporta provedores compatíveis com a API, bastando apontar a base_url correta.

Quantas ferramentas um agente pode ter? Não há limite rígido, mas ferramentas demais confundem o modelo. Comece com poucas e bem documentadas.

Isso substitui meu código Python? Não. O agente orquestra as chamadas; a lógica das funções continua sendo seu código Python.

Como saber se a ferramenta foi chamada? Ative o tracing do SDK ou adicione print() dentro da função para depurar o fluxo.