Uso do computador

O Uso do computador permite que um modelo opere interfaces de navegador e de desktop. Use esse recurso para preencher formulários, testar fluxos de usuário ou concluir tarefas em aplicativos por meio de suas interfaces.

Você fornece o ambiente e executa as solicitações do modelo. O modelo usa capturas de tela e outros resultados de ferramentas para decidir o que fazer em seguida. Escolha como conectá-lo ao seu aplicativo:

• Execução de código: O modelo escreve código que usa uma biblioteca como PyAutoGUI ou Playwright para operar a interface. Uma única chamada pode combinar ações, loops ou lógica condicional.
• A ferramenta de computador: O modelo retorna ações estruturadas de mouse e teclado que seu aplicativo converte em entradas para o navegador ou desktop.

Se você já expõe operações de interface por meio de chamada de função ou ferramentas MCP remotas, pode manter essa interface. Consulte Use suas próprias ferramentas de interface para entender as diferenças na forma como essas integrações executam ferramentas e retornam resultados.

Use a execução de código

Uma integração de execução de código fornece ao modelo uma ferramenta de função que aceita um script. Seu aplicativo executa o script em um ambiente isolado de navegador ou desktop e retorna a saída, incluindo capturas de tela. Mantenha o ambiente disponível entre as chamadas para que o modelo possa dar continuidade ao trabalho anterior.

Execute o aplicativo de exemplo

O aplicativo de exemplo de CUA inclui implementações em JavaScript/Playwright e Python/PyAutoGUI, com tarefas locais e um console compartilhado:

1. Siga as instruções de configuração da implementação escolhida em um ambiente isolado.
2. Escolha um dos cenários incluídos e inicie uma execução.
3. Inspecione as ações, as capturas de tela e o estado final para avaliar se a tarefa foi concluída com sucesso.

Consulte o README do aplicativo para obter informações sobre instalação, permissões de desktop e ambientes compatíveis. Leia Execute com segurança antes de adaptá-lo a sites ou contas reais.

Conecte seu próprio ambiente de execução

O exemplo a seguir mostra o ciclo da API para um ambiente de execução fornecido por você. Python e Ruby enviam código Python para um ambiente de execução de desktop que usa PyAutoGUI; JavaScript usa Playwright para operar um navegador. Cada cliente expõe uma ferramenta comum do tipo função e retorna texto ou imagens com o call_id original.

A função auxiliar execute_in_sandbox ou executeInSandbox envia código ao seu ambiente de execução e retorna suas observações. Ela deve preservar a sessão do navegador ou desktop, impor limites de execução e aplicar suas regras de permissão. Estes são exemplos de integração, separados da execução do aplicativo de exemplo.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72import json
import uuid

from openai import OpenAI
from openai.types.responses import (
    FunctionToolParam,
    ResponseInputParam,
)

def run_computer_use(endpoint, prompt, model="gpt-6-astra"):
    client = OpenAI()
    session_id = str(uuid.uuid4())
    tools: list[FunctionToolParam] = [
        {
            "type": "function",
            "name": "exec_py",
            "description": (
                "Run Python in a persistent desktop. Variables persist across calls. "
                "PyAutoGUI operations are synchronous. Available: pyautogui, time, "
                "log(value), and display(PIL_image). Inspect the screen with "
                "display(pyautogui.screenshot()) before acting. Use screenshot "
                "coordinates and check the screen after a short group of actions. "
                "Keep screenshots in memory and PyAutoGUI's fail-safe enabled."
            ),
            "parameters": {
                "type": "object",
                "properties": {"code": {"type": "string"}},
                "required": ["code"],
                "additionalProperties": False,
            },
            "strict": True,
        }
    ]
    next_input: ResponseInputParam = [{"role": "user", "content": prompt}]
    previous_response_id = None

    for turn in range(20):
        response = client.responses.create(
            model=model,
            tools=tools,
            input=next_input,
            previous_response_id=previous_response_id,
        )
        if response.status != "completed":
            raise RuntimeError(f"Response stopped with status: {response.status}")

        calls = [item for item in response.output if item.type == "function_call"]
        if not calls and any(
            item.type == "message" and item.phase != "commentary"
            for item in response.output
        ):
            print(response.output_text)
            return
        if turn == 19:
            raise RuntimeError(
                "The task reached the 20-response limit. Inspect the last result."
            )

        next_input = []
        for call in calls:
            if call.name != "exec_py":
                raise ValueError(f"Unexpected tool: {call.name}")
            code = json.loads(call.arguments)["code"]
            output = execute_in_sandbox(code, session_id, endpoint)
            next_input.append(
                {
                    "type": "function_call_output",
                    "call_id": call.call_id,
                    "output": output,
                }
            )
        previous_response_id = response.id

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74import { randomUUID } from "node:crypto";
import OpenAI from "openai";

