Drivers de navegador e de desktop

Um driver converte chamadas de ferramenta permitidas em ações em um navegador ou desktop que você controla. Use um driver de navegador quando seu aplicativo puder informar o texto da página, os controles e as abas. Use um driver de computador quando o modelo precisar trabalhar com capturas de tela e coordenadas. O SDK envia solicitações e despacha chamadas. Seu aplicativo gerencia a sessão, as permissões e a liberação dos recursos.

Configure os controles comuns

Comece pelo exemplo de navegador em Python ou Node. Ele inclui um driver completo, uma política de confirmação e uma execução da API Responses com limite de solicitações. Mantenha a sessão aberta até o fim da execução. Em Python, também há as classes síncronas BrowserToolset e ResponsesToolRunner para drivers síncronos.

Aprove as ações e gerencie a sessão

Crie drivers e callbacks de aprovação no código confiável do aplicativo. Mantenha a configuração executável separada dos dados não confiáveis da página e retorne esses dados pelos campos declarados no relatório do driver.

Um método selecionado do navegador que altera o estado ou lê dados de diagnóstico exige confirm. Apenas o valor exato true em Node ou True em Python aprova uma ação. navigate e new_tab também exigem urlPolicy (Node) ou url_policy (Python). Os dois callbacks recebem um objeto independente com member, os arguments validados, o state anterior e call_id. O callback da política de URLs também recebe a URL solicitada. Alterar esse objeto não modifica a ação validada.

confirm aprova os argumentos já fixados para a ação. Seu state registra uma observação anterior e não bloqueia o documento nem o controle em foco. A página pode navegar para outro endereço ou mudar o foco enquanto a pessoa decide. Se o consentimento se aplicar a uma página ou controle específico, o driver deverá verificar o alvo original no momento da execução. Nesse fluxo, desabilite key e recuse type quando o alvo for nulo, pois ambos usam o foco atual. Vincule da mesma forma ao alvo as demais ações que dependem do estado atual do navegador.

Para pedir confirmação antes de ler uma página privada, liste os membros de leitura em confirmReads (Node) ou confirm_reads (Python). O mesmo callback confirm é executado antes de qualquer leitura de estado ou conteúdo pelo driver. Nesse contexto, a fase é phase: "before_read" e o estado é state: null em Node ou None em Python. Trate esse caso sem ler os metadados da página. Em caso de recusa, nenhum conteúdo ou estado da página é retornado. Sem essa opção, as leituras existentes mantêm o comportamento atual e as aprovações obrigatórias de ações continuam em vigor.

Nas chamadas de computador, aprove todas as verificações de segurança pendentes antes que o auxiliar execute qualquer ação. Em Node, approveSafetyChecks e, em Python, approve_safety_checks devem retornar exatamente o valor booleano verdadeiro. Se o callback estiver ausente ou negar a aprovação, a execução será interrompida. O callback opcional beforeAction ou before_action verifica cada ação imediatamente antes da execução, inclusive a captura de tela final. Se fornecido, ele também deve aprovar a ação explicitamente. Nem uma escolha do modelo nem uma mensagem de conclusão podem conceder aprovação. Consulte as orientações de segurança para Uso do computador.

Em Node, os dois callbacks de aprovação de ações do computador recebem { signal } como último argumento. Em Python, o callback recebe o argumento nomeado opcional cancelled se o aceitar. Os callbacks existentes com menos argumentos continuam compatíveis. Use esse contexto para fechar uma solicitação de aprovação pendente quando a execução parar. O auxiliar aguarda o término do callback antes de liberar a sessão.

A aprovação de uma ação do computador abrange os argumentos fixados para ela. A tela e o foco podem mudar enquanto a pessoa decide. Se o consentimento se aplicar a um alvo específico, o driver deverá vincular a ação a esse alvo ou recusá-la após uma mudança de estado. Execute as ações do computador em um ambiente isolado com acesso limitado à rede.

Restrinja as URLs

Habilite navigate ou new_tab apenas se a tarefa precisar deles. Forneça confirm e urlPolicy em Node ou confirm e url_policy em Python. O callback de URL recebe (context, url), com um contexto de execução opcional em Node ou o argumento nomeado cancelled em Python. Ele deve retornar exatamente o valor booleano verdadeiro para que o SDK prossiga para confirm. Uma nova aba em branco com URL nula também exige confirmação, mas não há URL a verificar.

Analise a URL solicitada. Compare o protocolo, o nome do host e a porta com os destinos permitidos para a tarefa. Não valide apenas o prefixo da string. https://example.com.evil.test não pode ser aceito como https://example.com. Um driver de navegador sem navegação não precisa de callback de URL. O exemplo de navegador mantém esses métodos desabilitados.

