poly) in any way. Entrypoint for the PolyAI ADK skills suite — covers setup, project\nstructure, resource choice, and the core edit/validate/push/test/merge workflow, and\nroutes to the task-specific skills (testing, branching, conversations, rtc).\nmetadata:\nauthor: PolyAI\nlicense: Apache-2.0\nversion: 0.71.3\nrequires:\nbins:\n- poly\ninstall: \"uv tool install polyai-adk\"The PolyAI ADK (poly) is a CLI for building dialog agents on the Agent Studio platform. It gives you a Git-like local workflow: agent resources (flows, functions, topics, entities, settings) live on disk as YAML, text, and Python files, and you pull, push, branch, and merge them against the platform.
Use poly <command> --help as the source of truth for flags. Almost every command accepts --json (a single JSON object on stdout, exit code 0 on success) — prefer it when you need to parse output.
This skill covers setup and the core loop. Load the matching skill when the task goes deeper:
\n| Task | \nSkill | \n
|---|---|
| Testing the agent — scripted chat, running the test suite, writing test cases | \npoly-adk-testing | \n
| Merge conflicts, branch management, sharing reviews | \npoly-adk-branching | \n
| Inspecting real conversations, logging and metrics | \npoly-adk-conversations | \n
| Per-environment real-time configuration | \npoly-adk-rtc | \n
Assume poly is installed. If a command fails because it isn't:
uv tool install polyai-adk (install uv first if needed: curl -LsSf https://astral.sh/uv/install.sh | sh)uv tool upgrade polyai-adkAssume the user is already logged in — do not check credentials up front. Only if a command fails with an authentication error, ask the user to run poly login — it opens a browser to sign in, so they must complete it themselves. Regions: studio for self-serve accounts, us / eu / uk for enterprise workspaces. On a fresh machine, poly setup runs sign-in plus shell completion, AI skills, and project setup in one command.
Credentials are resolved in this order: ~/.poly/credentials.json (written by poly login), then a region-scoped env var (POLY_ADK_KEY_US / POLY_ADK_KEY_EUW / POLY_ADK_KEY_UK / POLY_ADK_KEY_STUDIO), then POLY_ADK_KEY — useful when debugging why the CLI is using the wrong account or region. POLY_API_KEY is an account API key for the PolyAI APIs; the ADK does not read it, so exporting it does not log the CLI in. When no ADK key resolves, the error names the region, any other regions that already hold a key, and poly login --region <region> as the fix.
Before creating or editing any resource, load the built-in docs — they define each resource type's exact schema, valid values, and conventions:
\npoly docs # For the top level overview of all resource types\npoly docs {resource name} # For a specific resource type, e.g. flows, functions, topics, etc.\npoly docs flows functions topics # For multiple resource types at once\nRead the relevant sections before writing files. Do not guess at resource schemas — poly docs is authoritative for the installed version.
The three that overlap most are rules, topics, and functions. The test: if an instruction is always true, it belongs in agent_settings/rules.txt; if it's only relevant when a subject comes up, it belongs in a topic; if it needs a comparison, calculation, or API call, it belongs in a Python function. Prompts are for collecting and presenting information; Python is for branching, routing, and validation — never write \"if X then Y\" conditionals in prompt text.
Resources reference each other by name with {{prefix:name}} placeholders ({{fn:}} functions, {{entity:}} entities, {{ho:}} handoffs, {{attr:}} variant attributes, {{vrbl:}} state variables, {{twilio_sms:}} SMS templates, {{tn:}} translations). poly validate checks every reference resolves.
poly project create # create a new Agent Studio project and pull it locally\npoly init # connect to an existing project (interactive pickers)\npoly template list # optional: start from a pre-built template\npoly template load <name>\nProjects land in a <account_id>/<project_id>/ directory. Run all poly commands from inside the project directory, or pass --path.
A project looks like:
\n<account>/<project>/\n├── _gen/ # Generated stubs — NEVER edit\n├── agent_settings/ # persona.txt, rules.txt, guardrails, languages\n├── config/ # entities, handoffs, sms_templates, api_integrations, mcp, variants, translations\n├── context/ # background docs for Studio Assistant\n├── voice/ # voice channel config, speech_recognition/, response_control/\n├── chat/ # webchat channel config\n├── flows/ # multi-step guided conversations\n├── functions/ # Python functions (deterministic logic, lifecycle hooks)\n├── topics/ # knowledge base entries\n├── test_suite/ # simulated conversation tests\n├── real_time_configuration/ # per-environment RTC (see poly-adk-rtc)\n└── project.yaml # project metadata\nYou cannot work on main. Every change goes on a branch. The branch you are on determines what poly push writes to and what poly chat talks to.
poly pull # 1. start from the latest state on main\npoly branch create <name> # 2. create + switch to a branch (keeps local edits)\n# 3. edit resource files on disk\npoly status # 4. see unpushed local changes\npoly diff # inspect them in detail\npoly validate # 5. catch structural errors locally, before pushing\npoly push # 6. push to the branch\npoly chat --push # 7. test interactively (see poly-adk-testing)\npoly test run # and/or run the simulated test suite\n# 8. iterate: repeat 3–7\npoly branch diff # 9. review everything on the branch since creation\npoly branch merge '<message>' # 10. merge into main (deploys to sandbox automatically)\nKey distinctions:
\npoly status / poly diff show unpushed local edits; poly branch status / poly branch diff show everything on the branch since it was created. Use the branch-level commands before merging.poly revert discards local changes; poly format normalizes resource files.poly pull three-way merges rather than overwriting, and poly branch merge can conflict — if either reports conflicts, load poly-adk-branching for the resolution workflow.Four layers, catching different problems — load poly-adk-testing for the details of each:
| Command | \nCatches | \nRuns against | \n
|---|---|---|
poly validate | \nInvalid resources, missing values, broken references | \nLocal files | \n
poly chat | \nConversational behavior, judged by reading | \nLast pushed state | \n
poly test run | \nRegressions, repeatably | \nLast pushed state | \n
poly conversations | \nWhat happened on real calls | \nLive traffic | \n
poly chat and poly test run run against the last pushed state, not local files — push first, or use poly chat --push / poly test run --push.
Merging into main deploys to sandbox automatically. From there, promotion is one step at a time up the ladder — sandbox → pre-release → live:
poly deployments promote --from sandbox --to pre-release --dry-run\npoly deployments list # what is deployed where\nNever promote to pre-release or live unless the user explicitly asks — live is production. Use --dry-run first to preview, and re-run tests against each environment after promoting. See poly deployments --help for the full surface, including rollback.
_gen/ — generated stubs.main; check poly branch current if unsure.poly validate before every push — push runs the same validation and rejects what validate rejects.@func_description and @func_parameter decorators; without them the platform creates the function with no parameters and calls fail at runtime. Lifecycle functions and function steps don't need them.{{prefix:name}} syntax).poly pull reconciles.