Tutorial da API GPT-6 Astra: construa um agente de verificação de release com ferramentas async e steering

O que é a API GPT-6 Astra?

A API GPT-6 Astra é como você acessa o novo modelo principal da OpenAI, lançado em 3 de setembro de 2026, pela Responses API. Para este tutorial, o que importa é a interface: gpt-6-astra aceita entradas de texto e imagem pela Responses API da OpenAI. Seu esforço de raciocínio vai de low a max, sem opção none. 

Os exemplos deste tutorial usam client.responses.create em vez de client.chat.completions.create, mas a migração também exige mudanças nos formatos de requisição, saída e resultado de ferramenta. Remova também as configurações personalizadas de temperature, top_p e probabilidades de log, já que a Astra não as suporta. Antes da primeira chamada, vamos ver os preços.

Quanto custa o GPT-6 Astra?

Para requisições com no máximo 272.000 tokens de entrada, o preço padrão é de US$ 10 por milhão de tokens de entrada comuns e US$ 50 por milhão de tokens de saída. Entrada em cache custa US$ 1 por milhão, e gravações de cache custam US$ 12,50 por milhão. 

Quando uma requisição ultrapassa esse limite, a OpenAI aplica um multiplicador de 2x nas taxas de entrada e cache e 1,5x na taxa de saída. As taxas mais altas se aplicam à requisição inteira, não apenas aos tokens acima do limite. Nenhuma execução neste tutorial chegou perto do limite.

O que vamos construir com a API GPT-6 Astra?

O app de staging é um pequeno quadro de tarefas em Flask: uma página inicial, um formulário para adicionar tarefa, um botão para marcar como concluída e um endpoint /health . O código completo, incluindo o app de staging, está neste repositório no GitHub.

Três tarefas pré-carregadas aparecem antes do teste. Imagem do autor.

O app tem uma falha intencional. O agente faz três checks, mas só a suíte de testes foi feita para pegá-la.

Por que o app aceita títulos de tarefa em branco?

O endpoint de criação de tarefa não rejeita título em branco. Mantive esse comportamento para que o agente tenha uma falha conhecida para encontrar sem revelá-la no prompt.

Quais checks de release o agente pode executar?

O agente pode chamar três ferramentas:

• run_test_suite roda o pytest, incluindo um teste de importação em lote com cerca de 250 requisições HTTP. 

• check_ui_flow usa o Playwright para adicionar uma tarefa e confirmar que ela aparece. 

• check_staging_health envia uma requisição GET para /health. 

As três rodam contra o staging, sem mocks. O check de navegador usa código fixo; a demo de uso de computador escrita pelo modelo vem depois.

Como configurar a API GPT-6 Astra em Python

Você precisa de uma chave da OpenAI API com acesso ao gpt-6-astra. Crie uma chave em platform.openai.com/api-keys e verifique se seu projeto tem o gpt-6-astra habilitado. Workspaces Enterprise vêm com a Astra desativada por padrão no lançamento.

Os comandos abaixo usam o Windows PowerShell e instalam todos os pacotes necessários para este tutorial, incluindo o realtime da OpenAI para a demo de steering.

python -m venv .venv
.venv\Scripts\Activate.ps1
Copy-Item .env.example .env
pip install "openai[realtime]" flask pytest playwright pydantic matplotlib python-dotenv streamlit
playwright install chromium

No macOS ou Linux, troque o comando de ativação por source .venv/bin/activate e o de cópia por cp .env.example .env. 

Depois adicione a chave da API ao novo arquivo .env: abra o .env que você acabou de copiar e inclua OPENAI_API_KEY=sk-..., que o python-dotenv carrega e o SDK pega automaticamente, então você nunca passa a chave em código.

Se dependências específicas do projeto ou arquivos .env são novidade para você, nossos guias de ambiente virtual e variáveis de ambiente explicam tudo. Confirme que a chave funciona antes de prosseguir.

Se sua chave já funciona com a Responses API, pule a próxima subseção e comece com o loop síncrono de ferramentas. A primeira requisição só verifica a configuração.

