kernel-python-sdk

このスキルを使う場面

Kernel のブラウザーセッションを作成、制御する Python コードを書くときに、このスキルを使用します。次の用途に適しています。

• ブラウザー VM でのサーバーサイド Playwright の実行
• CDP 経由のクライアントサイド Playwright
• 永続プロファイルと明示的なプロキシルーティング
• ブラウザープールまたはデプロイ済み Python アクション

シェルコマンドや簡単な単発セッションには、kernel-cli スキルを使用します。

セットアップ

uv pip install -U kernel
# Add this only for client-side CDP:
uv pip install playwright

環境に KERNEL_API_KEY を設定し、ソースには記述しないでください。Kernel() と AsyncKernel() は自動的に読み込みます。非同期クライアントを一貫して使用し、非同期アクションから同期 SDK メソッドを呼び出さないでください。

自動化の方法を選ぶ

サーバーサイド Playwright（デフォルト）

Chrome と同じ場所で JavaScript／TypeScript を実行します。これにより、ローカルの CDP との往復を避けられ、ローカルの Playwright も必要ありません。

from kernel import Kernel

with Kernel() as client:
    browser = client.browsers.create(stealth=True, timeout_seconds=300)
    try:
        response = client.browsers.playwright.execute(
            browser.session_id,
            code="""
await page.goto("https://example.com");
return { title: await page.title(), url: page.url() };
""",
            timeout_sec=60,
        )
        if not response.success:
            raise RuntimeError(response.error or response.stderr or "Playwright execution failed")
        print(response.result)
    finally:
        client.browsers.delete_by_id(browser.session_id)

セッション ID を最初の位置引数として渡します。コードでは page、context、browser を使用できます。return を使わないと、response.result は空になります。timeout_sec はリモートでのコード実行時間を制限し、SDK の timeout= オプションは HTTP リクエストを制御します。

CDP 経由のクライアントサイド Playwright

ローカルの Playwright ツールや対話的なデバッグが必要な場合は、CDP を使用します。

import asyncio

from kernel import AsyncKernel
from playwright.async_api import async_playwright


async def main() -> None:
    async with AsyncKernel() as client:
        kernel_browser = await client.browsers.create(
            stealth=True,
            timeout_seconds=300,
        )
        try:
            async with async_playwright() as playwright:
                remote = await playwright.chromium.connect_over_cdp(
                    kernel_browser.cdp_ws_url
                )
                context = remote.contexts[0]
                page = context.pages[0] if context.pages else await context.new_page()
                await page.goto("https://example.com")
                print(await page.title())
        finally:
            await client.browsers.delete_by_id(kernel_browser.session_id)


asyncio.run(main())

ページから Kernel セッションの読み込み済みプロファイル状態を参照できるよう、既存のデフォルトコンテキストを再利用してください。新しいシークレットコンテキストでは、その状態は共有されません。SDK クライアントのコンテキストを閉じると HTTP 接続は閉じますが、リモートブラウザーの削除の代わりにはなりません。

ブラウザーのライフサイクルとクリーンアップ

• 作成または取得したすべてのセッションは、作成直後に try/finally で囲んでください。
• 通常のセッションは client.browsers.delete_by_id(session_id) で削除します。AsyncKernel では await を使用してください。
• プールから取得したセッションは削除せず、ブラウザープールのリリース API を使って解放してください。
• クリーンアップを実装していても、ブラウザーの非アクティブタイムアウトは有限値に設定してください。アクティビティによってタイムアウトが延長されることがあるため、明示的なクリーンアップの代わりにはなりません。
• 使い捨てのプロファイルとプロキシは、それらを使用するすべてのセッションが終了してから削除してください。意図的に永続化するプロファイルは残してください。

プロファイル

プロファイルをアタッチする前に作成してください。Cookie とローカル状態をプロファイルに保存する必要がある場合は、save_changes=True を設定します。