Aplique também uma política de rede no navegador ou no ambiente. O callback verifica a navegação solicitada, mas não consegue restringir redirecionamentos, pop-ups, scripts da página ou recursos incorporados. Mantenha a mesma sessão isolada entre solicitações e feche os recursos que seu aplicativo criou. Deixe os recursos emprestados sob a responsabilidade de quem os forneceu.

Verifique o consumo e os tempos de execução

Com ResponsesToolRunner, passe onDiagnostic em Node ou on_diagnostic em Python a run. Para cada solicitação concluída da API Responses, o callback recebe um registro com api: "responses", stage: "request", reason: "completed" e usage. O consumo inclui input_tokens, output_tokens e total_tokens quando a API fornece esses dados. Caso contrário, o valor é null em Node ou None em Python. Para medir o consumo da execução, some os valores de cada campo de tokens em todas as solicitações concluídas. Se faltar o consumo de alguma solicitação, os totais estarão incompletos.

ComputerToolset.run não informa o consumo das solicitações pelo callback de diagnóstico. A resposta retornada pode conter o consumo apenas da última solicitação. Use ResponsesToolRunner com ComputerToolset quando precisar do consumo por solicitação.

Os registros de diagnóstico também identificam a API, a etapa, o motivo, o ID da chamada, o membro e a duração medida. Eles não contêm o erro bruto, o texto da página, os argumentos nem a imagem. Uma falha no observador não pode aprovar uma ação nem alterar seu resultado. Se seu aplicativo incluir dados privados nos IDs de chamada ou nos nomes dos membros, não os publique nos logs.

Use um observador síncrono. O executor não aguarda o processamento dos diagnósticos. Agende no aplicativo qualquer gravação assíncrona.

Os tempos das etapas podem se sobrepor nas execuções antecipadas, pois o tempo de recebimento do fluxo pode incluir o tempo das ações. Não some essas medidas para calcular a duração total da execução.

Encerre e cancele operações

O auxiliar rejeita chamadas simultâneas com um erro que indica que está ocupado. O executor também rejeita uma segunda execução ativa na mesma instância. Atribua a responsabilidade por cada sessão de navegador ou desktop a um único componente.

Chame close() no auxiliar para recusar novas operações. Seu status é closed quando não há mais chamadas ativas ou draining quando uma chamada anterior ainda pode produzir efeitos. Se o status for draining, aguarde o término da chamada de execução original antes de fechar o driver ou transferir o controle da sessão. O auxiliar não fecha o navegador nem o desktop. Chamar close() dentro de um callback do driver não faz com que ele aguarde esse mesmo callback.

Em Node, os métodos do driver e as funções comuns que cooperam com o cancelamento podem aceitar um segundo argumento de contexto com signal. Em Python, os métodos podem aceitar o argumento nomeado cancelled. Verifique o cancelamento durante operações demoradas, inclusive navegação e capturas de tela. Os callbacks existentes de um argumento continuam válidos, mas o SDK não consegue forçá-los a parar nem desfazer um efeito.

Contrato do driver de navegador

Implemente state() e apenas as operações que pretende disponibilizar. Em Node, os métodos podem retornar um valor ou uma promessa. Em Python, há classes distintas para execução síncrona e assíncrona. Cada operação recebe os argumentos validados em um único objeto ou dicionário. Para IDs de aba e alvos que podem ficar sem valor, use explicitamente null em Node e None em Python.

Em Python, o SDK rejeita incompatibilidades conhecidas entre métodos síncronos e assíncronos na criação do auxiliar. Use métodos async def com AsyncBrowserToolset. Ao encapsular métodos, preserve os metadados dos decoradores ou as anotações de retorno. Os wrappers opacos são verificados no momento da chamada. Protocolos opcionais como BrowserReadDriver e AsyncBrowserReadDriver ajudam a tipar um driver parcial sem implementar todas as operações. Em Node, o SDK exporta BrowserArguments<Member> e BrowserResult<Member> para as entradas e saídas correspondentes.

state() retorna tabs, um array de objetos com id, title, url e active. Use IDs estáveis e marque a aba que realmente está ativa. Exclua credenciais e informações privadas dos títulos e das URLs. O SDK retorna o estado atual após as operações comuns, inclusive quando falham. Quando uma leitura protegida é recusada, o SDK retorna uma resposta de recusa predefinida sem ler nem expor o estado. Se uma leitura obrigatória do estado falhar, a execução será interrompida. Em Node, os leitores de estado recebem { signal }. Em Python, podem aceitar o argumento nomeado cancelled. Use esse contexto para encerrar leituras de estado pendentes quando o código que iniciou a execução a interromper. Os leitores existentes sem argumentos continuam compatíveis.