Faça sua primeira chamada à API GPT-6 Astra

Com a chave no lugar, ela precisa ser carregada usando dotenv. Depois disso, você pode criar um cliente OpenAI e enviar sua primeira requisição usando a função client.responses.create(). A menor requisição possível é assim:

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI()
response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "low"},
    input="In one sentence, what is a staging environment used for?",
)
print(response.output_text)

O campo usage da resposta lista as contagens de tokens necessárias para o cálculo de custo mais adiante.

Construa um loop síncrono de ferramentas no GPT-6 Astra

Os trechos abaixo são excertos; as versões executáveis estão no repositório no GitHub que acompanha.

Antes de tocar em qualquer coisa async, eu construí a versão comum: 

1. Chame o modelo

2. Verifique se há um item function_call

3. Rode a ferramenta correspondente

4. Envie o resultado de volta com previous_response_id

5. Repita até o modelo parar de pedir ferramentas. 

Esse loop bloqueante é o baseline para a comparação com async.

for turn in range(max_turns):
    response = client.responses.create(
        model="gpt-6-astra",
        reasoning={"effort": "low"},
        tools=TOOLS,
        input=next_input,
        previous_response_id=previous_response_id,
    )
    calls = [item for item in response.output if item.type == "function_call"]
    if not calls:
        final_text = response.output_text
        break
    outputs = [
        {"type": "function_call_output", "call_id": call.call_id, "output": run_tool(call)}
        for call in calls
    ]
    next_input, previous_response_id = outputs, response.id

O que o baseline encontrou

Na execução baseline, o modelo chamou cada ferramenta em sequência. Ele encontrou a falha de validação conhecida e retornou uma decisão de no-go. Em três execuções, o tempo médio de relógio foi de 23,40 segundos. Essa média cobre a execução inteira, não o tempo de cada ferramenta.

Como funciona a chamada assíncrona de ferramentas no GPT-6 Astra?

Marque uma ferramenta com "async": true no schema e seu app pode adiar esse resultado enquanto o modelo continua trabalhando ou espera. Seu aplicativo ainda roda a ferramenta e gerencia o job em segundo plano.

Como rodar checks independentes em paralelo

Marquei run_test_suite e check_ui_flow como assíncronos e adicionei uma ferramenta definida no app, wait_for_tasks, sem argumentos, já que esta demo sempre tem um único lote de trabalho pendente. Essa espera sem argumento mantém o exemplo enxuto. 

Em um executor de produção, identifique jobs com handles de tarefa, vincule cada handle ao seu call_id original e só espere quando o próximo passo depender de um resultado pendente.

Devolva cada resultado concluído no seu call_id original e depois retorne o status de espera no próprio call_id da ferramenta de espera.

TOOLS = [
    {"type": "function", "name": "run_test_suite", "async": True, ...},
    {"type": "function", "name": "check_ui_flow", "async": True, ...},
    {"type": "function", "name": "check_staging_health", ...},
    {"type": "function", "name": "wait_for_tasks", ...},
]

Nesta execução, o app enviou cada chamada marcada para um pool de threads. Enquanto os checks em segundo plano rodavam, ele fez o check rápido e síncrono de health. Em seguida, bloqueou em wait_for_tasks até os checks pendentes terminarem.

Chamadas assíncronas reduzem o tempo total?

Em três execuções, async reduziu o tempo médio de 23,40 segundos para 18,94 segundos (−19,1%). A média parecia simples até vermos as execuções individuais; o gráfico abaixo mostra o quanto variaram. Três execuções bastam para explicar o que aconteceu aqui, não para prever latência em produção.

Os tempos variaram nos dois modos. Imagem do autor.

Por que checks concorrentes causaram condição de corrida?

Executar o check de navegador e o teste de importação em lote ao mesmo tempo às vezes fez a asserção de importação em massa falhar porque ambos alteravam a mesma lista de tarefas em memória. Isso quebrou a suposição do teste de acesso exclusivo. Isolar os dados no executor ou nos testes evitaria a corrida.

