PolyAI

Agent Development Kit (ADK)

A CLI for building, testing, and deploying PolyAI voice and chat agents.

New to PolyAI? Sign up at studio.poly.ai and start free.

Installation

Via UV:

uv tool install polyai-adk

Via Pip:

pip install polyai-adk

Voice calling (poly call) needs extra audio and WebRTC dependencies, which are left out of the default install to keep it small for CI. Install them with the call extra:

pip install "polyai-adk[call]"
uv tool install "polyai-adk[call]"

Then set up your account, API key, AI skills, and a project:

poly setup

Once set up, use the poly command to manage your projects:

poly setup      # Set up everything: account, API key, AI skills, and a project
poly apikey     # Get an API key for the PolyAI APIs / Dialog RSN (separate from ADK setup; pass --region for your cluster)
poly init       # Initialize a project
poly project    # Manage poly projects
poly pull       # Pull latest configuration
poly push       # Push local changes
poly status     # View project status
poly diff       # View local changes
poly branch     # Manage branches
poly format     # Format resources
poly validate   # Validate configuration
poly review     # Create a review gist
poly deployments  # Manage deployments
poly docs       # Output reference documentation

Usage

Install the ADK from PyPI:

pip install polyai-adk

Once installed, the poly CLI command becomes available.

poly init         # Initialize a project (interactive)
poly pull         # Pull latest configuration
poly push         # Push local changes
poly status       # View project status
poly diff         # View local changes
poly branch       # Manage branches
poly format       # Format resources
poly validate     # Validate configuration
poly review       # Create a review gist
poly deployments  # List deployment history

Run:

poly --help

to see all available commands.

Each command also supports --help for detailed syntax:

poly push --help

Commands

Run poly --help to see all available commands and options. Each command also supports --help for detailed syntax (e.g. poly push --help).

`poly init`

Initialize a new Agent Studio project locally. Runs interactively by default, prompting for region, account, and project. You can also pass these directly:

poly init
poly init --region us-1 --account_id 123 --project_id my_project
poly init --base-path /path/to/projects
poly init --format   # format resources after init

`poly pull`

Pull the latest project configuration from Agent Studio:

poly pull
poly pull --force     # overwrite all local changes
poly pull --format    # format resources after pulling

`poly push`

Push local changes to Agent Studio:

poly push
poly push --dry-run          # preview what would be pushed
poly push --skip-validation  # skip local validation before pushing
poly push --force            # overwrite remote changes
poly push --format           # format resources before pushing

`poly status`

View changed, new, and deleted files in your project:

poly status

`poly diff`

Show diffs between your local project and the remote version, or between two named versions:

poly diff                              # local vs remote (all changes)
poly diff --files file1.yaml           # specific files only
poly diff abc1234                      # version hash vs its predecessor
poly diff --before hash1 --after hash2 # compare two specific versions

`poly revert`

Revert local changes:

poly revert                        # revert all changes
poly revert file1.yaml file2.yaml  # revert specific files

`poly branch`

Manage branches (default branch is main):

poly branch list                       # active branches
poly branch list --archived            # soft-deleted branches
poly branch current
poly branch create my-feature
poly branch create my-hotfix --from my-feature  # branch from another branch instead of the current one
poly branch switch my-feature
poly branch switch my-feature --force  # discard uncommitted changes
poly branch rename my-feature-v2       # rename the current branch
poly branch merge 'Merge my-feature'   # merge into the parent branch
poly branch sync                       # pull the parent branch's changes in
poly branch history                    # merge history for the current branch
poly branch delete                     # soft-delete, restorable for 30 days
poly branch restore my-feature-id      # restore a soft-deleted branch

Projects using simplified deployments can also stage a branch:

poly branch tag                        # tag the current branch, deploying it to staging
poly branch untag                      # remove the tag

poly branch sync, tag, and untag are only available on projects with simplified deployments enabled; they exit with an error otherwise.

`poly format`

Format project resources (Python via ruff, YAML/JSON via in-process formatting). Use --check to only report files that would change; use --ty to also run type checking.

poly format                        # all resources
poly format --files file1.py       # specific files
poly format --check                # check only, no writes

