kernel-typescript-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Use This Skill

何时使用该Skill

Use the Kernel TypeScript SDK when you need to:

Build browser automation scripts - Create TypeScript programs that control remote browsers
Execute server-side automation - Run Playwright code directly in the browser VM without local dependencies
Manage browser sessions programmatically - Create, configure, and control browsers from code
Build scalable scraping/testing tools - Use browser pools and profiles for high-volume automation
Deploy automation as actions - Package scripts as Kernel actions for invocation via API

When NOT to use:

For CLI commands (e.g.,
```
kernel browsers create
```
), use the
```
kernel-cli
```
skill instead
For quick one-off tasks, the CLI may be simpler than writing code

当你需要以下功能时，使用Kernel TypeScript SDK：

构建浏览器自动化脚本 - 创建控制远程浏览器的TypeScript程序
执行服务端自动化 - 在浏览器虚拟机中直接运行Playwright代码，无需本地依赖
以编程方式管理浏览器会话 - 通过代码创建、配置和控制浏览器
构建可扩展的爬取/测试工具 - 利用浏览器池和配置文件实现高容量自动化
将自动化部署为动作 - 将脚本打包为Kernel动作，通过API调用

不适合使用的场景：

若需使用CLI命令（如
```
kernel browsers create
```
），请改用
```
kernel-cli
```
skill
对于快速一次性任务，CLI可能比编写代码更简单

Core Concepts

核心概念

SDK Architecture

SDK架构

The SDK is organized into resource-based modules:

```
kernel.browsers
```
- Browser session management (create, list, delete)
```
kernel.browsers.playwright
```
- Server-side Playwright execution
```
kernel.browsers.computer
```
- OS-level controls (mouse, keyboard, screenshots)
```
kernel.browserPools
```
- Pre-warmed browser pool management
```
kernel.profiles
```
- Persistent browser profiles (auth state)
```
kernel.auth.connections
```
- Managed auth (create, login, submit, follow, retrieve, delete)
```
kernel.credentialProviders
```
- External credential providers (1Password)
```
kernel.proxies
```
- Proxy configuration
```
kernel.extensions
```
- Chrome extension management
```
kernel.deployments
```
- App deployment
```
kernel.invocations
```
- Action invocation

SDK按资源模块组织：

```
kernel.browsers
```
- 浏览器会话管理（创建、列出、删除）
```
kernel.browsers.playwright
```
- 服务端Playwright执行
```
kernel.browsers.computer
```
- 系统级控制（鼠标、键盘、截图）
```
kernel.browserPools
```
- 预启动浏览器池管理
```
kernel.profiles
```
- 持久化浏览器配置文件（认证状态）
```
kernel.auth.connections
```
- 托管式认证（创建、登录、提交、跟随、检索、删除）
```
kernel.credentialProviders
```
- 外部凭证提供商（1Password）
```
kernel.proxies
```
- 代理配置
```
kernel.extensions
```
- Chrome扩展管理
```
kernel.deployments
```
- 应用部署
```
kernel.invocations
```
- 动作调用

Two Automation Approaches

两种自动化方式

1. Server-side Execution (RECOMMENDED)

Execute Playwright code directly in browser VM using
```
kernel.browsers.playwright.execute()
```
Response accessed via
```
response.result
```
- MUST use
return
in code to get data back
Best for: Most use cases, production automation, parallel execution, actions

2. CDP Connection (Client-side)

Connect Playwright/Puppeteer to browser via CDP WebSocket URL (
```
browser.cdp_ws_url
```
)
Code runs locally, browser runs remotely; requires local Playwright installation
Best for: Complex debugging, specific local development needs

1. 服务端执行（推荐）

使用
```
kernel.browsers.playwright.execute()
```
在浏览器虚拟机中直接运行Playwright代码
通过
```
response.result
```
获取响应 - 必须在代码中使用
return
才能返回数据
最适合：大多数使用场景、生产环境自动化、并行执行、动作部署

2. CDP连接（客户端）

通过CDP WebSocket地址（
```
browser.cdp_ws_url
```
）将Playwright/Puppeteer连接到浏览器
代码在本地运行，浏览器在远程运行；需要本地安装Playwright
最适合：复杂调试、特定本地开发需求

Patterns Reference

模式参考

SDK Initialization

typescript

import { Kernel } from "@onkernel/sdk";
const kernel = new Kernel();  // Reads KERNEL_API_KEY from environment

Attribute Access: Use

snake_case

(e.g.,

browser.session_id

browser.cdp_ws_url

)

Binary Data Handling

Binary data does not serialize through

playwright.execute

(returns

undefined

). Use dedicated APIs:

typescript

// For screenshots:
const response = await kernel.browsers.computer.captureScreenshot(browser.session_id);
// For files:
const response = await kernel.browsers.filesystem.readFile(browser.session_id, { path: '/path/to/file' });

// Convert to buffer:
const blob = await response.blob();
const buffer = Buffer.from(await blob.arrayBuffer());

Note: This differs from the Python SDK where binary data CAN be returned via
playwright.execute
as a Buffer object. In TypeScript, always use dedicated APIs.

SDK初始化

typescript

import { Kernel } from "@onkernel/sdk";
const kernel = new Kernel();  // Reads KERNEL_API_KEY from environment

属性访问：使用

snake_case

格式（如

browser.session_id

、

browser.cdp_ws_url

）

二进制数据处理

二进制数据无法通过

playwright.execute

序列化（返回

undefined

）。请使用专用API：

typescript

// For screenshots:
const response = await kernel.browsers.computer.captureScreenshot(browser.session_id);
// For files:
const response = await kernel.browsers.filesystem.readFile(browser.session_id, { path: '/path/to/file' });

// Convert to buffer:
const blob = await response.blob();
const buffer = Buffer.from(await blob.arrayBuffer());

注意：这与Python SDK不同，在Python SDK中可以通过
playwright.execute
返回Buffer对象来处理二进制数据。在TypeScript中，请始终使用专用API。

References

参考资料

Kernel Documentation: https://www.kernel.sh/docs
Quickstart Guide: https://www.kernel.sh/docs/quickstart
Templates: https://www.kernel.sh/docs/reference/cli/create#available-templates
TypeScript Types: Available in
```
@onkernel/sdk
```
package
Examples: examples

Kernel文档：https://www.kernel.sh/docs
快速入门指南：https://www.kernel.sh/docs/quickstart
模板：https://www.kernel.sh/docs/reference/cli/create#available-templates
TypeScript类型定义：包含在
```
@onkernel/sdk
```
包中
示例：examples