polyai-adk 0.1.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.

Prerequisites

You must have access to a workspace in PolyAI Agent Studio before using this tool. Access and an API key are provided by your PolyAI contact. To request access to the PolyAI platform, reach out to [e-mail].

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

Usage

A whitelisted API key is needed to run any of the poly commands.

1. Create an API key at https://studio.[us/uk/eu].poly.ai//data-access
2. Contact an engineer from the developer platform team team to whitelist your API key on Kong
3. Add the key to your env variable (typically ~/.zshrc or ~/.bashrc), and name it POLY_ADK_KEY

Once you do that, you'll be able to access agents under the for the namespace in which the API key is generated.

We are in the process of automating the whitelisting of the API key, and limiting the external ADK to just the production namespace.

Usage

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:

poly diff              # all changes
poly diff file1.yaml   # specific files

poly revert

Revert local changes:

poly revert --all                  # revert everything
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 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                                      # local vs remote
poly review --before main --after feature-branch  # compare branches
poly review --delete                              # delete all review gists

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

Development Setup

Prerequisites

• Python 3.14 or higher
• uv (brew install uv)

Getting Started

git clone https://github.com/PolyAI-LDN/local_agent_studio.git
cd local_agent_studio
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
pre-commit install

Running Tests

pytest

Test files are located in src/poly/tests/.

Project Structure

• src/poly/cli.py - CLI interface
• src/poly/project.py - Core project management
• src/poly/resources/ - Resource type implementations
• src/poly/handlers/ - API handler implementations
• src/poly/tests/ - Test suite
• src/poly/types/ - Python type definitions for the Agent Studio runtime

Bugs & Feature Requests

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

Contributing

Contributions are welcome! The project uses ruff for linting/formatting (enforced via pre-commit hooks) and pytest for testing. Please ensure all tests pass before submitting a pull request.

We recommend using Claude Code for development. The repo includes a .claude/ directory with project-specific instructions and permissions pre-configured.

Releases

This project uses python-semantic-release to automate versioning and publishing. Version bumps are determined from conventional commit messages:

Commit prefix	Version bump	Example
fix:	Patch (2.0.4 → 2.0.5)	fix: handle missing config file
feat:	Minor (2.0.4 → 2.1.0)	feat: add poly export command
feat!: / BREAKING CHANGE:	Major (2.0.4 → 3.0.0)	feat!: redesign resource schema
chore:, docs:, ci:	No release	docs: update README

When a commit is merged to main, the release workflow automatically:

1. Determines the next version from commit history
2. Updates the version in pyproject.toml
3. Creates a git tag and GitHub Release

License

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