profile = client.profiles.create(name="checkout-login")
browser = client.browsers.create(
    profile={"id": profile.id, "save_changes": True},
    stealth=True,
)
try:
    # Automate with server-side Playwright or CDP.
    ...
finally:
    client.browsers.delete_by_id(browser.session_id)

ブラウザーを削除するとセッションが終了し、プロファイルの変更を確定できるようになります。先にプロファイルを削除しないでください。{"id": ...} または {"name": ...} のいずれか一方を使い、両方は使わないでください。

Python SDK では、どちらかのアーカイブ形式を指定でき、プロファイル名を SDK 上で変更できます。

archive = client.profiles.download(profile.id, format="tar")
archive.write_to_file("profile.tar")
client.profiles.update(profile.id, name="checkout-login-v2")

SDK は tar.zst と tar のどちらの場合もアーカイブを書き出しますが、内容を展開することはありません。アーカイブをディレクトリに展開する必要がある場合は、kernel profiles download <id-or-name> --to ./profile を使用します。

プロキシとデフォルトのステルスプロキシ

作成時に proxy_id を指定して、明示的なプロキシをアタッチします。

proxy = client.proxies.create(
    type="datacenter",
    config={"country": "US"},
    name="automation-us",
)
try:
    client.proxies.check(proxy.id, url="https://example.com")
    browser = client.browsers.create(stealth=True, proxy_id=proxy.id)
    try:
        ...
    finally:
        client.browsers.delete_by_id(browser.session_id)
finally:
    client.proxies.delete(proxy.id)  # Only if this proxy was created for this run.

宛先を指定したプロキシチェックでは、公開 HTTP／HTTPS URL の有効性を確認します。住宅用およびモバイル用プロキシでは、後続のブラウザーが同じ出口ノードを使うことまでは保証されません。カスタム URL を指定した場合、一般的なプロキシの健全性ステータスも更新されません。

実行中のブラウザーのプロキシルーティングは変更できます。

client.browsers.update(browser.session_id, proxy_id=another_proxy_id)
client.browsers.update(browser.session_id, proxy_id="")  # Remove explicit proxy.

明示的なプロキシがアタッチされていない場合、ステルスブラウザーでは Kernel のデフォルトのステルスプロキシが使用されることがあります。これは個別に制御できます。

client.browsers.update(browser.session_id, disable_default_proxy=True)   # Direct connection
client.browsers.update(browser.session_id, disable_default_proxy=False)  # Re-enable default

disable_default_proxy は更新パラメーターであり、ブラウザー作成用のパラメーターではありません。現在の SDK ではプロキシ名の変更はできません。kernel proxies update <id> --name <new-name> を使用してください。名前以外を変更するには、プロキシを作り直してください。

デプロイ済みアクションのパターン

from typing import TypedDict

import kernel

app = kernel.App("app-name")


class TaskInput(TypedDict):
    task: str


@app.action("action-name")
async def run(ctx: kernel.KernelContext, payload: TaskInput):
    async with kernel.AsyncKernel() as client:
        browser = await client.browsers.create(
            invocation_id=ctx.invocation_id,
            timeout_seconds=300,
        )
        try:
            response = await client.browsers.playwright.execute(
                browser.session_id,
                code="return await page.title();",
            )
            if not response.success:
                raise RuntimeError(response.error or response.stderr or "Playwright execution failed")
            return response.result
        finally:
            await client.browsers.delete_by_id(browser.session_id)

バイナリーの結果

サーバーサイドのスクリーンショットと PDF は、Node.js の Buffer 形式の結果を返すことがあります。

response = client.browsers.playwright.execute(
    browser.session_id,
    code="return await page.screenshot({ fullPage: true });",
)
if response.success and response.result:
    with open("output.png", "wb") as file:
        file.write(bytes(response.result["data"]))

参考資料

• Kernel のドキュメント
• Python SDK API リファレンス
• Kernel クイックスタート
• その他の例