Skip to main content

AYX Python SDK Overview

The AYX Python SDK is the back-end engine for building custom Alteryx Designer plugins in Python. Combine it with the AYX UI SDK, which provides the user interface, to create a complete plugin. This page covers the SDK architecture, the plugin lifecycle, the tool-type shapes, and the authoring workflow.

重要

In the SDK API, the component that you build is a plugin (PluginV2). In the Designer Tool Palette and in the CLI, it appears as a tool. The two terms mean the same thing, and this page uses "plugin".

Requirements and Prerequisites

To develop a plugin with the AYX Python SDK, you need these items:

Component

Requirement

Operating System

Windows 10, 64-bit. Designer and the AYX Plugin CLI run only on Windows.

Alteryx Designer

Designer version compatible with the SDK release you install. Check the Alteryx Python Compatibility table for the target release.

Python

3.13 on your development machine. Designer’s embedded Python is separate. It runs the packaged plugin at runtime. For the Python version that matches your Designer release, go to the Alteryx Python Compatibility table.

AYX Python SDK (ayx-python-sdk)

2.6.1. Install it with pip. It provides the runtime and the local test harness.

AYX Plugin CLI (ayx-plugin-cli)

1.4.0. Install it with pip next to the SDK. It provides the workspace, scaffolding, and packaging commands.

Node.js and npm

24 LTS. Required only when you generate a user interface. A backend-only plugin (--omit-ui) doesn’t need them.

Engine Compatibility

The AYX Python SDK requires that the AMP Engine is enabled.Alteryx AMP Engine

Installation

To install the AYX Python SDK, run pip install ayx-python-sdk.

Architecture

The AYX Python SDK is the runtime that your plugin code imports and runs against (ayx_python_sdk.core and ayx_python_sdk.providers.amp_provider). It does these things:

  • Defines the plugin lifecycle that your Python code implements (PluginV2).

  • Provides a provider object that your code uses to read configuration, write output, log messages, and get anchor and connection information at runtime.

  • Moves data between Designer and your plugin as Arrow tables (pyarrow.Table and RecordBatch).

  • Provides a local test harness that validates plugin logic without opening Designer.

The SDK works with a separate package, the AYX Plugin CLI (ayx-plugin-cli). The CLI scaffolds the workspace and plugin files, generates configuration and test files, and packages and installs the finished plugin in Designer. You use the two packages together. The SDK is the runtime, and the CLI is the authoring tool.

The optional user interface of a plugin is a React-based configuration panel. The CLI generates it into its own ui/ folder, and you build it with the AYX UI SDK. A plugin with no user-configurable settings can skip the user interface entirely with --omit-ui, and then it has no Node.js or npm dependency.

Mental Model

These ideas describe how the SDK works:

  • A workspace is the project folder that holds one or more plugins. It also holds the shared metadata (ayx_workspace.json) and the build files.

  • A plugin ("tool" in Designer's Tool Palette) is one Designer extension that lives in the workspace. The CLI generates it from a tool-type template.

  • The Python class of a plugin subclasses PluginV2 and receives a provider object in __init__. All input and output, configuration access, and logging go through that provider.

  • Designer delivers data to the plugin as Arrow tables or record batches, one stream for each input or output anchor. An anchor is a named connection point on the tool icon in Designer, for example, Input and Output. Multiple batches can arrive on each input connection, and the plugin writes batches to named output anchors.

Plugin Lifecycle

Every PluginV2 subclass implements four callbacks:

Callback

Called When

Notes

__init__(self, provider)

The plugin is constructed.

Store the provider, read configuration, and log the startup. It also runs in update-only mode.

on_incoming_connection_complete(self, anchor)

An input anchor finishes sending data, including an optional anchor that received nothing.

Not called in update-only mode.

on_record_batch(self, batch, anchor)

A batch of records arrives on an input anchor.

Not called in update-only mode. Not called at all for input-type plugins, because they have no inputs.

on_complete(self)

All other processing has finished.

Clean up here. Input-type plugins, and optional-input plugins with no incoming connection, generate and write their output here instead of in on_record_batch.

  • To write output, call provider.write_to_anchor("AnchorName", table).

  • To log, call provider.io.info(...), provider.io.warn(...), or provider.io.error(...).

  • To read the settings of the plugin, use provider.tool_config.

Tool-Type Shapes

The --tool-type option of create-ayx-plugin scaffolds the anchor layout of the plugin. The SDK includes a worked example for each shape in AyxPythonSdk/ayx_python_sdk/examples/:

  • AyxSdkPassThrough: one input and one output.

  • AyxSdkInput: no input anchor. It generates its output in on_complete.

  • AyxSdkOutput: consumes input and produces no downstream rows.

  • AyxSdkMultipleInputAnchors and AyxSdkMultipleOutputAnchors: route or combine data across more than one named anchor.

  • AyxSdkMultiConnectionsMultiOutputAnchor: multiple connections feed a single input anchor.

  • AyxSdkOptionalInputAnchor: handles both the connected case and the unconnected case.

Start from the example that is closest to the data flow of your plugin, not from a blank file..

Authoring Workflow

Building a plugin follows the same sequence for every tool-type shape:

  1. Create a workspace with ayx_plugin_cli sdk-workspace-init.

  2. Create a plugin in the workspace with ayx_plugin_cli create-ayx-plugin --tool-name <Name> --tool-type <type>. Add --omit-ui for a backend-only plugin.

  3. Implement the transformation in the generated backend/ayx_plugins/<tool>.py module.

  4. Generate and edit a local test with ayx_plugin_cli generate-tests --tool-name <Name>. Run it with ayx_plugin_cli test or pytest backend. The CLI command doesn’t return the failing exit status of pytest, so use pytest backend in scripts and CI.

  5. Package the plugin with ayx_plugin_cli create-yxi. To build and install in one step, use ayx_plugin_cli designer-install --install-type user.

  6. Restart Designer, enable AMP, and test the plugin in a workflow.

For a complete example, go to the Platform SDK Quickstart Guide. It walks through this sequence with a plugin that converts a text column to uppercase. It includes the generated files, the full plugin code, a working test, and troubleshooting for each step.