async function runComputerUse(endpoint, prompt, model = "gpt-6-astra") {
  const client = new OpenAI();
  const sessionId = randomUUID();

  const tools = [
    {
      type: "function",
      name: "exec_js",
      description: `Run JavaScript in a persistent browser. Available: Playwright's
browser, context, and page objects; console.log(value); and display(base64Image).
Save reusable variables on globalThis. Inspect a screenshot before acting and
check the screen after a short group of actions. Keep screenshots in memory.
Use top-level await for async operations. Return images with display() and concise
text with console.log(). The context viewport is 1440x900.`,
      parameters: {
        type: "object",
        properties: { code: { type: "string" } },
        required: ["code"],
        additionalProperties: false,
      },
      strict: true,
    },
  ];

  let nextInput = [{ role: "user", content: prompt }];
  let previousResponseId;

  for (let turn = 0; turn < 20; turn++) {
    const response = await client.responses.create({
      model,
      tools,
      input: nextInput,
      previous_response_id: previousResponseId,
      reasoning: { effort: "low" },
    });
    if (response.status !== "completed") {
      throw new Error(`Response stopped with status: ${response.status}`);
    }
    const calls = response.output.filter(
      (item) => item.type === "function_call"
    );
    if (
      calls.length === 0 &&
      response.output.some(
        (item) => item.type === "message" && item.phase !== "commentary"
      )
    ) {
      console.log(response.output_text);
      return;
    }
    if (turn === 19) {
      throw new Error(
        "The task reached the 20-response limit. Inspect the last result."
      );
    }

    nextInput = [];
    for (const call of calls) {
      if (call.name !== "exec_js")
        throw new Error(`Unexpected tool: ${call.name}`);
      const { code } = JSON.parse(call.arguments);
      const output = await executeInSandbox(code, sessionId, endpoint);
      nextInput.push({
        type: "function_call_output",
        call_id: call.call_id,
        output,
      });
    }
    previousResponseId = response.id;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57require "json"
require "openai"
require "securerandom"

def run_computer_use(endpoint, prompt)
  client = OpenAI::Client.new
  session_id = SecureRandom.uuid
  tools = [
    {
      type: :function,
      name: "exec_py",
      description: "Run Python in a persistent desktop. Variables persist across calls. PyAutoGUI operations are synchronous. Available: pyautogui, time, log(value), and display(PIL_image). Inspect the screen with display(pyautogui.screenshot()) before acting. Use screenshot coordinates and check the screen after a short group of actions. Keep screenshots in memory and PyAutoGUI's fail-safe enabled.",
      parameters: {
        type: :object,
        properties: { code: { type: :string } },
        required: ["code"],
        additionalProperties: false
      },
      strict: true
    }
  ]
  next_input = []
  next_input << {
    role: :user,
    content: prompt
  }
  history = {}
  20.times do |turn|
    response = client.responses.create(
      model: "gpt-6-astra", tools: tools, input: next_input, previous_response_id: history[:id]
    )
    raise "Response stopped with status: #{response.status}" unless response.status == OpenAI::Responses::ResponseStatus::COMPLETED

    calls = response.output.grep(OpenAI::Responses::ResponseFunctionToolCall)
    if calls.empty? && response.output.any? { |item| item.is_a?(OpenAI::Responses::ResponseOutputMessage) && item.phase != :commentary }
      puts(response.output_text)
      return response
    end
    raise "The task reached the 20-response limit" if turn == 19

    next_input.clear
    calls.each do |call|
      raise "Unexpected tool: #{call.name}" unless call.name == "exec_py"

      code = JSON.parse(call.arguments).fetch("code")
      raise "Expected Python source text" unless code.is_a?(String)

      output = execute_in_sandbox(code, session_id, endpoint)
      next_input << {
        type: :function_call_output,
        call_id: call.call_id,
        output: output
      }
    end
    history[:id] = response.id
  end
end

Para obter um adaptador de cliente completo e o formato esperado da saída de texto e imagem, consulte Conecte-se ao seu serviço de execução. A interface de serviço desses exemplos pertence ao seu aplicativo; ela não é um endpoint hospedado pela OpenAI.

Preserve o estado e retorne observações

Mantenha a sessão do navegador ou desktop ativa entre as chamadas. Um namespace persistente de Python ou JavaScript também pode preservar variáveis. Descreva os objetos e as funções auxiliares disponíveis na definição da ferramenta para que o modelo saiba o que pode usar.

Forneça ao modelo uma captura de tela atual quando o estado da interface for desconhecido. Após um pequeno grupo de ações, retorne outra captura de tela para que ele possa conferir o resultado. Mantenha as imagens na memória e use detail: "original" para preservar a resolução. Se você reduzir a resolução de uma captura de tela, converta as coordenadas do modelo de volta para o espaço de coordenadas do ambiente antes de executar as ações. Consulte Captura de tela e resolução.

A conversa da API e o ambiente de execução têm estados separados. Preserve as chamadas de ferramentas e suas saídas na conversa e mantenha o ambiente correspondente disponível no seu aplicativo. Dar continuidade a uma resposta não restaura a sessão do navegador, o estado de login nem as variáveis do ambiente de execução.

Use a ferramenta de computador

Use esta alternativa quando sua integração esperar ações estruturadas em vez de código gerado. Para seguir a abordagem recomendada, comece pela execução de código.

Para experimentar essa opção, siga as mesmas instruções de configuração do aplicativo de exemplo, selecione o modo Nativo e execute um dos cenários incluídos. Use um modelo compatível com a ferramenta de computador.

A troca de mensagens com a API tem três etapas: enviar uma tarefa, executar as ações retornadas e retornar uma captura de tela. Os trechos de código aqui usam uma página com um controle Mostrar filtros e um campo de pesquisa. Adapte essa tarefa à sua própria interface ao integrar a ferramenta.

Para configurar o ambiente e implementar manipuladores de ações, use os exemplos de integração.

Envie a tarefa

Ative computer no array tools e descreva o resultado desejado:

1
2
3
4
5
6
7
8
9
10
11
12import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.6-sol",
  tools: [{ type: "computer" }],
  input:
    "Check whether the Filters panel is open. If it is not open, click Show filters. Then type penguin in the search box. Use the computer tool for UI interaction.",
});