O estado das abas informa as origens HTTP e HTTPS, como https://example.com:8443, sem credenciais, caminhos, parâmetros de consulta ou fragmentos. O estado legado, sem metadados de observação, preserva about:blank e informa apenas o esquema das demais URLs, como data: ou file:. O limite de 2.048 bytes em UTF-8 se aplica ao valor informado. Assim, um caminho de página longo não impede a leitura do estado. Quando há metadados de observação V1, o estado limita os títulos a 1.024 bytes em UTF-8, sem cortar caracteres pela metade, e define title_truncated quando necessário. Os títulos e o conteúdo da página continuam sujeitos às regras de privacidade do aplicativo.

Selecione os métodos

Por padrão, o SDK disponibiliza os 18 métodos a seguir quando implementados e deriva list_tabs de state(). Não implemente list_tabs. A lista members permite disponibilizar menos métodos ou habilitar explicitamente os métodos de leitura por escopo e de ponteiro ou os métodos de diagnóstico, scripts e arquivos. Os nomes devem ser únicos e corresponder a membros predefinidos que o driver implemente. Apenas list_tabs dispensa a implementação de outro método além de state(). Uma lista vazia não disponibiliza nenhum método. Na construção, o SDK copia a seleção e mantém sua própria ordem de ferramentas. Ele rejeita chamadas desabilitadas antes de ler o estado ou pedir consentimento.

Para adicionar um método opcional e manter os métodos padrão implementados, use additionalMembers em Node ou additional_members em Python. Não combine essa opção com members. O método a adicionar deve existir no driver. BROWSER_MEMBERS e DEFAULT_BROWSER_MEMBERS listam os nomes predefinidos sem inspecionar um driver.

Desabilitar list_tabs não oculta o estado retornado por outras operações bem-sucedidas. Em Python e Node, members filtra os métodos do auxiliar de navegador. Os nomes das funções comuns podem começar com browser_, mas não podem coincidir com o nome de uma ferramenta de navegador habilitada.

Exceto em switch_tab e close_tab, o tab_id da tabela pode ser nulo. A direção pode ser up, down, left ou right. Em Node, BrowserArguments<Member> descreve o objeto de argumentos de cada método. Em Python, o SDK disponibiliza tipos de entrada nomeados, como TabInput, ReadPageInput e ClickInput.

Em read_page, find e get_page_text, retorne null ou nenhum valor em Node, ou None em Python, para fornecer apenas o estado atualizado do navegador. Retorne uma string vazia quando a leitura for concluída sem texto.

Em Node, todas as operações dessa tabela, exceto list_tabs, recebem { signal } como segundo argumento. list_tabs usa o leitor de estado descrito acima. Em Python, o SDK passa cancelled como argumento nomeado quando o método o aceita. Use esse contexto para interromper operações pendentes, inclusive navegação e entrada de dados. Os métodos existentes de um argumento continuam compatíveis.

Em wait_for, use texto não vazio de até 256 bytes em UTF-8 após a normalização dos espaços em branco. O tempo limite deve ser de 1 a 30.000 milissegundos. Após scroll_to, leia novamente a página atual antes de interagir com um controle.

Retorne leituras estruturadas

read_page, find e get_page_text podem retornar BrowserReadV1, com version: 1, o texto visível em text, um array elements e um array omitted. Cada elemento tem uma referência ref única, um label não vazio e um dos sete papéis possíveis: button, textbox, combobox, checkbox, radio, slider ou listbox.

Informe o value de um campo ou suas options (pares de label e value) apenas quando o aplicativo permitir que o modelo veja esses dados. Uma caixa de seleção ou um botão de opção pode informar o booleano checked. As opções de listbox podem informar o booleano selected. O SDK omite esses campos nos demais papéis. Em Node, o SDK omite os campos opcionais definidos como undefined e rejeita valores null nesses campos. get_page_text deve retornar um array elements vazio. O SDK não converte uma string comum em leitura estruturada.

O SDK não limita a quantidade de elementos ou opções, o tamanho do texto da página nem o tamanho total do relatório. As referências e os rótulos têm limite de 256 bytes, e os valores, de 512 bytes. Use valores escalares Unicode válidos. Para indicar cobertura parcial, os drivers podem usar códigos sem repetição em omitted: report_limit, text_limit, target_limit, work_limit, frame_limit, unsupported_root, unsupported_control, remote_action, private, value ou name_limit.

O driver é responsável pela visibilidade, pela privacidade dos campos e pela validade das referências. Após a aprovação, confira novamente a referência na página atual antes de agir. O rótulo de um controle não concede permissão para ler seu valor. Limites de tamanho, por si só, não garantem que o conteúdo da página seja seguro.

