roark

Use to define who calls the agent (personas) and what they do (customer flows) in Roark: pick from the system persona library or create a custom persona (voice, language, speech and behavioral profile), and author a flow with a happy path and edge cases. Use when a run plan needs a persona or flow that does not exist yet, or someone asks to design test conversations.

Use to author a SCRIPTED Roark customer flow: a conversation graph that walks an agent through an exact sequence, including IVR menu navigation and DTMF keypad entry (touch tones like "1w2w3#"), silence, voicemail, and branch/merge routing. Use whenever a test needs deterministic routing, an IVR/phone-tree, pressing digits, or a precise turn-by-turn script rather than an improvised conversation.

Use to configure and start a Roark simulation that tests a voice or chat agent: choose a testing goal (benchmark, flow adherence, red-teaming, knowledge grounding, tool-call accuracy, voicemail, load, health check), select which customer flows and how much of each to run, set iteration and concurrency, attach the metrics that grade it, preview the call count, and run. Use whenever someone asks to run a simulation, test their agent, or set up a run plan in Roark.

Use to choose or create the metrics that grade a Roark simulation or live calls: attach built-in metrics by slug, add pass/fail checks to gate a run, or author a custom metric (LLM judge, formula, or temporal pattern) with client.metric.createDefinition. Use whenever someone asks what to measure, how to score their voice agent, how to add a threshold, or how to write a custom Roark metric.

Use to configure how Roark places OUTBOUND simulated calls: define the HTTP request Roark sends to your telephony/agent platform to trigger it to dial the simulated caller. Covers httpRequestDefinition (url, method, headers, body template with placeholders, signing secret). Use when setting up outbound simulations, when a run needs Roark to kick off the call by hitting your API, or when outbound calls are not dialing.

Use to gate a deploy or CI pipeline on a Roark simulation: start a run, wait for it to finish, check whether the pass/fail metrics passed, and turn that into a green/red result (exit code). Use when someone wants Roark to block a release, run in CI, or answer "did this build pass its voice tests".

Use to import an already-happened real call into Roark for analysis, and to read calls back: create a call from a recording URL (plus optional transcript, tool invocations, agent and customer linkage), then list, fetch, and read its transcript, metrics, and sentiment. Use when someone wants to analyze existing production recordings, bring calls from another platform into Roark, or query calls that already exist.

Use to manage Roark resources declaratively from a repo instead of imperative create/update calls: define agents, personas, flows, custom metrics, and collectors as a bundle, preview changes with config.diff, and reconcile with config.apply. Use when someone wants Roark config in version control, a repeatable/idempotent setup, or to sync a whole project's resources at once.

Use to manage saved Roark run plans as reusable test suites: list and search existing plans, read one back, update its flows/metrics/settings, promote a one-off run into a saved plan, re-run a plan by id, and delete a plan. Use when someone wants a named regression suite, to change what an existing suite tests, to find a previous plan, or to re-run the same tests.

Use to grade REAL production calls and chats with Roark metrics (not simulations): create a metric policy that auto-evaluates matching live conversations, or run a one-off collection job to backfill metrics over a set of existing calls/chats. Use when someone wants continuous quality monitoring of production traffic, to score live calls, to backfill a new metric over past conversations, or to filter which live calls get evaluated.

Use to read the results of a Roark simulation run: poll a run's status, list its calls, and read each call's metric scores (with pass/fail) and transcript. Use when someone asks how a run did, whether it passed, why a metric failed, or wants to inspect a specific simulated call.

Use to register the agent under test in Roark and give it an endpoint Roark can reach: create the agent, then add a phone endpoint (E.164) with a call direction. Also covers non-phone transports (WebSocket, LiveKit, ElevenLabs, Kore, Google CES, Daily), which cannot be created through this API. Use when setting up a new agent, or when a run plan needs an agentEndpoint id that does not exist yet.

Canonical definitions of the Roark domain objects: personas, customer flows, scripted flows, run plans, templates and metrics. Read a concept when you need to know what a Roark object IS, which fields it has, or how it relates to the others, rather than how to call the API for it. The other Roark skills reference these files instead of restating them.

Use when testing, simulating, or evaluating a voice or chat AI agent with Roark, or when the Roark MCP is connected. Covers how the Roark MCP works (you write @roarkanalytics/sdk snippets, you do not call one tool per endpoint), how to authenticate, the core testing loop (register agent -> personas and flows -> run plan -> run -> metrics -> results), and which companion skill to use for each step. Read this first.

Use to subscribe to Roark events over HTTP webhooks instead of polling: get notified when a simulation run or job finishes, a call or chat analysis completes, a metric collection job finishes, or an issue opens/resolves. Register, list, and delete webhook subscriptions, and verify their signatures. Use when someone wants event-driven notifications, to react to a run finishing, or to avoid long polling in CI.