console.log(JSON.stringify(response.output, null, 2));

1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6-sol",
    tools=[{"type": "computer"}],
    input="Check whether the Filters panel is open. If it is not open, click Show filters. Then type penguin in the search box. Use the computer tool for UI interaction.",
)

print(response.output)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5.6-sol",
		Tools: []responses.ToolUnionParam{{OfComputer: &responses.ComputerToolParam{}}},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Check whether the Filters panel is open. If it is not open, click Show filters. Then type penguin in the search box. Use the computer tool for UI interaction.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.Output)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.ResponseCreateParams;
import java.util.List;
import java.util.Map;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.6-sol")
        .input(
            "Open the Filters panel if needed, then search for penguin. Use the computer tool for UI interaction.")
        .putAdditionalBodyProperty("tools", JsonValue.from(List.of(Map.of("type", "computer"))))
        .build();

client.responses().create(params).output().forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.6-sol",
  input: "Open the Filters panel if needed, then search for penguin. Use the computer tool for UI interaction.",
  tools: [{ type: :computer }]
)

puts(response.output)

Execute as ações solicitadas

Uma computer_call contém um array actions ordenado. Por exemplo, esta chamada seleciona o campo de pesquisa e digita penguin:

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "output": [
    {
      "type": "computer_call",
      "call_id": "call_002",
      "actions": [
        { "type": "click", "button": "left", "x": 405, "y": 157 },
        { "type": "type", "text": "penguin" }
      ],
      "status": "completed"
    }
  ]
}

Seu manipulador de ações converte essas solicitações em entradas para o navegador ou sistema operacional. Execute as ações permitidas na ordem e, em seguida, capture a tela atualizada. O modelo pode solicitar click, double_click, drag, move, scroll, keypress, type, wait ou screenshot.

A primeira chamada pode conter apenas uma ação screenshot. Nesse caso, capture a tela atual e retorne-a sem alterar a interface. O valor status: "completed" em uma chamada significa que o modelo terminou de gerar essa chamada; seu aplicativo ainda precisa executá-la.

Use os exemplos de manipuladores de ações para mapeamentos de teclas, trajetórias de arraste e teclas modificadoras.

Retorne a captura de tela

Retorne um computer_call_output cujo call_id corresponda à chamada que você processou. Use previous_response_id para dar continuidade à conversa com o modelo:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import OpenAI from "openai";

const client = new OpenAI();