Retorne imagens do navegador

screenshot e zoom retornam um input_image nativo com pelo menos um dos campos image_url ou file_id preenchido. Os dois campos de origem podem estar presentes. Cada origem não nula deve ser uma string não vazia. Os campos aceitos são type, image_url, file_id, detail e prompt_cache_breakpoint. Um ponto de interrupção do cache deve ter o valor { mode: "explicit" }. Um valor nulo também é aceito quando o tipo de conteúdo nativo o permite. O SDK valida e copia esses campos antes de retornar a imagem. Em Node, ambos os métodos retornam ResponseInputImageContent, em que detail pode ser omitido ou nulo. Ao defini-lo, use auto, low, high ou original.

Em zoom, region segue o formato [left, top, right, bottom]. As coordenadas devem ser inteiros seguros não negativos e definir uma região com largura e altura positivas. Cabe ao driver recortar a imagem e verificar os limites. Todas as coordenadas posteriores continuam relativas à área visível inteira.

Habilite os métodos de leitura por escopo e de ponteiro

Esses seis métodos de navegador ficam desabilitados por padrão, mesmo nos drivers que os implementam. Selecione-os com members ou adicione-os com additionalMembers em Node ou additional_members em Python. Os 18 métodos padrão originais mantêm seus nomes, argumentos e tipos de resultado. Ao usar members, inclua os métodos padrão de que ainda precisa, como screenshot ou read_page.

Em Node, use BrowserArguments<Member>. Em Python, o SDK exporta ReadPageScopedInput, ClickAtInput, DragPathInput, HoldKeysInput, HoverAtInput e SetCheckedInput. Todos os campos são obrigatórios. Para a aba ativa, tab_id pode ser null ou None. Campos desconhecidos são rejeitados, inclusive campos extras em um ponto do trajeto. Os números devem ser inteiros seguros e finitos. Em Python, True e False são rejeitados onde se exige um número.

click_at aceita coordenadas x e y não negativas, button definido como left, right ou middle e click_count definido como 1, 2 ou 3. drag_path aceita de 2 a 100 pontos exatamente no formato {x, y}, com coordenadas não negativas. Ambos usam a área visível inteira da página em pixels CSS, mesmo após aplicar zoom. O driver deve verificar os limites atuais. O campo keys de cada método contém uma lista sem repetições dos modificadores Control, Alt, Meta ou Shift. A lista pode estar vazia.

hover_at move o ponteiro para as coordenadas CSS atuais sem manter um botão pressionado. set_checked define uma caixa de seleção com o estado booleano solicitado. Defini-la como verdadeira duas vezes deve deixá-la marcada. Mesmo quando nada muda, a operação deve usar o alvo original ainda válido e obter confirmação. Não aceite um controle desatualizado ou substituído.

hold_keys recebe de 1 a 8 nomes de teclas únicos e não vazios, cada um com até 64 bytes em UTF-8 e valores escalares Unicode válidos. duration_ms deve estar entre 1 e 3.000. Os métodos que alteram o estado exigem que confirm retorne exatamente o valor booleano verdadeiro. Os métodos que cooperam com o cancelamento recebem um contexto específico da chamada. Em Node, o SDK passa { signal } como segundo argumento. Em Python, passa o argumento nomeado cancelled quando o método o aceita. Os métodos existentes de um argumento continuam válidos.

Leia o conteúdo de uma seção

Em read_page_scoped, um root nulo permite descobrir as seções visíveis. Se a raiz não for nula, ela deve ser uma referência de escopo emitida pelo driver, e não um seletor. A referência deve ser não vazia, conter Unicode válido e ter até 256 bytes em UTF-8. Defina depth entre 1 e 32 e filter como all ou interactive. A profundidade mede o percurso no DOM dentro dessa raiz, independentemente dos limites de frames ou de árvores shadow DOM.

Retorne BrowserScopedReadV1, que acrescenta scopes: [{ref, label}] à leitura existente. As referências e os rótulos devem ser não vazios, conter Unicode válido e ter até 256 bytes em UTF-8. As referências de escopo devem ser únicas e não podem coincidir com referências de elementos. Esse método rejeita resultados do tipo string e resultados nulos. O SDK copia os campos conhecidos antes de solicitar o estado final.

Use referências de escopo apenas para selecionar outra raiz de leitura. Operações que alteram elementos devem rejeitá-las. Invalide as referências de escopos e de elementos em conjunto quando houver mudança de aba, documento, geração ou visibilidade. Mantenha as regras de privacidade dos campos e os limites existentes de trabalho total e de leitura.

Habilite diagnósticos, scripts e transferências de arquivos

