adk

 # Agent Development Kit (ADK) [](https://pypi.org/project/polyai-adk/) [](https://www.python.org/downloads/) [](LICENSE) [](https://github.com/astral-sh/ruff) [](https://claude.ai/download) A CLI for building, testing, and deploying PolyAI voice and chat agents. New to PolyAI? Sign up at [studio.poly.ai](https://studio.poly.ai) and start free. **[Documentation](https://polyai.github.io/adk/)** ## Installation Via [UV](https://docs.astral.sh/uv/): ```bash uv tool install polyai-adk ``` Via Pip: ```bash 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: ```bash pip install "polyai-adk[call]" uv tool install "polyai-adk[call]" ``` Then set up your account, API key, AI skills, and a project: ```bash poly setup ``` Once set up, use the `poly` command to manage your projects: ```bash 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: ```bash pip install polyai-adk ``` Once installed, the `poly` CLI command becomes available. ```bash 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: ```bash poly --help ``` to see all available commands. Each command also supports `--help` for detailed syntax: ```bash 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: ```bash 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: ```bash poly pull poly pull --force # overwrite all local changes poly pull --format # format resources after pulling ``` ### `poly push` Push local changes to Agent Studio: ```bash 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: ```bash poly status ``` ### `poly diff` Show diffs between your local project and the remote version, or between two named versions: ```bash 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: ```bash poly revert # revert all changes poly revert file1.yaml file2.yaml # revert specific files ``` ### `poly branch` Manage branches (default branch is `main`): ```bash 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: ```bash 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. ```bash poly format # all resources poly format --files file1.py # specific files poly format --check # check only, no writes ``` ### `poly validate` Validate project configuration locally: ```bash poly validate ``` ### `poly review` Create a GitHub gist for reviewing changes, similar to a pull request: ```bash 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: ```bash 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: ```bash 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 ```bash 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](https://github.com/PolyAI/adk/issues) page. ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and contribution guidelines. ## License This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.