Uso de computador com limites no GPT-6 Astra para testar UI

Para uso de computador, a doc do GPT-6 Astra recomenda execução de código, enquanto a ferramenta estruturada computer continua suportada como alternativa. Com execução de código, uma chamada pode combinar várias ações, loops e lógica condicional, enquanto a computer retorna uma ação estruturada de mouse ou teclado por vez para seu app traduzir e reproduzir.

Como limitar o executor de uso de computador

Eu chamei a classe de BrowserSandbox, mas o nome exagera a proteção. Ela dá ao código escrito pelo modelo uma page do Playwright, uma função log() e um helper expect_text() . O Python ainda pode injetar built-ins em exec(), e a página pode navegar para outra origem.

sandbox_globals = {"page": self.page, "log": log, "expect_text": expect_text}
exec(code, sandbox_globals)

Trate isto como um executor de demonstração, não um limite de segurança. Código escrito pelo modelo precisa de um processo ou contêiner isolado com restrições de filesystem, processos, rede e origem.

O que aconteceu no check de UI?

Limitei o loop a oito turnos porque um check com limites precisa de um corte duro. O modelo inspecionou a página, encontrou o input do formulário, criou o título "UI flow check, cobalt otter 73921", enviou a tarefa e confirmou que o título apareceu, o que levou 13 segundos. Nosso tutorial de uso de computador com o GPT-5.4 traz um exemplo detalhado usando um predecessor da Astra.

Como funciona o steering no meio do turno no GPT-6 Astra?

Steering no meio do turno está disponível apenas para o gpt-6-astra via conexão WebSocket.

Abra uma conexão e crie uma response, então envie um evento response.steer com novas instruções enquanto a resposta é gerada. Um evento response.steer.accepted significa que a atualização está enfileirada, não aplicada. Antes de criar a continuação automática, o servidor finaliza o item de saída atual e qualquer trabalho de ferramenta hospedada já em execução. 

Se ainda precisar de resultado de ferramenta do cliente ou aprovação, response.steer.pending identifica a entrada que falta.

async with client.responses.connect() as connection:
    await connection.response.create(model="gpt-6-astra", input=TASK)
    async for event in connection:
        if event.type == "response.created" and initial_response_id is None:
            initial_response_id = event.response.id
            await asyncio.sleep(1.0)
            await connection.response.steer(
                previous_response_id=initial_response_id,
                input="Also add a rollback plan, but skip mobile.",
            )

O atraso de um segundo replica o código do experimento e dá tempo para a primeira resposta começar. Sem esse atraso, estaríamos testando outro ponto do ciclo da resposta.

O que o steering no meio do turno não muda?

Steering não reescreve a resposta original. Se a atualização a interromper, essa resposta termina com status: "incomplete" e incomplete_details.reason: "steered". Uma resposta sucessora então continua com a nova instrução. 

Se a primeira resposta terminar antes da atualização surtir efeito, ela permanece concluída. Steering não desfaz nem cancela ações do lado do cliente que já começaram; seu aplicativo ainda é responsável por isso. Atualizações enfileiradas existem apenas na conexão WebSocket atual, então registre a atualização antes de tentar reconectar.

O caminho de comparação deixa a primeira resposta terminar e então envia uma nova requisição com as instruções combinadas. Em duas execuções, steering levou em média 26,91 segundos contra 50,02 segundos no caminho de finalizar e reiniciar. Esta comparação não cobre uma política de cancelar e reiniciar, nem avalia a correção do texto final.

Médias de duas execuções para tempo e custo. Imagem do autor.

O caminho de reinício gera duas respostas completas que cobrem parte das mesmas solicitações. Isso explica parte da diferença de tempo, então eu não trataria essas duas execuções como um benchmark geral para steering.

Como mudar o esforço de raciocínio do GPT-6 Astra no meio da conversa

gpt-6-astra suporta esforço de raciocínio de low até max. Esforço maior pode aumentar o uso de tokens de raciocínio, mas não garante resposta diferente. Um configuration_update muda as próximas respostas até outra atualização substituí-lo, enquanto a configuração no nível da requisição permanece igual. 