Esses quatro métodos também ficam desabilitados por padrão. Selecione cada um em members ou adicione-o com additionalMembers ou additional_members. Forneça confirm inclusive para leituras de diagnóstico. Implementar os métodos no driver não basta para disponibilizá-los ao modelo.

Em read_diagnostics, escolha console ou network como origem e um limite de 1 a 100. Retorne uma leitura estruturada com um array elements vazio. Em Node, use o tipo de resultado BrowserTextReadV1. O driver deve filtrar dados privados e limitar o histórico. Não retorne cabeçalhos brutos, cookies, credenciais ou mensagens de console sem filtragem.

run_script recebe código-fonte não vazio com Unicode válido e um tempo limite de 1 a 30.000 milissegundos. O SDK preserva o código-fonte integral. Retorne texto com Unicode válido. Uma string vazia é válida, mas um resultado nulo não é. O SDK preserva resultados grandes. Os scripts são executados com os privilégios da página. Use uma sessão nova sem credenciais, restrinja o acesso à rede e descarte a sessão se houver incerteza sobre a execução. Interromper a espera local não garante que o script da página tenha parado.

Os métodos de arquivo aceitam apenas um grant_id emitido por quem faz a chamada. Ele deve ser não vazio, conter Unicode válido e ter até 256 bytes em UTF-8. A autorização identifica um único arquivo aprovado para aquela tarefa. Não é um caminho nem uma URL. O responsável pelo arquivo deve obter uma aprovação separada para ele, verificar novamente a validade e a titularidade da autorização, aplicar limites de tamanho e permitir seu uso uma única vez. A confirmação do navegador não substitui a aprovação do arquivo.

Retorne exatamente version, status, effect e cleanup. Defina version como 1. Os valores aceitos para cleanup são not_started, pending e completed. A tabela mostra as combinações válidas de status e efeito.

O SDK copia e valida esse resultado antes de solicitar o estado final do navegador. Apenas completed define o campo ok da saída da ferramenta como verdadeiro. Nos demais casos, o resultado estruturado é preservado com ok falso, e o executor pula as chamadas de navegador dependentes nessa resposta. Verifique o arquivo e o estado real do aplicativo antes de repetir uma transferência de resultado desconhecido. O resultado de uma operação de arquivo não comprova que um envio de formulário ou uma operação de negócio posterior teve êxito.

run_script, upload_file e download_file recebem informações de cancelamento por chamada. Em Node, o SDK passa { signal } como segundo argumento. Em Python, passa o argumento nomeado cancelled. Em Python, o SDK exporta ReadDiagnosticsInput, RunScriptInput e BrowserFileInput.

Contrato do driver de computador

Um driver de computador recebe ações nativas do computador e retorna capturas de tela. Ele deve implementar os métodos a seguir. Em Node, importe ComputerDriver de openai. Em Python, importe ComputerDriver ou AsyncComputerDriver de openai. Importe também a classe correspondente, ComputerToolset ou, em Python, AsyncComputerToolset, de openai.

Os métodos de ação recebem o objeto de ação de computador já gerado, com os nomes de campos em snake_case, e não retornam valor. Se não conseguirem executar a ação, devem lançar um erro. Não ignore silenciosamente entradas incompatíveis. Em Node, os métodos podem retornar resultados síncronos ou promessas. Em Python, aguarde o término dos métodos assíncronos.

Em Python, use métodos síncronos com ComputerToolset e métodos async def com AsyncComputerToolset. O auxiliar rejeita incompatibilidades conhecidas no momento da criação. Ao encapsular métodos, preserve os metadados dos decoradores ou as anotações de retorno. Os wrappers opacos são verificados quando chamados, portanto seu código pode ser executado antes que o auxiliar detecte uma incompatibilidade.

Em Node, use ComputerCallInput nas chamadas que passar a ComputerToolset.execute(). Ele aceita chamadas nativas e chamadas modernas com um array actions que omitem pending_safety_checks. Nesse caso, os callbacks de aprovação recebem uma cópia independente da chamada com uma lista de verificações vazia. A chamada reenviada mantém os campos originais.

screenshot() retorna um computer_screenshot com image_url (que pode ser uma URL de dados) ou file_id. Os auxiliares de computador exigem pelo menos uma origem de imagem e aceitam os dois campos de origem juntos. O auxiliar não lê arquivos locais. As ações são executadas uma única vez, em ordem, e o auxiliar faz a captura de tela final após executá-las. Ele não repete ações do driver.

