description: A voice agent that conducts a spoken interview over the phone. Binds an instruction prompt to the questionnaires it can administer, so a Task focused on one of those questionnaires can find its agent without referencing voice at all. Speech and language models are optional overrides on top of the deployment defaults.
package_name: io.health-samurai.sdc.r4b
derivation: specialization
name: SDCVoiceAgent
type: SDCVoiceAgent
elements:
  description: {type: markdown, short: What this agent is for., index: 4}
  questionnaire: {type: canonical, short: Questionnaires this agent administers. Array order is interview order; a Task focused on any of these can be routed here. At least one is required — an agent without a questionnaire has nothing to ask., array: true, min: 1, index: 6}
  name: {type: string, short: Machine-readable name., index: 1}
  stt:
    type: Reference
    short: Speech-to-text model, as a Device. Falls back to the deployment default.
    refers: ['http://hl7.org/fhir/StructureDefinition/Device']
    index: 11
  title: {type: string, short: 'Human-readable name, shown when picking an agent.', index: 2}
  maxAttempts: {type: integer, short: How many times to redial when nobody picks up. Defaults to a single attempt., index: 15}
  extractorLlm:
    type: Reference
    short: Model that turns the finished transcript into answers, as a Device. A separate call from the conversation, so it can be a cheaper or stricter model; falls back to llm.
    refers: ['http://hl7.org/fhir/StructureDefinition/Device']
    index: 14
  prompt: {type: canonical, short: 'SDCVoicePrompt lineage url. Version-less: the active revision is resolved when the call is placed.', index: 5}
  llm:
    type: Reference
    short: Language model, as a Device. Falls back to the deployment default.
    refers: ['http://hl7.org/fhir/StructureDefinition/Device']
    index: 13
  status:
    type: code
    short: draft | active | retired. Only active agents are selected for calls.
    constraint:
      voice-agent-status-1: {human: 'Status must be one of: draft, active, retired', severity: error, expression: $this in ('draft' | 'active' | 'retired')}
    index: 3
  maxDurationMinutes: {type: integer, short: Hard cap on a single conversation; the call is hung up when it is reached., index: 17}
  url: {type: uri, short: Canonical identity of this agent., index: 0}
  retryDelayMinutes: {type: integer, short: 'Gap between redial attempts, in minutes.', index: 16}
  context:
    type: BackboneElement
    short: Resources this agent needs to hold the conversation. Declared here, supplied to $call, and validated against this list before the call is placed — the same contract as sdc-questionnaire-launchContext.
    array: true
    index: 7
    elements:
      name: {type: code, short: 'What this slot is called when passed to $call and when rendered into the prompt, e.g. patient, appointment, referrer. Distinguishes two slots of the same resource type.', index: 8}
      type: {type: code, short: 'Resource type accepted in this slot, e.g. Patient, Appointment, Coverage. Any FHIR resource type is allowed.', index: 9}
      label: {type: string, short: Human-readable name for the picker in the UI., index: 10}
    required: [name, type]
  tts:
    type: Reference
    short: Text-to-speech voice, as a Device. Falls back to the deployment default.
    refers: ['http://hl7.org/fhir/StructureDefinition/Device']
    index: 12
package_version: 0.2608.0
class: resource
kind: resource
url: http://health-samurai.io/fhir/sdc/StructureDefinition/SDCVoiceAgent
base: http://hl7.org/fhir/StructureDefinition/DomainResource
version: 0.2608.0
required: [status, prompt, questionnaire]