polyai-adk 0.16.0

Agent Development Kit (ADK) — a CLI for managing Agent Studio projects locally

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.

Documentation

Early Access

⚠️ The PolyAI ADK is currently in Early Access.

Changes may be pushed frequently while the platform evolves. If you encounter issues, please ensure you are running the latest version of the ADK before reporting them.

Request access to the PolyAI ADK

Once approved, the PolyAI team will provide the credentials required to use the ADK.

Prerequisites

Before using the ADK you must:

• have access to a PolyAI Agent Studio workspace
• obtain an ADK API key from the PolyAI team

Access to both is granted through the Early Access Program.

Store your API key as an environment variable named: POLY_ADK_KEY

For example:

export POLY_ADK_KEY=<your-key>

Installation

pip install polyai-adk

Once installed, use the poly command to manage your projects:

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
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
poly branch current
poly branch create my-feature
poly branch switch my-feature
poly branch switch my-feature --force  # discard uncommitted changes

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

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.