Para um loop da API Responses que use apenas o computador, use ComputerToolset.run ou, em Python, AsyncComputerToolset.run. Escolha um modelo disponível para seu projeto que ofereça suporte à ferramenta de computador. Para execuções mistas, passe o auxiliar de computador na opção computer do executor da API Responses. Em Node, os callbacks de computador são passados na opção de execução computerOptions. Em Python, passe approve_safety_checks e before_action diretamente como argumentos nomeados da execução. O exemplo de navegador controla apenas um navegador. Ele não implementa nem verifica um desktop nativo.

Tanto o auxiliar de computador quanto ResponsesToolRunner aceitam a compactação da API Responses por meio de context_management. Eles verificam os campos obrigatórios dos itens e reenviam o conteúdo criptografado sem alterações. Com ResponsesToolRunner, escolha essa opção nativa ou a opção local contextBudget ou context_budget. Não as combine.

Execute uma tarefa com capturas de tela

Execute sua primeira tarefa inclui um exemplo completo em Python ou Node. O exemplo usa a ferramenta de computador da API Responses para exibir os detalhes da retirada em um navegador local.

Use um desktop isolado

Para controlar o desktop de um sistema operacional, consulte o exemplo completo em Python ou Node. Ambos usam um sistema Linux convidado isolado. Em Macs com Apple silicon, o sistema convidado roda em uma máquina virtual. Em Linux x86-64, ele roda no Docker. Cada exemplo inclui um exercício local que dispensa chave de API. A tarefa que usa a API verifica tanto o registro no navegador quanto o arquivo salvo. Para configurar seu próprio ambiente, comece pelas instruções para Docker e adapte o contrato de driver descrito acima.

Combine ações de navegador com outras ferramentas

O executor da API Responses pode combinar auxiliares de navegador e computador com funções comuns, pesquisa na Web, pesquisa de arquivos, Code Interpreter, geração de imagens e ferramentas MCP remotas. Quando a solicitação seguinte reenvia a resposta, os resultados das ferramentas do servidor preservam seu conteúdo nativo e os IDs dos contêineres. Se houver resultados do servidor com falha, incompletos ou ainda em andamento, o turno será interrompido antes das ações locais.

Quando uma execução declara ferramentas do servidor, as chamadas locais aguardam a resposta completa, mesmo que eager esteja habilitado. Para agir com segurança, o executor precisa inspecionar os resultados do servidor e as solicitações de aprovação que chegarem depois.

Quando o turno estiver concluído, supplyOutputs em Node ou supply_outputs em Python poderá substituir o resultado de uma função comum cuja execução ainda não foi tentada, desde que o registro da função permita substituições. Isso também funciona sem uma política explícita de execução antecipada. Uma substituição não pode responder a chamadas de navegador ou computador nem a solicitações de aprovação MCP.

Esse executor precisa de respostas armazenadas para continuar após a geração de imagens. Ele rejeita store: false em Node ou store=False em Python quando você declara image_generation. Habilite o armazenamento quando apropriado ou use client.responses.create para uma única solicitação sem estado. O executor nunca habilita o armazenamento por conta própria.

Reutilize ferramentas de função tipadas para evitar repetir a validação. Em Node, encapsule uma zodResponsesFunction ou standardResponsesFunction com runnerFunction de openai/helpers/responses-tool-runner. A ferramenta deve incluir seu callback. Em Python, use RegisteredFunction.from_tool ou AsyncRegisteredFunction.from_tool com uma pydantic_responses_function_tool existente e um executor tipado explícito. Argumentos inválidos interrompem o processamento antes que esse executor seja chamado. Uma saída inválida do callback interrompe a execução sem repetir efeitos. Os registros diretos com RunnerFunction e RegisteredFunction mantêm o comportamento existente para os argumentos.

Para MCP, forneça approveMcp em Node ou approve_mcp em Python. O callback recebe uma cópia independente da solicitação real de aprovação e retorna verdadeiro ou falso. O executor vincula a resposta ao ID da solicitação e ao servidor declarado nela. Ele não pode conceder aprovação por conta própria nem interpretar uma mensagem final como consentimento.

Solicitações que declaram ferramentas MCP desabilitam as novas tentativas automáticas do SDK, com ou sem um registro persistente da execução. Se uma solicitação falhar, verifique o que o servidor MCP fez antes de iniciar outra execução.

Trate falhas

Lance BrowserError apenas para um problema recuperável, como uma referência desatualizada, e use somente texto que possa ser mostrado ao modelo com segurança. Outros erros lançados por uma operação do navegador geram uma mensagem genérica de falha. Nesses casos, o executor fornece uma saída para cada chamada de navegador, pula as operações de navegador restantes nessa resposta e permite que o modelo escolha novamente no turno seguinte. Um resultado retornado inválido ou um estado inválido interrompe a execução. A execução também é interrompida se o driver não conseguir informar o estado, se uma função comum falhar ou se uma verificação nativa de segurança do computador não for aprovada.

