OpenAI Responses API 入門 (11) - Computer use

「Responses API」の「Computer use」の使い方についてまとめました。

前回

1. Computer use

「Computer use」は、「CUA」(Computer-Using Agent)の実用的な応用であり、「GPT-4o」の視覚機能と高度な推論を組み合わせて、コンピューターインターフェースの操作やタスクの実行をシミュレートします。

2. Computer use のしくみ

「Computer use」は、連続ループで動作します。このツールは click(x, y) や type(text) のようなコンピュータ操作を送信し、ユーザーのコードがそれをコンピュータやブラウザ環境で実行します。その後、結果のスクリーンショットがモデルに返されます。

このしくみにより、ユーザーのコードは人間がコンピュータインターフェースを操作する動作をシミュレートし、モデルはスクリーンショットを分析して環境の状態を理解し、次のアクションを提案します。

このループを活用することで、クリック、タイピング、スクロールなどの操作を自動化できます。たとえば、航空券の予約、商品の検索、フォームの入力などのタスクを実行できます。

3. 環境の設定

このツールを統合する前に、スクリーンショットを取得し、推奨される操作を実行できる環境を準備する必要があります。安全性の観点から、サンドボックス環境の使用を推奨します。

3-1. ローカルブラウジング環境のセットアップ

最小限のセットアップで「Computer use」を試したい場合は、Playwright や Selenium などのブラウザ自動化フレームワークを使用できます。

ただし、ローカルでブラウザ自動化フレームワークを実行すると、セキュリティリスクが生じる可能性があります。これを軽減するために、以下の設定を推奨します。

対応するSDKをインストールすることで、好みのプログラミング言語でブラウザインスタンスを起動できます。

例えば、Playwright のブラウザインスタンスを起動する手順は、次のとおりです。

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(
        headless=False,
        chromium_sandbox=True,
        env={},
        args=[
            "--disable-extensions",
            "--disable-file-system"
        ]
    )
    page = browser.new_page()
    page.set_viewport_size({"width": 1024, "height": 768})
    page.goto("https://bing.com")

    page.wait_for_timeout(10000)

3-2. ローカル仮想マシン環境のセットアップ

Dockerのようなツールを使用して、ローカルで仮想マシンを構築・実行できます。その後、このローカルマシンに接続して「Computer use」アクションを実行できます。

(1) Dockerの起動
Dockerがインストールされていない場合は、公式サイトからインストールできます。インストール後、Dockerが正常に動作していることを確認してください。

(2) Dockerfileの作成
仮想マシンの構成を定義するために、Dockerfileを作成します。
以下は、VNCサーバーを備えたUbuntu仮想マシンを起動する例のDockerfileです。

FROM ubuntu:22.04
ENV DEBIAN_FRONTEND=noninteractive

