kernel-typescript-sdk

Kernel TypeScript SDK

このスキルを使用する場面

TypeScript から Kernel のブラウザーセッションを作成、自動化する場合、プロファイルを使用してブラウザーの状態を保持する場合、プロキシ経由でセッションをルーティングする場合、または自動化を Kernel アクションとしてパッケージ化する場合に、このスキルを使用してください。

単発の kernel ... コマンドには、代わりに kernel-cli スキルを使用してください。

インストールと初期化

npm install @onkernel/sdk
# Only CDP-based automation also needs a local Playwright client:
npm install playwright-core

import { Kernel } from "@onkernel/sdk";

const kernel = new Kernel(); // Reads KERNEL_API_KEY from the environment.

リクエストとレスポンスのフィールドには snake_case（timeout_seconds、session_id、cdp_ws_url）を使用します。SDK メソッドには JavaScript の命名規則（deleteByID、captureScreenshot）を使用します。

自動化方法の選択

ほとんどの自動化では、サーバーサイド Playwright と kernel.browsers.playwright.execute() の使用を推奨します。コードはブラウザーの隣で実行されるため、レイテンシーが低く、ローカルに Playwright をインストールする必要もありません。

ローカルライブラリから Playwright を直接操作する必要がある場合、または対話的にデバッグする場合は、CDP 接続を使用します。browser.cdp_ws_url で接続し、ブラウザーの既存のコンテキストを再利用してください。

サーバーサイド Playwright のライフサイクル

作成したセッションは必ず finally で削除してください。アイドルタイムアウトは安全策であり、通常のクリーンアップ方法ではありません。

import { Kernel } from "@onkernel/sdk";

const kernel = new Kernel();
const session = await kernel.browsers.create({
  stealth: true,
  timeout_seconds: 300,
});

try {
  const response = await kernel.browsers.playwright.execute(session.session_id, {
    code: `
      await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
      return { title: await page.title(), url: page.url() };
    `,
    timeout_sec: 60,
  });

  if (!response.success) {
    throw new Error(response.error ?? response.stderr ?? "Playwright execution failed");
  }

  console.log(response.result);
} finally {
  await kernel.browsers.deleteByID(session.session_id);
}

code 内で return を使用すると、response.result に値を設定できます。呼び出しごとに新しい実行コンテキストが使用されるため、依存する手順は1回の呼び出しにまとめるか、次の呼び出しに必要な状態を返してください。

CDP のライフサイクル

ローカルの CDP クライアントを閉じてから、接続や自動化に失敗した場合でも Kernel セッションを削除してください。

import { Kernel } from "@onkernel/sdk";
import { chromium } from "playwright-core";

const kernel = new Kernel();
const session = await kernel.browsers.create({ stealth: true, timeout_seconds: 300 });

try {
  const browser = await chromium.connectOverCDP(session.cdp_ws_url);
  try {
    const context = browser.contexts()[0];
    if (!context) throw new Error("Kernel browser has no default context");

    const page = context.pages()[0] ?? (await context.newPage());
    await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
    console.log(await page.title());
  } finally {
    await browser.close();
  }
} finally {
  await kernel.browsers.deleteByID(session.session_id);
}

browser.close() を Kernel リソースのクリーンアップとして扱わないでください。必ず deleteByID() を呼び出してください。

プロファイル

プロファイルは、アタッチする前に作成してください。セッション終了後も変更を保持する場合に限り、save_changes: true を設定してください。

const profile = await kernel.profiles.create({ name: "example-login" });
const session = await kernel.browsers.create({
  profile: { id: profile.id, save_changes: true },
  stealth: true,
});

try {
  // Authenticate or automate with playwright.execute or CDP.
} finally {
  await kernel.browsers.deleteByID(session.session_id);
}

長時間の作業では、プロファイル ID の使用を推奨します。ブラウザーから名前で参照されている間は、プロファイルの名前を変更しないでください。セッションの変更が保存されなくなる可能性があります。一時的なテストデータとして作成したプロファイルのみ、ブラウザーセッションを削除した後に削除してください。

await kernel.profiles.delete(profile.id);

プロキシと直接接続

既存のプロキシは、作成時に ID を指定してアタッチします。

const session = await kernel.browsers.create({
  stealth: true,
  proxy_id: process.env.KERNEL_PROXY_ID!,
});

接続先への到達性が重要な場合は、使用前に設定済みのプロキシから公開 HTTP(S) ターゲットへの接続を確認してください。

const checked = await kernel.proxies.check(process.env.KERNEL_PROXY_ID!, {
  url: "https://example.com",
});
if (checked.status === "unavailable") throw new Error("Proxy is unavailable");

実行中のステルスセッションで明示的なプロキシをクリアし、Kernel のデフォルトのステルスプロキシを無効にすると、直接接続できます。

await kernel.browsers.update(session.session_id, {
  proxy_id: "",
  disable_default_proxy: true,
});

デフォルトのステルスプロキシを再度有効にするには、disable_default_proxy: false を設定します。kernel.proxies.update(id, { name }) はプロキシの名前を変更するだけです。種類や設定を変更するには、プロキシを作り直してください。一時的なプロキシは、使用中のすべてのセッションを削除してから削除してください。

バイナリデータ

スクリーンショットやファイルのバイト列を playwright.execute から返さないでください。専用のレスポンスエンドポイントを使用してください。

const screenshot = await kernel.browsers.computer.captureScreenshot(session.session_id);
const screenshotBuffer = Buffer.from(await screenshot.arrayBuffer());

const file = await kernel.browsers.fs.readFile(session.session_id, {
  path: "/tmp/output.pdf",
});
const fileBuffer = Buffer.from(await file.arrayBuffer());

クリーンアップのルール

1. 作成したブラウザーセッションは、作成直後に必ず try/finally で囲んでください。
2. 成功時も失敗時も、kernel.browsers.deleteByID(session_id) でセッションを削除してください。
3. CDP を使用する場合は、セッションを削除する前にローカルクライアントを閉じてください。
4. 一時的なプロファイルとプロキシは、依存するセッションを削除してから削除してください。
5. 認証情報とプロキシのパスワードは環境変数に保存し、ソースコードやログに埋め込まないでください。

参考資料

• Kernel ドキュメント：https://www.kernel.sh/docs
• クイックスタートガイド：https://www.kernel.sh/docs/quickstart
• TypeScript 型定義：@onkernel/sdk に付属する宣言ファイルとホバードキュメントを使用してください
• その他の統合例：examples