Neste pipeline, o relatório encerra a conversa, então a atualização afeta só esse passo final.

response = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=previous_id,
    reasoning={"effort": "low"},  # default remains low
    input=[
        {"type": "configuration_update", "reasoning": {"effort": "high"}},
        {"role": "user", "content": "Diagnose the root cause and recommend a fix."},
    ],
)

Usei o mesmo rastro de falha nos dois níveis de esforço e comparei diagnóstico e uso de tokens.

Um detalhe: o campo reasoning.effort da resposta ainda reporta a configuração do nível da requisição, não o esforço selecionado pelo configuration_update. Não use esse campo para checar se a atualização surtiu efeito.

Esforço alto mudou o diagnóstico?

Na execução combinada completa, o passo escalado usou 108 tokens de raciocínio. Todos os outros passos em low usaram zero. Em um teste isolado anterior com um rastro de falha mais longo, esforço baixo usou zero tokens de raciocínio e esforço alto usou 318. As duas versões identificaram o bug de validação, então aumentar o esforço mudou o consumo de tokens, mas não o diagnóstico.

Atualizações de configuração funcionam só em requisições padrão, de agente único. A API rejeita atualizações adjacentes, e elas não podem ser combinadas com compactação ou truncamento automáticos.

Como usar saídas estruturadas no GPT-6 Astra

O último passo do pipeline chama client.responses.parse para trocar texto livre por um modelo Pydantic validado.

class GoNoGoReport(BaseModel):
    decision: str
    summary: str
    checks_completed: list[str]
    failures: list[str]
    risks: list[str]
    follow_up_actions: list[str]
    confidence: float

response = client.responses.parse(
    model="gpt-6-astra",
    previous_response_id=previous_id,
    text_format=GoNoGoReport,
    input=[...],
)

O Pydantic checa os tipos de campo declarados aqui. Ele não prova que o relatório corresponde às evidências, e esta versão não restringe decision a dois valores nem confidence a um intervalo.

O que o relatório go/no-go pegou?

O relatório retornou decision: "no_go". Ele classificou a falha de validação citada antes em failures e a questão de concorrência em risks. Para esta última, escreveu: "possible interference from concurrent UI checks against shared staging data." O prompt não nomeou esse risco.

Mantenha latência e custo fora deste schema e calcule-os em código. O modelo preenche os campos do relatório a partir das evidências de ferramentas.

A interface em Streamlit consome o mesmo gerador do executor em linha de comando. Ela renderiza cada evento de ferramenta conforme chega e depois mostra o relatório parseado nas abas Relatório e JSON.

Progresso do agente ao vivo ao lado do relatório final. Vídeo do autor.

O dashboard roda o pipeline de release assíncrono combinado, com seu check de navegador fixo, atualização de raciocínio, relatório estruturado e exibição de tempos. O painel de custos lê o mesmo livro-razão do executor em linha de comando. Ele não roda as demos separadas de uso de computador escrito pelo modelo ou de steering.

Como rastrear uso de tokens e custo na API GPT-6 Astra

Na parte de tokens de modelo dessas execuções, o campo usage contém as quatro contagens de tokens necessárias para precificar cada resposta. Gravações em cache têm sua própria tarifa, então não agrupe com a entrada comum. As ferramentas aqui rodam no seu aplicativo; se você adicionar uma ferramenta hospedada com tarifa separada, inclua esse custo também.

details = usage.input_tokens_details
cached_tokens = details.cached_tokens
cache_write_tokens = details.cache_write_tokens
ordinary_tokens = usage.input_tokens - cached_tokens - cache_write_tokens

cost = (
    ordinary_tokens * PRICE_INPUT
    + cached_tokens * PRICE_CACHED_INPUT
    + cache_write_tokens * PRICE_CACHE_WRITE
    + usage.output_tokens * PRICE_OUTPUT
) / 1_000_000

