Load poly-adk-workflow first for the overall build loop these commands fit into.
Four layers of verification, catching different problems:
\n| 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 (see poly-adk-conversations) | \nLive traffic | \n
poly chat and poly test run run against the last pushed state, not local files. Push first, or pass --push to push-and-run in one step. Both target the current branch by default; -e sandbox|pre-release|live targets a deployed environment instead.
poly validate checks local files without contacting the platform — malformed resources, missing required values, and {{prefix:name}} references that don't resolve. Run it as you edit, not just before pushing; poly push runs the same validation and rejects anything validate rejects.
As an agent, always use the non-interactive modes:
\npoly chat --push -m 'Hello' -m 'I want to book a table' --json\npoly chat --input-file ./script.txt # one message per line; - for stdin\npoly chat --metadata # show function calls, active flow/step, and state changes per turn\npoly chat --conv-id <id> -m 'Follow-up' # resume an existing conversation\nUseful flags for reproducing specific situations:
\n--channel voice|webchat — which channel's settings apply (default voice)--sip-header X-Customer-ID=12345 — simulate SIP headers, exposed to project functions via conv.sip_headers (repeatable; test-only, no real SIP call)--variant <name> — chat as a specific variant--lang / --input-lang / --output-lang — multilingual agentsWith --json, output is a conversations array with per-turn detail mirroring the --functions/--flows/--state flags you enabled.
Chat is for judging whether a conversation feels right. Anything worth checking twice belongs in the test suite instead.
\npoly call) — a user-only routepoly call places a live WebRTC voice call to the agent through the user's microphone and speaker (draft/branch build only). It's the route for judging voice-specific behavior — speech, timing, barge-in — that a transcript can't show.
It is interactive and human-driven: you (the AI agent) can't use it — there's no way to speak into a call or script it non-interactively. When a user wants to check voice/audio behavior, point them at poly call (poly call --help) rather than running it yourself.
Test cases live in test_suite/ and assert what the agent should say and which functions it should call. They are the only repeatable layer — the thing that stops a fixed bug coming back. Run poly docs tests for the file format and available assertions before writing cases.
poly test run # all tests, polls until complete, non-zero exit on failure\npoly test run --tag smoke # only tagged tests (multiple tags OR-match)\npoly test run --files greeting_flow_test.yaml # bare names, paths or quoted globs\npoly test run --dry-run # preview which tests would run\npoly test run --dont-poll # trigger and exit; check later with poly test show\npoly test run --json # never polls: returns the pending run and next_command to check on it\npoly test run --tag smoke --name \"Pre-release check · booking flow\" # name the run\npoly test list # past runs\npoly test show <run_id> # run summary + per-test table\npoly test show <run_id> <test_case_id> # assertion results, function failures, full transcript\nStatuses: pending, in_progress, passed, failed (assertion failed), errored, timed_out. After a run, failures are summarized with assertion reasons and conversation IDs.
Write cases for the paths that are tedious to reach by hand — an unavailable API, a caller changing their mind, variant-specific behavior. For the API case, api_mocks forces a named API integration operation to return a fixed response so the test is deterministic (see poly docs tests).
To debug one function without a conversation:
\npoly functions execute <function_name> --args '{\"x\": 1}' --json # returns body, logs, runtime\npoly functions validate # syntax errors + orphaned flow-step references\nLimitations: builds a fresh conv from the branch config — no live caller, conv.state starts empty and is not persisted, and conv.say/conv.goto_flow/conv.call_handoff have no channel to act on. Covers global functions only, not flow transition functions or function steps. There is no way to attach to a real call.
Both subcommands accept --region --project_id --branch_id (all three together) to run headlessly without a local checkout.
Validation and chat belong in the edit loop; the test suite belongs before merging; and after promoting to an environment, re-run chat and tests against it with -e. A surprising real conversation found via poly-adk-conversations is the raw material for the next test case.