Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Agents SDK: Instalação e o Seu Primeiro Agente

Aula 4 de 25 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Agents SDK: Instalação e o Seu Primeiro Agente
  2. Pré-requisitos
  3. Instalação
  4. O Seu Primeiro Agente
  5. Execução Assíncrona
  6. Execução em Streaming
  7. Estrutura do Projeto do Agente
  8. Pontos-chave

Agents SDK: Instalação e o Seu Primeiro Agente

Vamos começar a programar. Vai instalar o SDK oficial de Agentes da OpenAI, criar um agente Python funcional e explorar os três modos de execução que utilizará ao longo deste curso.

Pré-requisitos

Precisa apenas de três coisas: Python 3.10+ instalado na sua máquina, uma conta OpenAI com uma chave de API ativa e um editor de código. Recomendamos o VS Code, mas qualquer editor com realce de sintaxe para Python funciona perfeitamente.

Instalação

O pacote chama-se openai-agents. Atenção: instalar apenas openai fornece-lhe o cliente clássico da API, não o SDK de Agentes.

pip install openai-agents

Este pacote instala automaticamente as dependências necessárias, incluindo o SDK Python da OpenAI. De seguida, defina a sua chave de API como uma variável de ambiente. O SDK lê-a automaticamente, pelo que não é necessária configuração adicional.

export OPENAI_API_KEY="sk-proj-your-api-key"

Este comando desaparece quando fecha o terminal e, certamente, não vai querer codificar a sua chave diretamente nos ficheiros de origem. Para uma configuração de projeto adequada, utilize um ficheiro .env com python-dotenv e adicione esse ficheiro ao seu .gitignore antes do primeiro commit.

pip install python-dotenv
# .env
OPENAI_API_KEY=sk-proj-your-api-key

O Seu Primeiro Agente

Crie um ficheiro chamado my_first_agent.py:

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant. Respond in English concisely.",
    model="gpt-5.6-terra",
)

result = Runner.run_sync(agent, "Explain what an AI agent is in three sentences.")
print(result.final_output)

Execute-o:

python my_first_agent.py

Acabou de criar e executar o seu primeiro agente. É simples — sem ferramentas, sem barreiras de segurança — mas constitui a base para todo o resto. O restante deste curso apenas constrói sobre estes dois objetos: Agent e Runner.

Execução Assíncrona

run_sync bloqueia o thread atual até que a resposta chegue. Isso é aceitável para um script de teste, mas inaceitável para um servidor web que lida com centenas de pedidos simultâneos. Em produção, utilizará o modo assíncrono.

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="Async Assistant",
    instructions="You are a helpful assistant. Respond in English.",
    model="gpt-5.6-terra",
)

async def main():
    result = await Runner.run(agent, "What are the advantages of Python for AI?")
    print(result.final_output)

asyncio.run(main())

Runner.run() é a versão assíncrona; Runner.run_sync() é um wrapper síncrono que a chama por si. Ao utilizar o FastAPI ou qualquer outra estrutura assíncrona, utilize sempre Runner.run().

Execução em Streaming

Existe um terceiro modo, essencial sempre que um humano está à espera perante o ecrã. O streaming apresenta a resposta à medida que é gerada, token por token.

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="Streaming Assistant",
    instructions="You are a helpful assistant. Respond in English.",
    model="gpt-5.6-terra",
)

async def main():
    result = Runner.run_streamed(agent, "Tell a short story about AI.")
    async for event in result.stream_events():
        if event.type == "raw_response_event":
            if hasattr(event.data, "delta") and event.data.delta:
                print(event.data.delta, end="", flush=True)
    print()  # New line at the end

asyncio.run(main())

O ciclo async for consome um fluxo de eventos. Aqui, filtramos eventos de resposta brutos do modelo e imprimimos apenas os fragmentos de texto. O streaming é crítico para a experiência do utilizador: ninguém quer olhar para um ecrã em branco durante 10 segundos.

Estrutura do Projeto do Agente

Um agente de produção não cabe num único ficheiro. Separe as definições dos seus agentes, ferramentas e testes desde o início, ou o seu main.py tornar-se-á rapidamente ilegível.

my-agent-project/
├── .env                 # API key
├── requirements.txt     # Dependencies
├── agents/
│   ├── __init__.py
│   ├── assistant.py     # Agent definition
│   └── tools.py         # Tool definitions
├── main.py              # Entry point
└── tests/
    └── test_agent.py    # Tests
# requirements.txt
openai-agents>=0.1.0
python-dotenv>=1.0.0

Pontos-chave

  • Instale o SDK com pip install openai-agents
  • Defina OPENAI_API_KEY como uma variável de ambiente
  • Utilize Runner.run_sync() para desenvolvimento e Runner.run() para produção assíncrona
  • Utilize Runner.run_streamed() para streaming em tempo real
  • Estruture o seu projeto com pastas separadas para agentes, ferramentas e testes