polyai/adk/poly-adk-conversations

Reviewing Real Conversations

Load poly-adk-workflow first for the build loop this feeds back into. Once an agent handles real calls, the question becomes "what happened on that call?" — and answering it depends on instrumentation added while building. Logs and metrics are not available retroactively.

Inspecting conversations

poly conversations list                        # recent conversations: ID, start, duration, caller, channel, variant, handoff, summary
poly conversations list --limit 20 --offset 10
poly conversations get <conversation_id>       # full metadata + turn-by-turn transcript
poly conversations get-audio <conversation_id> -o recording.wav

• get includes channel, language, duration, handoff, tags, PolyScore, summary, and every turn — use --json when analyzing programmatically.
• get-audio downloads the WAV for a voice call; --direction user|agent|combined picks the track, --redacted fetches the redacted version.
• The CLI reads individual conversations. Aggregate views — containment, CSAT, handle time, flagged transcripts — live in Agent Studio, not the CLI.

Treat what you find as input to development: a surprising real conversation is the raw material for the next test_suite/ case (see poly-adk-testing). What callers actually say is reliably different from what you imagined.

Instrumenting functions

See poly docs functions for the full conv.log and metrics APIs.

Logging — record meaningful outcomes, not every step:

conv.log.info("Booking confirmed", reference=booking_ref)
conv.log.warning("Availability API slow, using cached slots")
conv.log.error("Payment provider returned 500")

Log around the things that can fail — API calls, validation, any branch you'd want to explain later. Never swallow an external failure silently: a bare except with no log turns a broken integration into a mysteriously unhelpful agent with nothing in the transcript to explain it.

Metrics — count outcomes you'll aggregate across calls (flow completions, handoffs fired, API fallbacks). The common mistake is inflation: a metric emitted in a loop or on every turn counts nothing useful. Use write_once=True for once-per-conversation events, and emit on the outcome you actually want to count.

The test for both: would this line help answer a question you can imagine being asked — "how often do callers abandon at payment?", "did that transfer actually fire?" If not, it's noise.

When debugging a specific call

1. poly conversations get <id> — read the transcript and logs turn by turn.
2. If the wording is right but the audio is wrong, it's a channel-settings problem, not a prompt problem: mishearing → voice/speech_recognition/ (keyphrase boosting, transcript corrections); mispronunciation → voice/response_control/ (pronunciations). See poly docs speech_recognition response_control.
3. Reproduce with poly chat (simulate SIP headers, variant, language — see poly-adk-testing), then encode the fix's verification as a test case.