Run tools

Run tools take a published blueprint and put it in front of a real participant. A channel describes how the interview is delivered (WebRTC voice, telephony, chat, custom); an interview run is a single conversation between the agent and one participant. Use these tools to create, inspect, list, and cancel runs.

create_channel

Signature

{
  type: "webrtc_voice" | "telephony" | "chat" | "custom";
  name: string;
  settings?: {
    recording?: boolean;
    max_duration_s?: number;
    idle_timeout_s?: number;
  };
  metadata?: Record<string, unknown>;
}

When to use

Create a channel once per delivery surface — typically one chat channel and one voice channel per environment. Reuse the channel ID across many runs.

Natural-language example

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_channel",
    "arguments": {
      "type": "webrtc_voice",
      "name": "Production voice",
      "settings": { "recording": true, "max_duration_s": 1200 }
    }
  }
}

Common errors

• 400 invalid_request — type outside the allowed enum.
• 401 unauthorized — missing API key.

create_interview_run

Signature

{
  blueprint_id: string;
  channel_id?: string;
  connector_id?: string;
  participant?: {
    external_id?: string;
    name?: string;
    email?: string;
    metadata?: Record<string, unknown>;
  };
  metadata?: Record<string, unknown>;
}

Provide either channel_id (chat/voice) or connector_id (external platform like Google Meet, Zoom, Teams) — not both.

When to use

Kick off a single interview. The blueprint must be published. The returned run object contains the join URL or session details for the participant.

Natural-language example

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_interview_run",
    "arguments": {
      "blueprint_id": "bp_7f3a_abc",
      "channel_id": "chn_voice",
      "participant": { "email": "jane@example.com", "name": "Jane Doe" }
    }
  }
}

Common errors

• 400 invalid_request — neither channel_id nor connector_id provided, or both provided.
• 409 conflict — blueprint is not published.
• 404 not_found — blueprint_id, channel_id, or connector_id does not exist.

get_interview_run

Signature

{
  run_id: string;
  expand?: Array<
    | "blueprint" | "agent" | "channel" | "connector"
    | "transcript" | "responses" | "analysis"
  >;
}

When to use

Poll for status (pending, in_progress, completed, cancelled, failed) or fetch a run with related objects inlined to avoid follow-up calls.

Natural-language example

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_interview_run",
    "arguments": { "run_id": "run_xyz789", "expand": ["transcript", "analysis"] }
  }
}

Common errors

• 404 not_found — wrong ID or run belongs to another organization.
• 400 invalid_request — expand value outside the allowed enum.

list_interview_runs

Signature

{
  limit?: number;
  starting_after?: string;
  blueprint_id?: string;
}

When to use

List recent runs across the workspace, or filter by blueprint_id to see all runs for a specific study.

Natural-language example

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_interview_runs",
    "arguments": { "blueprint_id": "bp_7f3a_abc", "limit": 20 }
  }
}

Common errors

• 400 invalid_request — limit outside 1–100.
• 400 invalid_request — starting_after cursor malformed.

cancel_interview_run

Signature

{ run_id: string }

When to use

Stop a run that is in progress or pending. Cancellation is terminal — you can't resume.

Natural-language example

Raw tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "cancel_interview_run", "arguments": { "run_id": "run_xyz789" } }
}

Common errors

• 409 conflict — run is already in a terminal state (completed, cancelled, failed).
• 404 not_found — wrong run ID.

Related tools

Pair with publish_blueprint before creating a run, launch_interview to create a connector and run together, or get_interview_summary once the run completes.