Esse cálculo cobre uma resposta. O livro-razão o aplica após cada resposta e depois soma os totais da chamada.

Registre cache_write_tokens mesmo quando o valor for zero. Caso contrário, uma gravação futura pode se esconder dentro da contagem de entrada comum, e esse é um jeito chato de descobrir erro de cobrança.

Considerações de produção para o agente GPT-6 Astra

A demo precisa destas mudanças antes de poder barrar deploys.

Permissões e isolamento de ferramentas

Mantenha o limite de staging e isole o BrowserSandbox como descrito acima. Não dê credenciais de banco de dados nem acesso à produção.

Ciclo de vida de jobs assíncronos

Na demo, todo job pendente termina e nada mais o toca. Em produção, o executor precisa sobreviver quando nenhum dos dois é verdade. Para cada pendência, ele precisa de:

• Deadline e estado final, para nada ficar pendente para sempre
• Flag de entrega, para callback e retry não enviarem o mesmo resultado duas vezes
• Timestamps de início e fim, para diferenciar timeout de uma conclusão válida porém tardia
• Rejeição de chamadas duplicadas, para a mesma tarefa não ser lançada duas vezes
• Tratamento de erro em threads de fundo, para exceção não sumir no pool
• Cancelamento, o que implica ignorar resultado tardio e parar trabalho externo já em andamento

Steering e ações irreversíveis

Steering pode mudar instruções futuras, mas não reverte efeito colateral concluído. Se uma ferramenta já alterou um sistema externo, uma ação separada deve compensar.

Monitoramento de desalinhamento

Parada automática se aplica a requisições da Responses API que usam raciocínio persistido, WebSockets ou compactação da OpenAI. Outras requisições podem disparar alertas, mas não são paradas automaticamente. 

Antes do streaming, o monitoramento de desalinhamento pode bloquear uma execução coberta com HTTP 403 e o código misalignment_policy_violation. Um cliente em streaming pode receber erro após o início da saída. A API não oferece caminho geral de retomada para a conversa interrompida.

Checklist de deploy do agente GPT-6 Astra

Antes de levar este agente de uma demo local para produção, adicione estes controles. Eles pertencem ao código do app, não às instruções do modelo.

• Defina timeouts explícitos nas chamadas HTTP do app de staging e na conexão WebSocket

• Registre entrada comum, entrada em cache, gravações de cache, saída, ID da resposta e contagem de turnos

• Alerta para execuções incompletas ou que atinjam o limite de turnos. Defina alerta separado para estouro de orçamento

• Fixa a versão do SDK openai e revalide comportamento de async, steering e configuration_update antes de atualizar

Quando usar ferramentas async ou steering no GPT-6 Astra?

Escolha o caminho mais simples que atende ao trabalho.

• Comece com uma requisição síncrona e saídas estruturadas quando as ferramentas retornam rápido e os requisitos permanecem fixos.
• Adicione chamadas assíncronas quando o modelo ou outra ferramenta puder fazer trabalho útil durante uma chamada lenta, e o tempo economizado justificar a sobrecarga de gerenciar jobs.
• Use steering no meio do turno quando os requisitos mudarem durante a execução.

Considerações finais

O check de release síncrono ficou mais útil quando ferramentas lentas puderam se sobrepor, embora não tenha sido uma vitória limpa. Em três execuções, async reduziu o tempo médio de 23,40 segundos para 18,94 segundos e expôs uma corrida de estado compartilhado que o loop sequencial escondia. 

Eu isolaria o navegador e os dados de teste, manteria turnos rotineiros em low e elevaria o esforço de raciocínio só quando as evidências exigirem um olhar mais atento. Se as ferramentas terminam rápido e os requisitos não mudam, fique no loop síncrono com saídas estruturadas. Use async quando trabalhos independentes puderem se sobrepor e use steering quando instruções mudarem durante uma resposta.

Para o básico da API, recomendo fazer nosso curso Working with the OpenAI API. Para sistemas de agentes maiores, veja nosso curso Building Scalable Agentic Systems.