Agent Development Kit (ADK)
A CLI and Python package for managing Agent Studio projects locally. It provides a Git-like workflow for synchronizing project configurations between your local filesystem and the Agent Studio platform.
Installation
Via Pip:
pip install polyai-adk
Via UV:
uv tool install polyai-adk
Once installed, use the poly command to manage your projects:
poly setup # Set up everything: account, API key, AI skills, and a project
poly apikey --region studio # Get an API key for the PolyAI APIs / Dialog RSN
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.
1 maintainer
Release files for polyai-adk 0.61.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| polyai_adk-0.61.3.tar.gz | 454.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| polyai_adk-0.61.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.0 MB
Release files / polyai_adk-0.61.3.tar.gz
| Download URL | polyai_adk-0.61.3.tar.gz |
|---|---|
| Size | 454.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
df7cac402968058060d76e8fd6cc6c233b0653994bb1ad779d4b20710de2dcb2
|
|
BLAKE2b-256 checksum How to use checksums |
d40bebbbc0b5dd09c5abfcbc11f260fd5e487344dfc19fd023cd1b2cbae7c891
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 25, 2026.
Transparency logRelease files / polyai_adk-0.61.3-py3-none-any.whl
| Download URL | polyai_adk-0.61.3-py3-none-any.whl |
|---|---|
| Size | 564.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ba20c44569bf538d3424721dccf7956d95f676491324c82d6ec454a1c6dfb419
|
|
BLAKE2b-256 checksum How to use checksums |
1ecf3049509107efe96e79ef19857b02f70bfc3b86cd1a03a279f83ef7645404
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 25, 2026.
Transparency log
