Back to Details

kernel-python-sdk

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

When to Use This Skill

何时使用该技能

Use the Kernel Python SDK when you need to:
  • Build browser automation scripts - Create Python 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 Python SDK：
  • 构建浏览器自动化脚本 - 创建控制远程浏览器的Python程序
  • 执行服务器端自动化 - 在浏览器虚拟机中直接运行Playwright代码，无需本地依赖
  • 以编程方式管理浏览器会话 - 通过代码创建、配置和控制浏览器
  • 构建可扩展的爬取/测试工具 - 使用浏览器池和配置文件实现高容量自动化
  • 将自动化部署为动作 - 将脚本打包为Kernel动作，通过API调用
不适用场景：
  • 对于CLI命令（如
    kernel browsers create
    ），请改用
    kernel-cli
    技能
  • 对于快速一次性任务，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.browser_pools
    - Pre-warmed browser pool management
  • kernel.profiles
    - Persistent browser profiles (auth state)
  • kernel.auth.connections
    - Managed auth (create, login, submit, follow, retrieve, delete)
  • kernel.credential_providers
    - 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.browser_pools
    - 预启动浏览器池管理
  • kernel.profiles
    - 持久化浏览器配置文件（认证状态）
  • kernel.auth.connections
    - 托管认证（创建、登录、提交、跟随、检索、删除）
  • kernel.credential_providers
    - 外部凭证提供商（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(session_id, code="...")
  • session_id
    must be passed as a positional argument (first parameter), not as 
    id=
    keyword
  • 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 to browser via CDP WebSocket URL
  • Code runs locally, browser runs remotely; requires local Playwright installation
  • Best for: Complex debugging, specific local development needs
1. 服务器端执行（推荐）
  • 使用
    kernel.browsers.playwright.execute(session_id, code="...")
    在浏览器虚拟机中直接执行Playwright代码
  • session_id
    必须作为位置参数（第一个参数）传递，不能使用
    id=
    关键字参数
  • 通过
    response.result
    访问响应结果 - 必须在代码中使用
    return
    才能获取返回数据
  • 最适合：大多数使用场景、生产环境自动化、并行执行、动作部署
2. CDP连接（客户端）
  • 通过CDP WebSocket URL将Playwright连接到浏览器
  • 代码在本地运行，浏览器在远程运行；需要本地安装Playwright
  • 最适合：复杂调试、特定本地开发需求

Patterns Reference

模式参考

Import Patterns
  • Standard: 
    from kernel import Kernel
  • For actions: 
    import kernel
    and 
    from kernel import Kernel
  • For typed payloads: 
    from typing import TypedDict
  • For CDP: 
    from playwright.async_api import async_playwright
SDK Initialization
  • client = Kernel()
    reads 
    KERNEL_API_KEY
    from environment automatically
Action Handler Pattern
python
from typing import TypedDict
from kernel import Kernel

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

class TaskInput(TypedDict):
    task: str

@app.action("action-name")
async def my_action(ctx: kernel.KernelContext, input_data: TaskInput):
    # Access input: input_data["task"] or input_data.get("task")
    ...
CDP Connection Pattern (Client-side)
python
async with async_playwright() as playwright:
    browser = await playwright.chromium.connect_over_cdp(kernel_browser.cdp_ws_url)
    context = browser.contexts[0] if browser.contexts else await browser.new_context()
    page = context.pages[0] if context.pages else await context.new_page()
Binary Data Handling
Binary data (screenshots, PDFs) returns as Node.js Buffer: 
{'data': [byte_array], 'type': 'Buffer'}
python
undefined
导入模式
  • 标准方式：
    from kernel import Kernel
  • 用于动作：
    import kernel
    和 
    from kernel import Kernel
  • 用于类型化负载：
    from typing import TypedDict
  • 用于CDP：
    from playwright.async_api import async_playwright
SDK初始化
  • client = Kernel()
    会自动从环境变量中读取
    KERNEL_API_KEY
动作处理器模式
python
from typing import TypedDict
from kernel import Kernel

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

class TaskInput(TypedDict):
    task: str

@app.action("action-name")
async def my_action(ctx: kernel.KernelContext, input_data: TaskInput):
    # 访问输入：input_data["task"] 或 input_data.get("task")
    ...
CDP连接模式（客户端）
python
async with async_playwright() as playwright:
    browser = await playwright.chromium.connect_over_cdp(kernel_browser.cdp_ws_url)
    context = browser.contexts[0] if browser.contexts else await browser.new_context()
    page = context.pages[0] if context.pages else await context.new_page()
二进制数据处理
二进制数据（截图、PDF）会以Node.js Buffer格式返回：
{'data': [byte_array], 'type': 'Buffer'}
python
undefined

Follow canonical pattern above, then:

遵循上述标准模式，然后：

if response.success and response.result: data = bytes(response.result['data']) with open("output.png", "wb") as f: f.write(data)

**Installation**
- `uv pip install kernel` or `pip install kernel`
- For CDP: `uv pip install playwright`
if response.success and response.result: data = bytes(response.result['data']) with open("output.png", "wb") as f: f.write(data)

**安装步骤**
- `uv pip install kernel` 或 `pip install kernel`
- 若使用CDP：`uv pip install playwright`

References

参考资料