Python Script Action

python_script_action lets you run arbitrary Python code against the live Playwright page object—covering anything that standard interaction actions cannot express.

Overview

Use when: Built-in actions are insufficient (complex DOM manipulation, custom scrolling, dispatching browser events, reading element properties).
Execution: The runner execs your script, finds an async function named code_fn, and calls it with the current Playwright page.
No output: This action does not return or store data. To extract data with custom code, use extraction_action.python_script.

Properties

Property	Type	Description
`execution_code`	`str`	Python source that defines an async `code_fn(page)`

Script Contract

Your script must define an async function named code_fn that accepts a single page argument (a Playwright Page):

async def code_fn(page):
    # interact with the page here

The function is called as await code_fn(page). Any return value is ignored.

JSON Example

{
  "type": "action_node",
  "python_script_action": {
    "execution_code": "async def code_fn(page):\n    await page.evaluate(\"window.scrollTo(0, document.body.scrollHeight)\")"
  }
}

Common Patterns

Scroll to the bottom of the page

async def code_fn(page):
    await page.evaluate("window.scrollTo(0, document.body.scrollHeight)")

Wait for a custom JavaScript condition

async def code_fn(page):
    await page.wait_for_function("() => document.readyState === 'complete'")

Dispatch a custom browser event

async def code_fn(page):
    await page.evaluate("""
        document.querySelector('#upload-input').dispatchEvent(
            new Event('change', { bubbles: true })
        )
    """)

Interact with a shadow DOM element

async def code_fn(page):
    await page.evaluate("""
        document.querySelector('my-component').shadowRoot
            .querySelector('button.confirm')
            .click()
    """)

execution_code is evaluated with exec(). Only run scripts from trusted sources.

Python Script Extraction

To extract data from the page using custom code, use python_script inside an extraction_action instead. The contract is different: the function receives (axtree, browser) and must return a dict containing the extracted values.

{
  "type": "action_node",
  "extraction_action": {
    "python_script": {
      "script": "async def code_fn(axtree, browser):\n    page = await browser.get_current_page()\n    text = await page.locator('.order-id').inner_text()\n    return {\"order_id\": text.strip()}",
      "output_variable_names": ["order_id"]
    }
  }
}

Properties

Property	Type	Default	Description
`script`	`str`	Required	Python source defining `async def code_fn(axtree, browser)`
`extraction_format`	`dict \| None`	`None`	Expected output structure (required when `output_variable_names` is set)
`output_variable_names`	`list[str] \| None`	`None`	Promote returned dict keys to `generated_variables`

Script Contract

async def code_fn(axtree, browser):
    # axtree: string representation of the page accessibility tree
    # browser: the Browser instance (use browser.get_current_page() for the Playwright page)
    return {"key": "value"}  # must return a dict

The returned dict is stored as OutputData and, if output_variable_names is set, the specified keys are promoted to generated_variables for use in later nodes.

All keys in output_variable_names must exist in extraction_format, or schema validation will fail.

Action vs Extraction — Which to Use

Scenario	Use
Scroll, dispatch events, manipulate DOM	`python_script_action`
Extract and store data from the page	`extraction_action.python_script`
Simple text / table extraction	`extraction_action.llm`

Quickstart

Building Automations

Action Types

Inference

Advanced

FAQs

Overview

Properties

Script Contract

JSON Example

Common Patterns

Scroll to the bottom of the page

Wait for a custom JavaScript condition

Dispatch a custom browser event

Interact with a shadow DOM element

Python Script Extraction

Properties

Script Contract

Action vs Extraction — Which to Use

​Overview

​Properties

​Script Contract

​JSON Example

​Common Patterns

​Scroll to the bottom of the page

​Wait for a custom JavaScript condition

​Dispatch a custom browser event

​Interact with a shadow DOM element

​Python Script Extraction

​Properties

​Script Contract

​Action vs Extraction — Which to Use

Overview

Properties

Script Contract

JSON Example

Common Patterns

Scroll to the bottom of the page

Wait for a custom JavaScript condition

Dispatch a custom browser event

Interact with a shadow DOM element

Python Script Extraction

Properties

Script Contract

Action vs Extraction — Which to Use