`poly validate`

Validate project configuration locally:

poly validate

`poly review`

Create a GitHub gist for reviewing changes, similar to a pull request:

poly review create                                        # local vs remote
poly review create abc1234                                # version hash vs its predecessor
poly review create --before hash1 --after hash2           # compare two specific versions
poly review create --before main --after feature-branch   # compare branches
poly review list                                          # list existing review gists
poly review delete                                        # delete all review gists

`poly deployments`

List deployment history for the project:

poly deployments                          # last 10 sandbox deployments
poly deployments --env live               # live environment
poly deployments --limit 20 --offset 10   # pagination
poly deployments --hash abc1234           # start from a specific version
poly deployments --details                # full metadata per deployment

`poly chat`

Start an interactive chat session with your agent:

poly chat
poly chat --environment live
poly chat --channel webchat
poly chat --metadata   # show functions, flows, and state each turn

# Simulate one SIP header
poly chat --sip-header X-Customer-ID=12345
# Simulate multiple SIP headers
poly chat --sip-header X-Customer-ID=12345 --sip-header X-Language=en-GB

--sip-header NAME=VALUE is repeatable and simulates headers exposed to project functions through conv.sip_headers. It does not create a SIP call or reproduce carrier-level SIP behaviour.

`poly docs`

Output ADK documentation

poly docs
poly docs -all
poly docs {documentation (e.g topics)}
poly docs --output doc_file.md

Bugs & Feature Requests

Please report bugs or request features via the GitHub Issues page.

Contributing

See CONTRIBUTING.md for development setup, code style, and contribution guidelines.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Metadata

Release files for polyai-adk 0.67.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for polyai-adk 0.67.2
File	Size	Uploaded
polyai_adk-0.67.2.tar.gz	458.6 kB	Oct 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for polyai-adk 0.67.2
File	Interpreter	ABI	Platform	Reset
polyai_adk-0.67.2-py3-none-any.whl 568.2 kB Oct 7, 2026	Python 3	none	any	Details

Total release size: 1.0 MB

Release files / polyai_adk-0.67.2.tar.gz

Download URL	polyai_adk-0.67.2.tar.gz
Size	458.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`3b36996b558e7bc0679fdc4418a2f3205ccaaf9b6f8593afecd30fd66e2ed2e9`
BLAKE2b-256 checksum How to use checksums	`78ae7381bf0573448083f74622c5d1d44457af558756c5888362447c70a7a9e9`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/polyai/adk
Publishing commit: github.com/polyai/adk/tree/25b6858ae3c3177237f7d4d5034031be0e1eda07

Workflow

Publishing configuration: github.com/polyai/adk/blob/25b6858ae3c3177237f7d4d5034031be0e1eda07/.github/workflows/release.yaml
Publishing logs: github.com/polyai/adk/actions/runs/37624193444/attempts/1

Artifact

Subject: polyai_adk-0.67.2.tar.gz
SHA-256 checksum: 3b36996b558e7bc0679fdc4418a2f3205ccaaf9b6f8593afecd30fd66e2ed2e9 Verifying attestations

Release files / polyai_adk-0.67.2-py3-none-any.whl

Download URL	polyai_adk-0.67.2-py3-none-any.whl
Size	568.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`276536463afa6ca8014d2769be855d5476ced8f01e832a1e0e4f21ef60ef00d6`
BLAKE2b-256 checksum How to use checksums	`86a7a5dd0e69796d4491001fb79180c50b09b5d976ea1b358fc89f46e0c32cd9`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/polyai/adk
Publishing commit: github.com/polyai/adk/tree/25b6858ae3c3177237f7d4d5034031be0e1eda07

Workflow

Publishing configuration: github.com/polyai/adk/blob/25b6858ae3c3177237f7d4d5034031be0e1eda07/.github/workflows/release.yaml
Publishing logs: github.com/polyai/adk/actions/runs/37624193444/attempts/1

Artifact

Subject: polyai_adk-0.67.2-py3-none-any.whl
SHA-256 checksum: 276536463afa6ca8014d2769be855d5476ced8f01e832a1e0e4f21ef60ef00d6 Verifying attestations