Defina maxSteps ou max_steps para limitar o número de solicitações à API. O padrão é 20. A última solicitação permitida não pode iniciar novos efeitos. Uma nova tentativa HTTP do SDK não repete uma ação do driver. Use signal em Node ou cancelled em Python para interromper a execução entre operações. Nem sempre é possível desfazer chamadas do driver que já estão em andamento.

ResponsesToolRunner preserva tool_choice em cada solicitação. Se a escolha sempre exigir uma ferramenta local, a execução não poderá terminar. Por isso, o executor rejeita essa escolha antes de iniciar qualquer operação. Use auto para um loop ou responses.create para uma única solicitação com escolha obrigatória. Escolhas obrigatórias que também permitem uma ferramenta declarada do servidor continuam válidas.

Solucione problemas de execução

Corrija cliques fora do alvo

Faça uma nova captura de tela e confira se ela mostra a janela desejada. Use o mesmo sistema de coordenadas para a captura e a ação. Se enviar uma captura de 800 × 600 de uma tela de 1600 × 1200, multiplique por dois as duas coordenadas retornadas antes de clicar. Se o driver de computador enviar uma captura recortada, ajuste primeiro a escala e depois some o deslocamento do recorte. Os métodos de ponteiro do driver de navegador usam pixels CSS relativos à área visível inteira da página, mesmo após aplicar zoom. Não os confunda com os pixels da tela.

O tamanho da captura afeta o consumo de tokens de entrada e o custo. Consulte as instruções para capturar telas para saber como dimensionar as imagens e quais são os limites dos modelos.

Use streaming e retome a execução

Por padrão, as execuções da API Responses não usam streaming. Com stream e onEvent (Node) ou on_event (Python), o executor fornece cópias independentes dos eventos do fluxo e aguarda o fim da resposta antes de executar as chamadas. Com eager, ele pode executar antecipadamente os itens de saída concluídos, na ordem em que devem ser executados. Ele nunca executa fragmentos incrementais de argumentos.

Habilite a execução antecipada apenas se for seguro executar um item concluído antes que o executor valide a resposta inteira. Se um evento posterior alterar ou remover esse item, o executor será interrompido e manterá o registro da execução do item. Ele não consegue desfazer a ação. Se todas as ações precisarem aguardar a validação da resposta completa, deixe a execução antecipada desabilitada ou use uma política vazia para ela.

Se os itens concluídos chegarem fora de ordem ou houver lacunas nos índices, o executor aguardará a resposta completa antes de executar essa parte da sequência. Se o fluxo falhar, os efeitos já concluídos continuarão registrados.

earlyExecution ou early_execution permite restringir a execução antecipada aos nomes de funções selecionados usados no protocolo e controlar o despacho de ações nativas do computador com um booleano separado. Um objeto vazio adia todas as ferramentas locais. Omitir a opção mantém o comportamento geral da execução antecipada. Ao adiar a primeira ferramenta, o executor também adia todas as seguintes para preservar a ordem. Com iterate(), inspecione o turno concluído antes de avançar. Encerrar a execução nesse ponto não executa nenhuma ferramenta adiada. Essas opções alteram o momento da execução e mantêm os requisitos de aprovação.

Para uma chamada concluída, beforeEarlyCall ou before_early_call pode retornar defer antes do despacho. Esse callback não pode antecipar chamadas fora da lista de permissões de execução antecipada. Marque uma função comum com independent: true apenas quando ela puder ser executada sem depender de outras ações. Sem um registro persistente, funções independentes podem ser executadas enquanto o fluxo avança. Execuções persistentes, ações de navegador e ações de computador mantêm a ordem. Operações iniciadas preservam seu registro de execução mesmo se outra chamada falhar.

Por padrão, no máximo duas chamadas antecipadas independentes são executadas ao mesmo tempo. Defina maxConcurrentCalls em Node ou max_concurrent_calls em Python como um inteiro positivo para alterar esse limite. O executor aguarda o término do grupo atual antes de ler mais chamadas do fluxo. Essa opção se aplica apenas a execuções antecipadas independentes sem registro persistente. Cada função deve limitar as operações que ela própria inicia.

Se uma execução antecipada for interrompida, examine ResponsesToolRunnerError.attemptedCallIds e completedCallIds em Node ou attempted_call_ids e completed_call_ids em Python. Esses campos contêm IDs de chamadas e não incluem resultados, argumentos nem mensagens do driver. É possível que já tenham ocorrido efeitos. Consulte a fonte de referência do estado do aplicativo antes de repetir uma ação já tentada ou de resultado incerto.

