diff --git a/README.md b/README.md index b23a0c8..e198e4e 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ Demos with a **Live** link run in your browser at [demos.speechify.ai](https://d | [`demos/mastra-agent-speechify/`](./demos/mastra-agent-speechify) | TypeScript (Mastra) | | Text-in, speech-out Mastra Agent using an OpenAI LLM for replies and Speechify's simba-3.2 model for TTS via `@mastra/voice-speechify`. | | [`demos/voice-agent-showcase/`](./demos/voice-agent-showcase) | Cloudflare Workers | | One page, ten live Voice Agents API demos: calendar booking, policy-bound support, a page copilot, form intake, US outbound calls with a 5-minute cap, a voice gallery, mid-call language handoff, cross-call memory, a grounded knowledge base, and dual-control troubleshooting. | | [`demos/vercel-ai-sdk/`](./demos/vercel-ai-sdk) | TypeScript (Vercel AI SDK) | | Speechify TTS through the Vercel AI SDK's unified `generateSpeech` interface via the official `@speechify/vercel` provider — one-line swap from OpenAI/ElevenLabs, plus word-level speech marks from `providerMetadata`. | +| [`demos/agent-events-inspector/`](./demos/agent-events-inspector) | Next.js | [Open](https://demos.speechify.ai/agent-events-inspector) | A debug timeline for Voice Agent calls: replay a sample realtime event stream, or inspect a live conversation by id. The workspace key stays server-side. | ## Get an API key diff --git a/demos/agent-events-inspector/.env.example b/demos/agent-events-inspector/.env.example new file mode 100644 index 0000000..534cec4 --- /dev/null +++ b/demos/agent-events-inspector/.env.example @@ -0,0 +1 @@ +SPEECHIFY_API_KEY=your_api_key_here diff --git a/demos/agent-events-inspector/.gitignore b/demos/agent-events-inspector/.gitignore new file mode 100644 index 0000000..e838375 --- /dev/null +++ b/demos/agent-events-inspector/.gitignore @@ -0,0 +1,9 @@ +node_modules/ +.next/ +.env +next-env.d.ts +*.tsbuildinfo +test-results/ +playwright-report/ +/.playwright/ +.last-run.json diff --git a/demos/agent-events-inspector/README.md b/demos/agent-events-inspector/README.md new file mode 100644 index 0000000..c67d1dc --- /dev/null +++ b/demos/agent-events-inspector/README.md @@ -0,0 +1,58 @@ +# Voice agent events inspector + +A tiny debug view for a Speechify Voice Agent call. Watch a call unfold as a +timeline of realtime events — session start, user transcripts, agent replies, +tool calls and results, session end — either by **replaying a bundled sample +stream** or by **inspecting one of your own conversations by id**. The workspace +API key stays server-side. + +Pairs with the Speechify post *Realtime agent events: debugging a live voice +agent call*. + +## What you get + +- A **timeline** that colour-codes events by source (session / user / agent / + tool) and lets you expand any event's raw JSON payload. +- **Replay mode** — plays the sample event stream in + [`app/sample-events.ts`](./app/sample-events.ts) against a scrubber, at + 0.5×–4× speed, so you can see how a call reads as a stream. +- **Inspect mode** — enter a `conv_…` id (or leave blank to list recent calls); + the server proxies `GET /v1/agents/conversations/{id}` on the Voice Agents API + and renders what comes back. +- **[`app/api/conversation/route.ts`](./app/api/conversation/route.ts)** — the + one server route that holds the key and talks to the API. + +## Run it yourself + +```bash +cp .env.example .env # paste your Speechify workspace API key +pnpm install +pnpm dev # http://localhost:8774/agent-events-inspector +``` + +Get a workspace key at [platform.speechify.ai/api-keys](https://platform.speechify.ai/api-keys). +Replay mode needs no key; inspect mode needs a key with a Voice Agents workspace. + +## On the event schema + +The confirmed conversation record fields are `id`, `agent_id`, `status`, +`started_at`, `ended_at`, and `duration_ms` — the same ones the +[voice-agent-showcase](../voice-agent-showcase) reads. The per-event stream shape +in `app/sample-events.ts` is **illustrative**: it shows how you'd render a live +event feed, and the inspector renders whichever event/transcript array a live +conversation returns. Confirm the exact live event field names against the +[Voice Agents API docs](https://docs.speechify.ai) before wiring this to a +production audit tool. + +## Abuse protection (hosted) + +The hosted build gates `/api/conversation` with Cloudflare Turnstile via the +shared [`app/lib/turnstile.ts`](./app/lib/turnstile.ts) helper. It fail-opens +when `TURNSTILE_SECRET_KEY` is unset, so local dev and forks work with zero +config. + +## Prerequisites + +- Node 20+. +- For inspect mode: a Speechify workspace with the Voice Agents API and at least + one conversation to look at. diff --git a/demos/agent-events-inspector/app/api/conversation/route.ts b/demos/agent-events-inspector/app/api/conversation/route.ts new file mode 100644 index 0000000..9e6d1dc --- /dev/null +++ b/demos/agent-events-inspector/app/api/conversation/route.ts @@ -0,0 +1,53 @@ +import { NextResponse } from "next/server"; +import { verifyTurnstile } from "../../lib/turnstile"; + +export const runtime = "nodejs"; + +const BASE = "https://api.speechify.ai"; + +// Proxies the Voice Agents conversations API so the workspace key never reaches +// the browser. A single id returns that conversation; no id lists recent ones. +export async function POST(req: Request) { + if (!(await verifyTurnstile(req))) { + return NextResponse.json({ error: "Forbidden" }, { status: 403 }); + } + + const key = process.env.SPEECHIFY_API_KEY; + if (!key) { + return NextResponse.json( + { error: "SPEECHIFY_API_KEY is not set on the server." }, + { status: 503 }, + ); + } + + const { id } = (await req.json().catch(() => ({}))) as { id?: string }; + + // conv_ ids only — don't proxy arbitrary paths. + if (id && !/^conv_[a-z0-9]+$/i.test(id)) { + return NextResponse.json({ error: "That doesn't look like a conversation id (conv_…)." }, { status: 400 }); + } + + const path = id ? `/v1/agents/conversations/${id}` : `/v1/agents/conversations?limit=20`; + + try { + const upstream = await fetch(`${BASE}${path}`, { + headers: { Authorization: `Bearer ${key}` }, + }); + const text = await upstream.text(); + let data: unknown = null; + try { + data = text ? JSON.parse(text) : null; + } catch { + /* non-JSON upstream error */ + } + if (!upstream.ok) { + return NextResponse.json( + { error: `Upstream ${upstream.status}`, detail: data ?? text.slice(0, 300) }, + { status: upstream.status }, + ); + } + return NextResponse.json(data); + } catch (err) { + return NextResponse.json({ error: (err as Error).message }, { status: 502 }); + } +} diff --git a/demos/agent-events-inspector/app/globals.css b/demos/agent-events-inspector/app/globals.css new file mode 100644 index 0000000..c96c327 --- /dev/null +++ b/demos/agent-events-inspector/app/globals.css @@ -0,0 +1,389 @@ +/* Speechify brand base — mirrors demos.speechify.ai/site (speechify.ai/brand). + * ABC Diatype is licensed and NOT committed; it is loaded cross-origin from + * speechify.ai/fonts (served with Access-Control-Allow-Origin: *). Monochrome + * palette, thin display type, pill ink buttons, sentence-case voice. + * Paste this block at the TOP of the demo's app/globals.css, then make the + * demo-specific rules below it reference these tokens (no hardcoded colours). */ + +@font-face { font-family: "ABCDiatype"; src: url("https://speechify.ai/fonts/ABCDiatype-Thin.woff2") format("woff2"); font-weight: 100; font-style: normal; font-display: swap; } +@font-face { font-family: "ABCDiatype"; src: url("https://speechify.ai/fonts/ABCDiatype-Light.woff2") format("woff2"); font-weight: 300; font-style: normal; font-display: swap; } +@font-face { font-family: "ABCDiatype"; src: url("https://speechify.ai/fonts/ABCDiatype-Regular.woff2") format("woff2"); font-weight: 400; font-style: normal; font-display: swap; } +@font-face { font-family: "ABCDiatype"; src: url("https://speechify.ai/fonts/ABCDiatype-Medium.woff2") format("woff2"); font-weight: 500; font-style: normal; font-display: swap; } +@font-face { font-family: "ABCDiatype"; src: url("https://speechify.ai/fonts/ABCDiatype-Bold.woff2") format("woff2"); font-weight: 700; font-style: normal; font-display: swap; } + +:root { + --font-sans: "ABCDiatype", ui-sans-serif, system-ui, -apple-system, sans-serif; + --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, "Cascadia Code", monospace; + + --surface-page: #ffffff; + --surface-card: #ffffff; + --surface-subtle: #f5f5f5; + --surface-raised: #fafafa; + --text-primary: #0a0a0a; + --text-secondary: #525252; + --text-tertiary: #666666; + --border-subtle: #e5e5e5; + --border-strong: #d1d1d4; + --action: #0a0a0a; + --action-hover: #2a2a2e; + --action-foreground: #fafafa; + --focus-ring: rgba(10, 10, 10, 0.22); + --success: #00c270; + --danger: #b42318; + --radius-md: 8px; + --radius-lg: 12px; + --radius-pill: 9999px; +} + +/* Interactive apps: keep a monochrome dark mapping so night viewers aren't + * blinded. Still monochrome, still on-brand (inverted ink/paper). */ +@media (prefers-color-scheme: dark) { + :root { + --surface-page: #0a0a0a; + --surface-card: #101010; + --surface-subtle: #161616; + --surface-raised: #141414; + --text-primary: #fafafa; + --text-secondary: #b3b3b3; + --text-tertiary: #8a8a8a; + --border-subtle: #262626; + --border-strong: #3a3a3a; + --action: #fafafa; + --action-hover: #e5e5e5; + --action-foreground: #0a0a0a; + --focus-ring: rgba(250, 250, 250, 0.28); + } +} + +* { box-sizing: border-box; } + +body { + margin: 0; + padding: 4rem 1.5rem; + background: var(--surface-page); + color: var(--text-primary); + font-family: var(--font-sans); + font-weight: 400; + line-height: 1.55; + -webkit-font-smoothing: antialiased; + text-rendering: optimizeLegibility; +} + +main { + max-width: 44rem; + margin: 0 auto; + display: flex; + flex-direction: column; + gap: 1.75rem; +} + +/* Thin display headings, tight tracking, sentence case (author copy in sentence case). */ +h1 { + font-weight: 100; + font-size: clamp(2.25rem, 6vw, 3.5rem); + line-height: 1.02; + letter-spacing: -0.03em; + margin: 0 0 0.5rem; +} +h2 { font-weight: 300; letter-spacing: -0.01em; margin: 0 0 0.5rem; } + +.eyebrow { + font-family: var(--font-mono); + font-size: 13px; + font-weight: 500; + letter-spacing: 0.02em; + color: var(--text-tertiary); + text-transform: none; + margin: 0 0 0.75rem; +} + +.lead { + max-width: 62ch; + color: var(--text-secondary); + font-size: 1.0625rem; + line-height: 1.55; + margin: 0; +} + +a { color: var(--text-primary); text-underline-offset: 2px; } + +code, kbd, samp { font-family: var(--font-mono); } +code { + background: var(--surface-subtle); + border: 1px solid var(--border-subtle); + padding: 0.08em 0.38em; + border-radius: 5px; + font-size: 0.88em; +} + +.card, .step { + background: var(--surface-subtle); + border: 1px solid var(--border-subtle); + border-radius: var(--radius-lg); + padding: 1.25rem; +} + +label { display: block; font-size: 0.9rem; color: var(--text-secondary); margin: 0 0 0.5rem; } + +input[type="text"], input[type="email"], textarea, select { + width: 100%; + font: inherit; + color: var(--text-primary); + background: var(--surface-card); + border: 1px solid var(--border-subtle); + border-radius: var(--radius-md); + padding: 0.65rem 0.8rem; +} +textarea { resize: vertical; } + +input:focus-visible, textarea:focus-visible, select:focus-visible, button:focus-visible { + outline: 3px solid var(--focus-ring); + outline-offset: 1px; +} + +/* Pill buttons — medium weight only, never 600. */ +.btn, button.btn { + font: inherit; + font-weight: 500; + cursor: pointer; + display: inline-flex; + align-items: center; + justify-content: center; + gap: 0.4rem; + border-radius: var(--radius-pill); + padding: 0.65rem 1.5rem; + border: 1px solid transparent; + transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease; +} +.btn-primary { background: var(--action); color: var(--action-foreground); } +.btn-primary:hover:not(:disabled) { background: var(--action-hover); } +.btn-outline { background: transparent; color: var(--text-primary); border-color: var(--border-strong); } +.btn-outline:hover:not(:disabled) { background: var(--action); color: var(--action-foreground); border-color: var(--action); } +.btn:disabled { opacity: 0.55; cursor: default; } + +footer { + color: var(--text-tertiary); + font-size: 0.9rem; + border-top: 1px solid var(--border-subtle); + padding-top: 1.25rem; +} +footer a { color: inherit; } + +@media (prefers-reduced-motion: reduce) { + * { animation-duration: 0.001ms !important; animation-iteration-count: 1 !important; transition-duration: 0.001ms !important; } +} + +/* ── Demo-specific: agent events inspector ───────────────────────────────── + * A dense debug timeline needs a slightly wider column than the 44rem default. + * Event-type rail colours are kept as semantic accents (see brand note: agent + * event-type colours may stay as-is); everything else references brand tokens. */ + +main { max-width: 46rem; } + +/* Event-type accents for the timeline rail — semantic, kept as-is. */ +:root { + --session: #6b7280; + --user: #2563eb; + --agent: #059669; + --tool: #d97706; + --other: #9333ea; +} + +@media (prefers-color-scheme: dark) { + :root { + --session: #9ca3af; + --user: #60a5fa; + --agent: #34d399; + --tool: #fbbf24; + --other: #c084fc; + } +} + +.tabs { + display: flex; + gap: 0.5rem; +} + +.tabs button { + font: inherit; + font-weight: 500; + cursor: pointer; + padding: 0.5rem 1.1rem; + border-radius: var(--radius-pill); + border: 1px solid var(--border-strong); + background: transparent; + color: var(--text-primary); + transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease; +} + +.tabs button.on { + background: var(--action); + color: var(--action-foreground); + border-color: var(--action); +} + +.panel { + border: 1px solid var(--border-subtle); + border-radius: var(--radius-lg); + padding: 1rem; + background: var(--surface-subtle); +} + +.meta { + display: flex; + align-items: center; + gap: 0.6rem; + flex-wrap: wrap; + margin-bottom: 0.75rem; + font-size: 0.85rem; + color: var(--text-secondary); +} + +.pill { + border: 1px solid var(--border-subtle); + border-radius: var(--radius-pill); + padding: 0.05rem 0.6rem; + font-size: 0.75rem; + text-transform: uppercase; + letter-spacing: 0.06em; +} + +.controls { + display: flex; + align-items: center; + gap: 0.75rem; + margin-bottom: 0.75rem; + flex-wrap: wrap; +} + +.controls input[type="range"] { + flex: 1; + min-width: 8rem; +} + +.controls label { + display: flex; + align-items: center; + gap: 0.35rem; + font-size: 0.85rem; + color: var(--text-secondary); + margin: 0; +} + +.controls select { + width: auto; + padding: 0.35rem 0.5rem; + border-radius: var(--radius-md); +} + +.live-input { + display: flex; + gap: 0.5rem; + margin-bottom: 0.5rem; +} + +.live-input input { + flex: 1; +} + +.timeline { + list-style: none; + margin: 0; + padding: 0; + display: flex; + flex-direction: column; + gap: 0.25rem; +} + +.evt { + display: grid; + grid-template-columns: 5.5rem 11rem 1fr auto; + gap: 0.5rem; + align-items: baseline; + padding: 0.35rem 0.5rem; + border-left: 3px solid var(--border-subtle); + border-radius: 0 5px 5px 0; + background: var(--surface-card); + font-size: 0.85rem; +} + +.evt.active { + outline: 2px solid var(--agent); +} + +.evt.session { border-left-color: var(--session); } +.evt.user { border-left-color: var(--user); } +.evt.agent { border-left-color: var(--agent); } +.evt.tool { border-left-color: var(--tool); } +.evt.other { border-left-color: var(--other); } + +.evt .t { + color: var(--text-tertiary); + font-family: var(--font-mono); + font-size: 0.78rem; +} + +.evt .type { + font-family: var(--font-mono); + font-size: 0.8rem; +} + +.evt.session .type { color: var(--session); } +.evt.user .type { color: var(--user); } +.evt.agent .type { color: var(--agent); } +.evt.tool .type { color: var(--tool); } +.evt.other .type { color: var(--other); } + +.evt .summary { + color: var(--text-secondary); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.evt .peek { + font: inherit; + font-size: 0.75rem; + cursor: pointer; + border: 1px solid var(--border-subtle); + border-radius: 5px; + background: var(--surface-subtle); + color: var(--text-primary); + padding: 0 0.4rem; +} + +.json { + grid-column: 1 / -1; + margin: 0.4rem 0 0; + padding: 0.6rem; + background: var(--surface-raised); + border: 1px solid var(--border-subtle); + border-radius: var(--radius-md); + font-family: var(--font-mono); + font-size: 0.78rem; + overflow-x: auto; +} + +.json.raw { + max-height: 30rem; + overflow: auto; +} + +.error { + color: var(--danger); + font-size: 0.9rem; +} + +.hint { + color: var(--text-secondary); + font-size: 0.9rem; +} + +@media (max-width: 640px) { + .evt { + grid-template-columns: 4.5rem 1fr auto; + } + .evt .summary { + grid-column: 1 / -1; + } +} diff --git a/demos/agent-events-inspector/app/layout.tsx b/demos/agent-events-inspector/app/layout.tsx new file mode 100644 index 0000000..4c8fea7 --- /dev/null +++ b/demos/agent-events-inspector/app/layout.tsx @@ -0,0 +1,21 @@ +import type { Metadata } from "next"; +import type { ReactNode } from "react"; +import Script from "next/script"; +import "./globals.css"; + +export const metadata: Metadata = { + title: "Voice agent events inspector", + description: + "Replay a sample realtime event stream or inspect a live Speechify Voice Agent conversation in a debug timeline.", +}; + +export default function RootLayout({ children }: { children: ReactNode }) { + return ( + + + + @@ -368,7 +368,7 @@

FAQ