v0.11.0

v0.11.0 (2026-04-21)

This release is published under the Apache-2.0 License.

Documentation

• Feat(cli): deployment history and version-scoped diff/review (#90, bf0939d)

Summary

This covers the work from #39

Motivation

Closes #

Changes

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [x] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [x] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Features

• Add 'studio' region and filter region selection based on permissions (#82, d4af195)

Summary

Updates poly init to only display regions the user's API key has access to, and adds the studio region.

Motivation

Previously, poly init showed all hardcoded regions regardless of whether the user had access. This change probes regions concurrently and filters the list. Additionally, studio was not available as a region.

Changes

• Added get_accessible_regions() to PlatformAPIHandler that concurrently probes regions via get_accounts() and returns only accessible ones - Added get_accessible_regions() to AgentStudioInterface as the public interface - Updated init_project() in cli.py to fetch and display only accessible regions (with a loading spinner), with an error message if none are found - Added "studio" region pointing to https://api.studio.poly.ai/adk/v1

Test strategy

• Added/updated unit tests - [x] Manual CLI testing (poly <command>) - [x] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [x] pytest passes - [x] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

---

Detailed Changes: v0.10.0...v0.11.0

v0.10.0

v0.10.0 (2026-04-17)

This release is published under the Apache-2.0 License.

Features

• cli: Deployment history and version-scoped diff/review (#39, 0730d06)

Summary Adds poly deployments, extends diff / review with hash and --before / --after / --files, updates. Updates review to be review create to be similar with branch commands

Motivation Improves visibility into deployed versions and makes comparing local vs remote or named versions consistent in the CLI.

Changes - poly deployments with --env, pagination, --hash, --oneline, --json; Rich output with sandbox / pre-release / live badges. - get_deployments (API + project): client_env, list return shape, tuple with active hashes on AgentStudioProject. - poly diff / poly review: optional hash, --files, --before / --after; --delete on review; shared diff computation. - poly review logic moved to poly review create - poly revert / poly format: CLI shape updates to be consistent (--all removed; format uses --files).

Test strategy - [x] Added/updated unit tests - [x] Manual CLI testing (poly <command>) - [x] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist - [x] ruff check . and ruff format --check . pass - [x] pytest passes - [x] No breaking changes to the poly CLI interface (or migration path documented) - [x] Commit messages follow conventional commits

Screenshots / Logs

--details

--env

---

Detailed Changes: v0.9.1...v0.10.0

v0.9.1

v0.9.1 (2026-04-17)

This release is published under the Apache-2.0 License.

Bug Fixes

• Don't show diff for reordered entities (#87, 2a0ff85)

Summary

Fix spurious diffs after push caused by extracted_entities list ordering differences between local YAML and the platform.

Motivation

After pushing, poly diff shows reordering-only changes to extracted_entities in flow steps. The platform returns entity IDs in a different order than local YAML, producing false diffs with no meaningful content change.

Changes

• Sort extracted_entities in FlowStep.to_yaml_dict() so both local and remote representations use a consistent alphabetical order

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [x] pytest passes - [x] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

Documentation

• Add missing warnings for key ADK footguns and workflow gaps (#86, 4391333)

Summary

Addresses the documentation gaps identified from a real end-to-end AI-agent workflow build (Bella Vista reservation assistant) that caused significant lost time. Each change adds a targeted note or warning where the docs were silent on a real failure mode.

Motivation

A systematic audit against a live implementation identified six gaps where the docs' silence or vagueness caused actual blockers — not theoretical ones. Several required digging through source code to resolve.

Changes

Gap 1 — No local runtime - testing.md: prominent warning that there is no poly serve or local simulator; all execution is in Agent Studio Sandbox - what-is-the-adk.md: clarify the ADK manages config files and does not execute agents

Gap 2 — API keys are workspace-scoped - prerequisites.md: warning that poly init lists all projects visible to the key; seeing unexpected projects means the wrong key is in use; also removes a garbled duplicate section from a previous edit

Gap 3 — Platform-provisioned resources cannot be created via ADK - voice_settings.md, chat_settings.md, agent_settings.md, speech_recognition.md: note on each page that greeting/style prompt/disclaimer/personality/role/ASR settings are provisioned by Agent Studio on project init and can only be updated, not created; pushing them into a project without a matching .agent_studio_config entry fails with NotImplementedError: Create operation not supported

Gap 4 — Don't copy project directories - anti-patterns.md: new section explaining why copying a project directory to a different project causes push failures (.agent_studio_config IDs, platform-provisioned resources); correct approach is poly init + poly pull

Gap 6 — No poly merge command - tutorials/build-an-agent.md: note at Workflow 1 Step 10 and Workflow 2 Step 7 that merging requires the Agent Studio web UI; there is no CLI command

Minor gaps - tutorials/build-an-agent.md: mark chat/ as optional in the project structure diagram - tutorials/build-an-agent.md: add tip in AI-agent Workflow 2 Step 3 to run poly docs --all immediately after poly pull, before generating any files — without it, a coding agent has no schema context and will hallucinate resource structure

What was not addressed

• poly merge CLI command — this is a code change, not a doc change; documented as a known gap - Gap 5 (branch --environment 404) — cli.md already partially covers branch environment behavior; the failure mode may be platform-specific and is not clearly reproducible

Test strategy

• N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [x] pytest passes - [x] No breaking changes to the poly CLI interface (or migration path documented) - [x] Commit messages follow conventional commits

Note: prerequisites.md is also touched by #85 (tab rename). Whichever merges second will need a quick rebase.

---

Co-authored-by: Claude Sonnet 4.6 noreply@anthropic.com

• Add onboarding page and wire into get-started nav (#78, b0654b5)

Summary

Adds a new get-started/agent-wizard.md page at the top of the Get Started section, before any ADK content. Covers two user paths: new users building their first agent via Agent Wizard, and existing Agent Studio users pulling down an existing project.

Motivation

Users arriving at the ADK docs without an existing agent had no clear entry point. Agent Wizard is the fastest way to create one, but there was no documentation connecting the two products.

Closes #

Changes

• New page docs/docs/get-started/agent-wizard.md — new user onboarding via Agent Wizard, including the concrete poly init --account_id ... --project_id ... + poly pull handoff to local development - mkdocs.yml — new page added as first item in Get Started nav - index.md — hero card updated to surface Agent Wizard as the entry point for users without an agent - what-is-the-adk.md — next steps now includes a card pointing to the Agent Wizard page

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [x] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [x] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

---

Co-authored-by: Claude Sonnet 4.6 noreply@anthropic.com

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

• Feat: non-interactive scripted input, conversation resume, pre-chat push, and JSON output for poly chat (#83, 1209129)

Summary

This is the work from #69

Motivation

Closes #

Changes

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [x] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [x] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

---

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Co-authored-by: Claude Sonnet 4.6 noreply@anthropic.com

• Fix API key provisioning — self-generated, not provided by contact (#84, a1c9250)

Summary

Corrects the inaccurate claim that both workspace access and the API key are provided by a PolyAI contact. The API key is self-generated by the user inside Agent Studio.

Motivation

The docs stated "Both are provided by your PolyAI contact" — this is wrong for the API key. It also meant the Getting Started flow sent users to Prerequisites for an API key after they'd already been told to run poly pull, which requires the key.

Changes

• access-and-waitlist.md: distinguish workspace access (from contact) vs API key (self-generated in Agent Studio) - prerequisites.md: update checklist item from "obtained from your PolyAI contact" to "generated in Agent Studio" - get-started.md: add Step 5 — Generate an API key (with POLY_ADK_KEY env var export) between finding account/project IDs and pulling; renumber Steps 5–6 → 6–7; replace the misplaced "Next step → Prerequisites" CTA with "Next step → Installation"

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [x] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [x] pytest passes - [x] No breaking changes to the poly CLI interface (or migration path documented) - [x] Commit messages follow conventional commits

---

Co-authored-by: Claude Sonnet 4.6 noreply@anthropic.com

• Improve first-steps get-started page (#88, cb99c5b)

Summary

• Adds missing screenshots (agent-studio-login.png, go-back-to-key.png) for the get-started flow
• Moves sign-up instructional text above the screenshot for better reading order

Test plan

• Verify images render correctly in the docs site
• Check that the get-started page reads logically top to bottom

🤖 Generated with [Claude Code](https://claude.com/claude-cod...

v0.9.0

v0.9.0 (2026-04-16)

This release is published under the Apache-2.0 License.

Documentation

• Allow specifying lang code in chat requests (#81, e6d8f3f)

Summary

Motivation

Closes #

Changes

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [x] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [ ] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Features

• Non-interactive scripted input, conversation resume, pre-chat push, and JSON output for poly chat (#69, 7a1ae59)

Summary

Extends poly chat with four new capabilities: push before chatting (--push), scripted/file-based message input (-m/--input-file), resuming an existing conversation (--conv-id), and structured JSON output (--json). Interactive mode is fully unchanged.

Motivation

Makes poly chat usable in automated testing pipelines and CI scripts without a human at the terminal. --push removes the manual push step before testing a branch.

Changes

• --push: pushes the project before creating the chat session so local changes are live before testing - --message/-m (repeatable): supply utterances non-interactively, e.g. -m "Hello" -m "Goodbye" - --input-file FILE: reads messages line-by-line from a file; use - for stdin - --conv-id: resumes an existing conversation by ID, skipping session creation entirely - --json: emits a single JSON object {"conversations": [...]} when the session ends; each conversation contains conversation_id, url, and turns (greeting is turns[0] with "input": null); restarts produce multiple entries in the array - _run_chat_loop now returns (restart, conversation_dict) so the caller accumulates conversations across restarts before printing - Clean error message when --input-file path does not exist - Updated chat_parser help text with examples for all new flags

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [ ] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

---

Co-authored-by: Copilot 175728472+Copilot@users.noreply.github.com

---

Detailed Changes: v0.8.5...v0.9.0

v0.8.5

v0.8.5 (2026-04-15)

This release is published under the Apache-2.0 License.

Bug Fixes

• Allow specifying lang code in chat requests (#80, b9070b9)

Summary

Adds --lang, --input-lang, and --output-lang flags to poly chat, allowing users to specify language codes for ASR (input) and TTS (output) when starting or continuing a chat session.

Motivation

Users chatting against multilingual agents need a way to specify the expected input/output language without relying on the project default. This exposes the existing asr_lang_code / tts_lang_code API fields via the CLI.

Changes

• Added --lang, --input-lang, --output-lang arguments to the chat subcommand in cli.py - --lang sets both input and output lang; --input-lang/--output-lang override individually - Threaded input_lang / output_lang through AgentStudioProject.create_chat_session, send_message, AgentStudioInterface, and PlatformAPIHandler for both standard and draft/branch chat flows - Maps input_lang → asr_lang_code and output_lang → tts_lang_code in API request payloads

Test strategy

• Added/updated unit tests - [x] Manual CLI testing (poly <command>) - [x] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [x] pytest passes - [x] No breaking changes to the poly CLI interface (or migration path documented) - [x] Commit messages follow conventional commits

Screenshots / Logs

Chores

• Add docs team to CODEOWNERS (#77, 7c01266)

Summary Create docs team as a code owner so we can loosen PR approval policies when only targeting documentation.

Motivation Our docs team is getting slowed down needing engineering approval for minor doc changes.

Documentation

• Adk branch create --env flag to specify source env for new branch (#57, 2de96af)

Summary

This PR is related to #56

Motivation

Closes #

Changes

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [ ] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

---

Co-authored-by: Ruari Phipps ruari@poly-ai.com

• Chore: Update experimental config (#74, 838f437)

Summary

Motivation

Closes #

Changes

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [x] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [ ] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

• Fix: --debug flag to poly review command that enables DEBUG-level (#76, 165f81c)

Summary

Motivation

Closes #

Changes

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [ ] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

• Fix: Raise proper error message for invalid format functions (#72, 15830a2)

Summary

Motivation

Closes #

Changes

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [x] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [ ] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

---

Detailed Changes: v0.8.4...v0.8.5

v0.8.4

v0.8.4 (2026-04-14)

This release is published under the Apache-2.0 License.

Bug Fixes

• Don't delete or fail to update conditions when their parent step… (#71, 85c6aea)

Summary

Fixes two bugs in _clean_resources_before_push that caused push failures when a flow step with conditions was deleted.

Motivation

When a FlowStep is deleted, Agent Studio automatically deletes its child Conditions server-side. This caused two issues: 1. Explicitly including the condition in deleted_resources would result in a double-delete error. 2. If a condition was also being updated (e.g. re-pointed to a new step), the update request would fail because the platform had already deleted the condition when the step was removed.

Changes

• Strip conditions from deleted_resources when their parent FlowStep is being deleted (platform handles the cascade) - Promote affected conditions from updated_resources to new_resources when their original child_step is being deleted in the same push

Test strategy

• Added/updated unit tests - [x] Manual CLI testing (poly <command>) - [x] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [x] pytest passes - [ ] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

---

Co-authored-by: Copilot Autofix powered by AI 175728472+Copilot@users.noreply.github.com

---

Detailed Changes: v0.8.3...v0.8.4

v0.8.3

v0.8.3 (2026-04-14)

This release is published under the Apache-2.0 License.

Bug Fixes

• Empty diff entries caused a 422 error from the GitHub Gists API (#75, 6ffa08f)

Summary

• Add --debug flag to poly review command that enables DEBUG-level logging for easier troubleshooting
• Fix bug where empty diff entries caused a 422 error from the GitHub Gists API (missing_field: files)

Test plan

• Run poly review --debug and verify debug logs appear
• Run poly review without --debug and verify only warnings are shown
• Verify that projects with empty diffs no longer trigger a 422 gist creation error

🤖 Generated with Claude Code

---

Co-authored-by: Claude Opus 4.6 (1M context) noreply@anthropic.com

Chores

• Update experimental config (#73, 10840e5)

Summary Update experimental config

Motivation Get new features

Changes Update to latest

Test strategy

• Added/updated unit tests
• Manual CLI testing (poly <command>)
• Tested against a live Agent Studio project
• N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass
• pytest passes
• No breaking changes to the poly CLI interface (or migration path documented)
• Commit messages follow conventional commits

Screenshots / Logs

---

Detailed Changes: v0.8.2...v0.8.3

v0.8.2

v0.8.2 (2026-04-10)

This release is published under the Apache-2.0 License.

Bug Fixes

• Allow ?query ending for API operations (#70, 4199800)

Summary Update validation regex to allow API operation with ?query ending

Motivation

Closes #

Changes

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [ ] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

---

Detailed Changes: v0.8.1...v0.8.2

v0.8.1

v0.8.1 (2026-04-10)

This release is published under the Apache-2.0 License.

Bug Fixes

• Raise proper error message for invalid format functions (#68, 5222f3e)

Summary

Fixes two related issues: untyped or unsupported function parameters now raise a clear ValueError instead of crashing with AttributeError, and merge-conflicted files are correctly excluded from modified_files in project_status and handled without crashing in get_diffs. Also surfaces all CLI errors as structured JSON when --json is set.

Motivation

In v0.6.x, functions with untyped parameters (e.g. def f(conv, booking_ref)) caused _extract_decorators to crash with AttributeError: 'NoneType' has no attribute 'id'. Separately, files with merge conflicts were being passed to read_local_resource, which would now raise rather than silently fail. Both issues needed to be fixed together for poly status and poly diff to be reliable after a branch pull with conflicts.

Closes #

Changes

• _extract_decorators: guard arg.annotation access before reading .id; raise ValueError with a distinct message for missing vs unsupported type annotations; remove the try/except SyntaxError wrapper so errors propagate to the user - resource.py: rename get_status → is_modified, removing merge conflict detection from the resource itself - project_status: check for merge conflicts on raw file content before calling read_local_resource; conflicted files now appear only in files_with_conflicts, not also in modified_files - get_diffs: same conflict-before-parse pattern; shows diff of conflict markers vs original; fix type(resource_type) key bug and missing second arg to get_diff - cli.py: wrap the command dispatch in try/except; when --json is set, errors are returned as {"success": false, "error": "...", "traceback": "..."} instead of raising - src/poly/docs/functions.md: note that all parameters must have a supported type annotation

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [x] pytest passes - [x] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

Documentation

• Feat: add poly branch delete command (#67, 285327b)

Summary

This PR is related to #63

Motivation

Closes #

Changes

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [ ] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

• Fix prerequisites around API key generation (#59, 4fea771)

Summary

This PR relates to #45 and updates API key generation info

Motivation

Closes #

Changes

Test strategy

• Added/updated unit tests - [ ] Manual CLI testing (poly <command>) - [ ] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [ ] pytest passes - [ ] No breaking changes to the poly CLI interface (or migration path documented) - [ ] Commit messages follow conventional commits

Screenshots / Logs

---

Detailed Changes: v0.8.0...v0.8.1

v0.8.0

v0.8.0 (2026-04-08)

This release is published under the Apache-2.0 License.

Features

• Add poly branch delete command (#63, 463a663)

Summary

Adds poly branch delete — an interactive command for deleting branches, following the same UX pattern as poly review delete.

Motivation

Branch deletion was already implemented in the backend (project.delete_branch()) but not exposed through the CLI.

Changes

• Added delete subcommand to poly branch with optional branch_name argument - Interactive checkbox selection (via questionary) when no branch name is provided - Direct deletion mode when branch name is passed as argument - JSON output mode support (--json) - Filters out main branch (cannot be deleted) - 16 new unit tests covering all code paths

Test strategy

• Added/updated unit tests - [x] Manual CLI testing (poly <command>) - [x] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change)

Checklist

• ruff check . and ruff format --check . pass - [x] pytest passes (431 tests) - [x] No breaking changes to the poly CLI interface (or migration path documented) - [x] Commit messages follow conventional commits

🤖 Generated with Claude Code

---

Co-authored-by: Claude Opus 4.6 (1M context) noreply@anthropic.com

Co-authored-by: Ruari Phipps ruari@poly-ai.com

---

Detailed Changes: v0.7.3...v0.8.0