async function sendComputerScreenshot(response, callId, screenshotBase64) {
  const output = {
    type: "computer_screenshot",
    image_url: `data:image/png;base64,${screenshotBase64}`,
    detail: "original",
  };

  return await client.responses.create({
    model: "gpt-5.6-sol",
    tools: [{ type: "computer" }],
    previous_response_id: response.id,
    input: [
      {
        type: "computer_call_output",
        call_id: callId,
        output,
      },
    ],
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22from openai import OpenAI

client = OpenAI()


def send_computer_screenshot(response, call_id, screenshot_base64):
    return client.responses.create(
        model="gpt-5.6-sol",
        tools=[{"type": "computer"}],
        previous_response_id=response.id,
        input=[
            {
                "type": "computer_call_output",
                "call_id": call_id,
                "output": {
                    "type": "computer_screenshot",
                    "image_url": f"data:image/png;base64,{screenshot_base64}",
                    "detail": "original",
                },
            }
        ],
    )

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	response, err := sendComputerScreenshot(client, "resp_abc123", "call_abc123", "<base64 bytes here>")
	if err != nil {
		panic(err)
	}
	fmt.Println(response.Output)
}

func sendComputerScreenshot(client openai.Client, responseID string, callID string, screenshotBase64 string) (*responses.Response, error) {
	screenshot := responses.ResponseComputerToolCallOutputScreenshotParam{
		ImageURL: openai.String("data:image/png;base64," + screenshotBase64),
	}
	screenshot.SetExtraFields(map[string]any{"detail": "original"})
	return client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:              "gpt-5.6-sol",
		Tools:              []responses.ToolUnionParam{{OfComputer: &responses.ComputerToolParam{}}},
		PreviousResponseID: openai.String(responseID),
		Input: responses.ResponseNewParamsInputUnion{OfInputItemList: responses.ResponseInputParam{
			responses.ResponseInputItemParamOfComputerCallOutput(callID, screenshot),
		}},
	})
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.ResponseComputerToolCallOutputScreenshot;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import java.util.List;
import java.util.Map;

String responseId = "resp_abc123";

String computerCallId = "call_abc123";

String screenshotBase64 = "<base64 bytes here>";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-5.6-sol")
        .input(
            ResponseCreateParams.Input.ofResponse(
                List.of(
                    ResponseInputItem.ofComputerCallOutput(
                        ResponseInputItem.ComputerCallOutput.builder()
                            .callId(computerCallId)
                            .output(
                                ResponseComputerToolCallOutputScreenshot.builder()
                                    .imageUrl("data:image/png;base64," + screenshotBase64)
                                    .putAdditionalProperty("detail", JsonValue.from("original"))
                                    .build())
                            .build()))))
        .previousResponseId(responseId)
        .putAdditionalBodyProperty("tools", JsonValue.from(List.of(Map.of("type", "computer"))))
        .build();

client.responses().create(params).output().forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-5.6-sol",
  previous_response_id: "resp_abc123",
  input: [
    {
      type: :computer_call_output,
      call_id: "call_abc123",
      output: {
        type: :computer_screenshot,
        image_url: "data:image/png;base64,<base64 bytes here>",
        detail: :original
      }
    }
  ],
  tools: [{ type: :computer }]
)

puts(response.output)

As mesmas orientações sobre capturas de tela e estado se aplicam a este loop. Mantenha o ambiente disponível enquanto previous_response_id dá continuidade à conversa com o modelo.

Continue até que o modelo pare de retornar itens computer_call. Inspecione o restante da saída para identificar uma resposta, um pedido de ajuda ou outra chamada de ferramenta e verifique o resultado no aplicativo. Neste exemplo, o painel Filtros deve estar aberto e o campo de pesquisa deve conter penguin.

Consulte Repita o loop de Uso do computador para ver a estrutura básica do loop, incluindo as funções auxiliares necessárias para ações e capturas de tela.

Execute com segurança

O Uso do computador pode afetar contas e dados reais. Aplique estes controles no seu aplicativo e no ambiente de execução, assim como nas instruções do modelo:

• Restrinja o ambiente. Use um navegador isolado ou uma máquina virtual e uma lista de sites e ações permitidos. Limite o acesso ao que a tarefa exige.
• Trate o conteúdo da tela como não confiável. O texto de uma página, documento ou resultado de ferramenta não pode conceder permissão nem se sobrepor às instruções do usuário.
• Confirme ações de impacto. Mantenha os usuários no controle de compras, transmissão de dados, alterações destrutivas e outras ações difíceis de reverter. Digitar informações sensíveis em um formulário conta como transmissão.
• Limite e verifique a execução. Defina limites de etapas, tempo ou custo, permita o cancelamento e verifique o resultado real em vez de confiar apenas na resposta final do modelo.

Consulte as orientações sobre confirmação e consentimento para conhecer os requisitos específicos de aprovação, a transferência de controle para uma pessoa e exemplos de prompts.

Próximos passos

• Use as receitas de integração para configurar o ambiente, implementar manipuladores de ações, capturar telas e criar adaptadores para serviços de execução.
• Siga as instruções em Migração de computer-use-preview ao atualizar uma integração antiga.
• Explore o aplicativo de exemplo de CUA para conhecer fluxos de trabalho completos no navegador e no desktop.