Use contextBudget ou context_budget para limitar os bytes de entrada e a quantidade de imagens da próxima solicitação, com ou sem armazenamento persistente. A projeção preserva as observações atuais e as relações necessárias entre as ferramentas. Um limite em memória não permite recuperar a execução após o encerramento do processo.

Ao fim de um turno concluído, appendUserText ou append_user_text coloca orientações humanas na fila. O executor as acrescenta após registrar as saídas pendentes. O método aceita texto, não aceita saídas arbitrárias de ferramentas nem objetos de aprovação e não reinicia a contagem de solicitações disponíveis.

Use esse método para esclarecer a tarefa atual, por exemplo, pedindo ao agente que confira outra data. Se o usuário substituir a tarefa, interrompa a execução atual e aguarde seu encerramento antes de iniciar outra. Leia novamente o estado do aplicativo e obtenha uma nova aprovação para as novas ações. Mantenha o registro da execução anterior, pois alterar as instruções não desfaz os efeitos dela.

Para poder recuperar a execução após uma interrupção, forneça um ledger que salve cada ponto de verificação enquanto um único componente detém o controle exclusivo da execução. Retome somente a partir do fim de uma etapa concluída. Se houver uma ação pendente ou de resultado incerto, é necessário reconciliá-la primeiro. A retomada preserva o saldo de solicitações disponíveis e o histórico concluído. A compactação local para respeitar o limite de contexto mantém todas as evidências no registro persistente e fixa as observações atuais, as verificações de segurança, as mensagens e o raciocínio. Ela nunca concede aprovação.

Cada operação de gravação recebe uma cópia independente e completa do ponto de verificação, inclusive nas gravações antes e depois de efeitos locais. O ponto de verificação inclui o lote inteiro e o histórico acumulado. Em lotes grandes, o trabalho total para copiar e armazenar esses registros pode crescer de forma quadrática. Escolha um armazenamento adequado a esse volume. contextBudget e context_budget limitam a entrada das solicitações, mas não o armazenamento do registro persistente.

Se houver uma interrupção, o ponto de verificação pendente conterá o trecho inicial salvo até a última gravação. Ele pode omitir texto posterior e propostas cuja execução ainda não foi tentada. Ele nunca autoriza a reexecução. Antes e depois de um efeito, o ponto de verificação salvo inclui todo o trecho inicial observado e os registros de execução.

Uma execução que inclui ferramentas MCP salva um ponto de verificação pendente antes de cada solicitação. Se a conexão falhar, verifique o que o servidor MCP fez antes de iniciar outra execução. Não é possível retomar automaticamente a partir do ponto de verificação pendente.

As declarações MCP salvas omitem os dados de autorização e os cabeçalhos personalizados e substituem as URLs dos servidores por identificadores SHA-256. As solicitações nativas continuam usando a URL original. Coloque as credenciais que precisam de rotação nos dados de autorização ou nos cabeçalhos. Alterar o caminho de uma URL ou um valor de consulta não reconhecido muda sua identidade e exige uma nova execução. Não é possível retomar a partir de pontos de verificação que contenham URLs MCP em formato bruto. Em Node, é necessário crypto.subtle.digest para salvar uma URL MCP. As demais entradas e saídas do ponto de verificação continuam sendo dados privados do aplicativo.

Ao retomar, forneça credenciais atuais e verifique se correspondem ao servidor e à conta pretendidos.

As declarações salvas do Code Interpreter preservam os nomes e domínios das credenciais, mas removem seus valores secretos. Ao retomar, forneça os valores atuais na configuração da ferramenta. Para aprovações MCP, um filtro vazio always: {} ou never: {} se aplica a todas as ferramentas.

Forneça approveMcp em Node ou approve_mcp em Python quando a entrada inicial ou um registro persistente salvo contiver solicitações MCP aprovadas. Antes da primeira gravação ou solicitação à API, o executor pede novamente cada aprovação para a qual não há uma chamada MCP correspondente concluída. Isso vale com ou sem registro persistente ou limite de contexto. O executor preserva as chamadas concluídas e as recusas anteriores. Se for necessária uma nova aprovação e o callback estiver ausente, a execução será interrompida.

Verifique um driver personalizado localmente

Execute o exercício local da demonstração de reservas ou do exemplo de desktop isolado antes de adaptá-lo. Acrescente verificações do estado real da página, dos efeitos das entradas e da liberação de recursos pelo driver. A validação do SDK não comprova que o ambiente executou uma ação corretamente.

Consulte Execute sua primeira tarefa para ver um fluxo de trabalho funcional com o SDK e as instruções de integração para configurar o ambiente. Após qualquer alteração, verifique o formulário salvo, o arquivo ou outro registro do aplicativo antes de informar que a ação foi bem-sucedida.