# 1) Install Xfce, x11vnc, Xvfb, xdotool, etc., but remove any screen lockers or power managers
RUN apt-get update && apt-get install -y     xfce4     xfce4-goodies     x11vnc     xvfb     xdotool     imagemagick     x11-apps     sudo     software-properties-common     imagemagick  && apt-get remove -y light-locker xfce4-screensaver xfce4-power-manager || true  && apt-get clean && rm -rf /var/lib/apt/lists/*

# 2) Add the mozillateam PPA and install Firefox ESR
RUN add-apt-repository ppa:mozillateam/ppa  && apt-get update  && apt-get install -y --no-install-recommends firefox-esr  && update-alternatives --set x-www-browser /usr/bin/firefox-esr  && apt-get clean && rm -rf /var/lib/apt/lists/*

# 3) Create non-root user
RUN useradd -ms /bin/bash myuser     && echo "myuser ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
USER myuser
WORKDIR /home/myuser

# 4) Set x11vnc password ("secret")
RUN x11vnc -storepasswd secret /home/myuser/.vncpass

# 5) Expose port 5900 and run Xvfb, x11vnc, Xfce (no login manager)
EXPOSE 5900
CMD ["/bin/sh", "-c", "    Xvfb :99 -screen 0 1280x800x24 >/dev/null 2>&1 &     x11vnc -display :99 -forever -rfbauth /home/myuser/.vncpass -listen 0.0.0.0 -rfbport 5900 >/dev/null 2>&1 &     export DISPLAY=:99 &&     startxfce4 >/dev/null 2>&1 &     sleep 2 && echo 'Container running!' &&     tail -f /dev/null "]

(3) Docker イメージのビルド
Dockerfile があるディレクトリで、以下のコマンドを実行して Docker イメージをビルドします。

docker build -t cua-image .

(4) Docker コンテナをローカルで実行
以下のコマンドを実行して、Docker コンテナを起動します。

docker run --rm -it --name cua-image -p 5900:5900 -e DISPLAY=:99 cua-image

(5) コンテナ内でコマンドを実行
コンテナが起動したら、コマンドを実行できます。
例えば、次のステップで使用する補助関数を定義し、コンテナ内でコマンドを実行できます。

def docker_exec(cmd: str, container_name: str, decode=True) -> str:
    safe_cmd = cmd.replace('"', '\"')
    docker_cmd = f'docker exec {container_name} sh -c "{safe_cmd}"'
    output = subprocess.check_output(docker_cmd, shell=True)
    if decode:
        return output.decode("utf-8", errors="ignore")
    return output

class VM:
    def __init__(self, display, container_name):
        self.display = display
        self.container_name = container_name

vm = VM(display=":99", container_name="cua-image")

4. CUAループの統合

アプリケーションに「Computer use」を統合する手順は、次のとおりです。

4-1. モデルにリクエストを送信

「Computer use」ツール (computer_use_preview) を備えた 「computer-use-preview」モデルを使用して、レスポンスを作成するリクエストを送信します。このリクエストには、環境の詳細情報と初期入力プロンプトを含める必要があります。また、オプションとして環境の初期状態を示すスクリーンショットを含めることもできます。

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="computer-use-preview",
    tools=[{
        "type": "computer_use_preview",
        "display_width": 1024,
        "display_height": 768,
        "environment": "browser" # other possible values: "mac", "windows", "ubuntu"
    }],
    input=[
        {
            "role": "user",
            "content": "Check the latest OpenAI news on bing.com."
        }
        # Optional: include a screenshot of the initial state of the environment
        # {
        #     type: "input_image",
        #     image_url: f"data:image/png;base64,{screenshot_base64}"
        # }
    ],
    truncation="auto"
)

print(response.output)

4-2. モデルからの応答を受信

モデルは、会話の状態に応じて、computer_call アイテム、単なるテキスト、または他のTool Callingを含む出力を返します。computer_call アイテムの例としては、クリック、スクロール、キー押下、その他 API リファレンスで定義されたイベントなどがあります。

今回の例では、computer_call アイテムとして クリックアクション が含まれています。

"output": [
    {
        "type": "reasoning",
        "id": "rs_67cc...",
        "content": []
    },
    {
        "type": "computer_call",
        "id": "cu_67cc...",
        "call_id": "call_zw3...",
        "action": {
            "type": "click",
            "button": "left",
            "x": 156,
            "y": 50
        },
        "pending_safety_checks": [],
        "status": "completed"
    }
]

・Reasoningアイテム

モデルは一部のアクションに対して、レスポンス出力内に Reasoning アイテムを含めることがあります。この場合、次回 CUA モデルにリクエストを送信する際に、Reasoning アイテムを必ず含める必要があります。

・セーフティーチェック
モデルは pending_safety_check パラメータとともに セーフティチェック を返すことがあります。セーフティチェックの承認方法については、後ほど説明します。

4-3. 要求されたアクションを実行

対応するアクションをコンピュータまたはブラウザ上で実行します。
computer_call をコードを通じてどのようにアクションにマッピングするかは、使用する環境によって異なります。

最も一般的なコンピュータアクションの実装例は、次のとおりです。

def handle_model_action(page, action):
    """
    Given a computer action (e.g., click, double_click, scroll, etc.),
    execute the corresponding operation on the Playwright page.
    """
    action_type = action.type
    
    try:
        match action_type:

            case "click":
                x, y = action.x, action.y
                button = action.button
                print(f"Action: click at ({x}, {y}) with button '{button}'")
                # Not handling things like middle click, etc.
                if button != "left" and button != "right":
                    button = "left"
                page.mouse.click(x, y, button=button)

            case "scroll":
                x, y = action.x, action.y
                scroll_x, scroll_y = action.scroll_x, action.scroll_y
                print(f"Action: scroll at ({x}, {y}) with offsets (scroll_x={scroll_x}, scroll_y={scroll_y})")
                page.mouse.move(x, y)
                page.evaluate(f"window.scrollBy({scroll_x}, {scroll_y})")

            case "keypress":
                keys = action.keys
                for k in keys:
                    print(f"Action: keypress '{k}'")
                    # A simple mapping for common keys; expand as needed.
                    if k.lower() == "enter":
                        page.keyboard.press("Enter")
                    elif k.lower() == "space":
                        page.keyboard.press(" ")
                    else:
                        page.keyboard.press(k)
            
            case "type":
                text = action.text
                print(f"Action: type text: {text}")
                page.keyboard.type(text)
            
            case "wait":
                print(f"Action: wait")
                time.sleep(2)

            case "screenshot":
                # Nothing to do as screenshot is taken at each turn
                print(f"Action: screenshot")

            # Handle other actions here

            case _:
                print(f"Unrecognized action: {action}")

    except Exception as e:
        print(f"Error handling action {action}: {e}")

4-4. 更新された状態をキャプチャ

アクションを実行した後、環境の最新の状態をスクリーンショットとして取得します。スクリーンショットの取得方法は、使用する環境によって異なります。

def get_screenshot(page):
    """
    Take a full-page screenshot using Playwright and return the image bytes.
    """
    return page.screenshot()

4-5. 繰り返し

スクリーンショットを取得したら、それを computer_call_output としてモデルに送信し、次のアクションを取得できます。レスポンスに computer_call アイテムが含まれている限り、このプロセスを繰り返します。

import time
import base64
from openai import OpenAI
client = OpenAI()

def computer_use_loop(instance, response):
    """
    Run the loop that executes computer actions until no 'computer_call' is found.
    """
    while True:
        computer_calls = [item for item in response.output if item.type == "computer_call"]
        if not computer_calls:
            print("No computer call found. Output from model:")
            for item in response.output:
                print(item)
            break  # Exit when no computer calls are issued.

        # We expect at most one computer call per response.
        computer_call = computer_calls[0]
        last_call_id = computer_call.call_id
        action = computer_call.action

        # Execute the action (function defined in step 3)
        handle_model_action(instance, action)
        time.sleep(1)  # Allow time for changes to take effect.

        # Take a screenshot after the action (function defined in step 4)
        screenshot_bytes = get_screenshot(instance)
        screenshot_base64 = base64.b64encode(screenshot_bytes).decode("utf-8")

        # Send the screenshot back as a computer_call_output
        response = client.responses.create(
            model="computer-use-preview",
            previous_response_id=response.id,
            tools=[
                {
                    "type": "computer_use_preview",
                    "display_width": 1024,
                    "display_height": 768,
                    "environment": "browser"
                }
            ],
            input=[
                {
                    "call_id": last_call_id,
                    "type": "computer_call_output",
                    "output": {
                        "type": "input_image",
                        "image_url": f"data:image/png;base64,{screenshot_base64}"
                    }
                }
            ],
            truncation="auto"
        )

    return response

4-6. 会話履歴の取り扱い

previous_response_id パラメータを使用すると、現在のリクエストを前回のレスポンスと関連付けることができます。会話履歴を自分で管理したくない場合は、この方法の使用を推奨します。

このパラメータを使用しない場合は、前回のリクエストのレスポンス出力に含まれていたすべてのアイテム（Reasoning アイテムを含む場合はそれも）を、inputs 配列に含める必要があります。

4-7. セーフティチェックの承認

API には、プロンプトインジェクションやモデルの誤動作を防ぐためのセーフティチェックが実装されています。

上記のいずれか、または複数のチェックに該当した場合、次回の computer_call のレスポンスで pending_safety_checks パラメータ を伴うセーフティチェックが発生します。

"output": [
    {
        "type": "reasoning",
        "id": "rs_67cb...",
        "content": [
            {
                "type": "reasoning_summary",
                "text": "Exploring 'File' menu option."
            }
        ]
    },
    {
        "type": "computer_call",
        "id": "cu_67cb...",
        "call_id": "call_nEJ...",
        "action": {
            "type": "click",
            "button": "left",
            "x": 135,
            "y": 193
        },
        "pending_safety_checks": [
            {
                "id": "cu_sc_67cb...",
                "code": "malicious_instructions",
                "message": "We've detected instructions that may cause your application to perform malicious or unauthorized actions. Please acknowledge this warning if you'd like to proceed."
            }
        ],
        "status": "completed"
    }
]

次のリクエストを送信する際に、acknowledged_safety_checks としてセーフティチェックを承認しないと、処理を継続できません。pending_safety_checks が返された場合は、すべてのアクションをエンドユーザーに確認させ、モデルの動作と正確性を確認する必要があります。

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="computer-use-preview",
    previous_response_id="<previous_response_id>",
    tools=[{
        "type": "computer_use_preview",
        "display_width": 1024,
        "display_height": 768,
        "environment": "browser"
    }],
    input=[
        {
            "type": "computer_call_output",
            "call_id": "<call_id>",
            "acknowledged_safety_checks": [
                {
                    "id": "<safety_check_id>",
                    "code": "malicious_instructions",
                    "message": "We've detected instructions that may cause your application to perform malicious or unauthorized actions. Please acknowledge this warning if you'd like to proceed."
                }
            ],
            "output": {
                "type": "computer_screenshot",
                "image_url": "<image_url>"
            }
        }
    ],
    truncation="auto"
)

4-8. 最終コード

まとめると、最終的なコードには次の内容が含まれるようになります。

エンドツーエンドの統合例を確認するには、CUA サンプルアプリリポジトリを参照してください。

5. 制限事項

ブラウザベースのタスクには、computer-use-previewモデルの使用を推奨します。ただし、このモデルは、特にブラウザ以外の環境では使用頻度が低いため、意図せず誤った結果を出す可能性があります。

例えば、computer-use-previewのOSWorldでのパフォーマンスは現在38.1%であり、OS上のタスクを自動化するにはまだ十分に信頼できるレベルではありません。

また、以下のような制限事項にも注意が必要です。

6. リスクと安全性

「Computer use」には、標準的なAPI機能やチャットインターフェースとは異なる特有のリスクがあり、特にインターネットと連携する際に注意が必要です。

以下に、これらのリスクを軽減するためのベストプラクティスを示します。

6-1. 高リスクなタスクには人間の確認を挟む

高リスクなタスクや高精度が求められるタスクは避けてください。モデルは誤った判断をする可能性があり、特にブラウザ以外の環境ではミスが発生しやすくなります。重要な決定の前にユーザー確認を求めることを期待していますが、完全には信頼できません。モデルの動作が現実世界に影響を与える場合は、必ず人間が介入し確認してください。

6-2. プロンプトインジェクションに注意

プロンプトインジェクションとは、AIモデルが入力内の不正な指示に従ってしまう現象です。computer-use-previewモデルの場合、提供されたスクリーンショット内の悪意のあるウェブサイトやメールの指示に誤って従う可能性があります。このリスクを避けるため、信頼できる隔離環境（サンドボックス化されたブラウザやコンテナなど）でのみ使用してください。

6-3. ブロックリストと許可リストを活用

Webサイト、アクション、ユーザーのブロックリストまたは許可リストを設定を推奨します。
例：チケット予約ツールとして使用する場合、許可リストに特定の予約サイトのみを登録し、他のサイトへのアクセスを制限。

6-4. ユーザーIDの送信

OpenAIが不正行為を監視・検出できるよう、エンドユーザーのID（任意のパラメータ）を送信することを推奨します。

6-5. セーフティチェックの活用

以下のセーフティチェック機能を活用し、プロンプトインジェクションやモデルの誤作動を防ぎましょう。

pending_safety_checkを受け取った場合、監視を強化してください。具体的には、タスクの実行をユーザーに委ね、ユーザーが明示的に確認した後に進行するようにします。また、「監視モード」（Operatorのような監視モード）を導入し、ユーザーがエージェントの動作をリアルタイムで監視できるようにします。セーフティチェックが発動した場合は、人間が介入するのが基本ルールです。

6-6. 安全性向上のための追加推奨事項

可能であれば、computer_call_output の一部として current_url（現在のURL）を送信してください。これにより、セーフティチェックの精度を向上させることができます。

{
    "type": "computer_call_output",
    "call_id": "call_7OU...",
    "acknowledged_safety_checks": [],
    "output": {
        "type": "computer_screenshot",
        "image_url": "..."
    },
    "current_url": "https://openai.com"
}

6-7. 追加の安全対策

「Computer use」ループと並行してガードレールを実装する など、アプリケーションに最適な追加の安全対策を導入してください。

6-8. 使用ポリシーの遵守

OpenAIの使用ポリシーおよびビジネス利用規約を遵守する責任はユーザーにあります。これらの遵守を確実にするために、提供されている安全機能やツールを積極的に活用することを推奨します。

次回