Health Care Consultant

Health Care Consultant Configuration

These examples use the tools registry: tools are created once at /v2/tools and attached to the PAL. Tools here use the default app-message delivery, so calls arrive as conversation.tool_call events for your frontend to handle.

General Doctor
Dermatologist

The General Doctor uses a single LLM tool that looks up cures for a named disease.

get_cures (LLM tool)

{
  "name": "get_cures",
  "description": "Fetch cures for the specified disease.",
  "parameters": {
    "type": "object",
    "required": ["disease"],
    "properties": {
      "disease": {
        "type": "string",
        "description": "The disease the user wants to cure."
      }
    }
  },
  "origin": "llm"
}

The PAL sets the models and no longer defines tools inline:

PAL configuration

{
  "pal_name": "Personal Doctor",
  "pipeline_mode": "full",
  "system_prompt": "You are a friendly Personal Doctor who knows cures to all diseases. In this call, users want to know the cure for their illness.",
  "context": "Users may ask questions like \"What is the cure to X?\" You should acknowledge the disease and call the get_cures tool with the disease name.",
  "default_face_id": "r90bbd427f71",
  "layers": {
    "tts": {
      "tts_engine": "cartesia",
      "tts_emotion_control": true
    },
    "llm": {
      "model": "tavus-gemma-4",
      "speculative_inference": true
    },
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "high",
      "pal_interruptibility": "low"
    }
  }
}

This PAL is designed to act as a friendly virtual doctor, offering quick answers to user health inquiries. It includes:

PAL Identity: A helpful and knowledgeable “Health Care” assistant who can provide medicines to cure various diseases.
Full Pipeline Mode: Enables the full Tavus conversational pipeline, including STT, LLM, and TTS.
System Prompt: instructs the PAL to behave as a trusted medical advisor. It ensures the PAL understands its role in responding to disease-related questions and calling the appropriate tool to provide answers.
Context: Clarifies expected user inputs (e.g., “What is the cure to X?”) and defines how the PAL should interpret and respond - by acknowledging the illness and triggering the attached get_cures tool with the specified disease name.
Model Layers:
- LLM Configuration: Uses the tavus-gemma-4 model with speculative inference. The attached get_cures tool accepts a single string parameter (disease) and is called when disease-related queries are detected.
- TTS Layer: Employs the cartesia voice engine with emotion control.
- STT Layer: Uses tavus-advanced engine with smart turn detection for seamless real-time conversations.

The Dermatologist uses an LLM tool that looks up skin-condition cures, plus a vision tool that fires when Raven sees acne.

get_skin_cures (LLM tool)

{
  "name": "get_skin_cures",
  "description": "Record the user's disease and return cures for the specified skin condition.",
  "parameters": {
    "type": "object",
    "required": ["disease"],
    "properties": {
      "disease": {
        "type": "string",
        "description": "The disease which the user wanted to know how to cure"
      }
    }
  },
  "origin": "llm"
}

acne_detected (vision tool)

{
  "name": "acne_detected",
  "description": "Trigger when acne is clearly visible on the user's face with high confidence.",
  "parameters": {
    "type": "object",
    "required": ["have_acne"],
    "properties": {
      "have_acne": {
        "type": "boolean",
        "description": "is acne detected on user's face?"
      }
    }
  },
  "origin": "vision"
}

The PAL sets the models and ambient queries; the tools are attached separately:

PAL configuration

{
  "pal_name": "Personal Skin Doctor",
  "pipeline_mode": "full",
  "system_prompt": "You are a friendly Personal Skin Doctor who know cures to all the disease in the world. In this call, users want to know what are the cures to the user's disease",
  "context": "User want to know what is the cure to his/her skin problem. When a user says \"What is the cure to X\" or \"What is the solution to X\", you should acknowledge their disease and use the get_skin_cures tool to return the cures of the disease's cures based on user request",
  "default_face_id": "r90bbd427f71",
  "layers": {
    "tts": {
      "tts_engine": "cartesia",
      "tts_emotion_control": true
    },
    "llm": {
      "model": "tavus-gemma-4",
      "speculative_inference": true
    },
    "perception": {
      "perception_model": "raven-1",
      "ambient_awareness_queries": [
        "Is the user have an acne in his or her face?",
        "Does the user appear distressed or uncomfortable?"
      ]
    },
    "conversational_flow": {
      "turn_detection_model": "sparrow-1",
      "turn_taking_patience": "high",
      "pal_interruptibility": "low"
    }
  }
}

This PAL acts as a virtual skin care specialist. It offers users professional yet warm advice for treating skin-related concerns and leverages both conversational understanding and visual perception. It includes:

PAL Identity: A friendly and knowledgeable “Personal Skin Doctor” who helps users find cures for skin conditions.
Full Pipeline Mode: Enables the full Tavus conversational pipeline, including Perception, STT, LLM, and TTS.
System Prompt: Directs the PAL to behave like a helpful skin doctor, answering cure-related questions clearly and empathetically.
Context: Guides the PAL to respond when users ask questions like “What is the cure to X” or “What is the solution to X.” The AI is instructed to extract the disease name and call the attached get_skin_cures tool to fetch a relevant response.
Model Layers
- LLM Configuration: Uses the tavus-gemma-4 model with speculative inference. The attached get_skin_cures tool takes a disease input to provide specific treatment guidance.
- Perception Configuration: Integrates the raven-1 model to visually assess the user’s face. It runs ambient queries like:
  - “Does the user have acne on their face?”
  - “Does the user appear distressed or uncomfortable?”
  When acne is detected, the attached acne_detected vision tool fires, reporting visual findings using a boolean have_acne parameter.
- TTS Layer: Employs the cartesia voice engine with emotion control.
- Conversational Flow Layer: Uses sparrow-1 turn detection model with high turn-taking patience to avoid interrupting patients and very low face interruptibility for careful, uninterrupted responses.

Create a Conversation with the Health Care Consultant

Step 1: Create the tools

Create each tool at /v2/tools. The response returns a tool_id you’ll attach to the PAL in Step 3.

curl --request POST \
  --url https://tavusapi.com/v2/tools \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "get_cures",
    "description": "Fetch cures for the specified disease.",
    "parameters": {
      "type": "object",
      "required": ["disease"],
      "properties": {
        "disease": {
          "type": "string",
          "description": "The disease the user wants to cure."
        }
      }
    },
    "origin": "llm"
  }'

curl --request POST \
  --url https://tavusapi.com/v2/tools \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "get_skin_cures",
    "description": "Record the user'\''s disease and return cures for the specified skin condition.",
    "parameters": {
      "type": "object",
      "required": ["disease"],
      "properties": {
        "disease": {
          "type": "string",
          "description": "The disease which the user wanted to know how to cure"
        }
      }
    },
    "origin": "llm"
  }'

curl --request POST \
  --url https://tavusapi.com/v2/tools \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "acne_detected",
    "description": "Trigger when acne is clearly visible on the user'\''s face with high confidence.",
    "parameters": {
      "type": "object",
      "required": ["have_acne"],
      "properties": {
        "have_acne": {
          "type": "boolean",
          "description": "is acne detected on user'\''s face?"
        }
      }
    },
    "origin": "vision"
  }'

Step 2: Create the PAL

Create the PAL using the following request. There are no inline tools - they’re attached in the next step.

curl --request POST \
  --url https://tavusapi.com/v2/pals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "pal_name": "Personal Doctor",
    "pipeline_mode": "full",
    "system_prompt": "You are a friendly Personal Doctor who knows cures to all diseases. In this call, users want to know the cure for their illness.",
    "context": "Users may ask questions like \"What is the cure to X?\" You should acknowledge the disease and call the get_cures tool with the disease name.",
    "default_face_id": "r90bbd427f71",
    "layers": {
      "tts": {
        "tts_engine": "cartesia",
        "tts_emotion_control": true
      },
      "llm": {
        "model": "tavus-gemma-4",
        "speculative_inference": true
      },
      "conversational_flow": {
        "turn_detection_model": "sparrow-1",
        "turn_taking_patience": "high",
        "pal_interruptibility": "low"
      }
    }
  }'

curl --request POST \
  --url https://tavusapi.com/v2/pals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "pal_name": "Personal Skin Doctor",
    "pipeline_mode": "full",
    "system_prompt": "You are a friendly Personal Skin Doctor who know cures to all the disease in the world. In this call, users want to know what are the cures to the user'\''s disease",
    "context": "User want to know what is the cure to his/her skin problem. When a user says \"What is the cure to X\" or \"What is the solution to X\", you should acknowledge their disease and use the get_skin_cures tool to return the cures of the disease'\''s cures based on user request",
    "default_face_id": "r90bbd427f71",
    "layers": {
      "tts": {
        "tts_engine": "cartesia",
        "tts_emotion_control": true
      },
      "llm": {
        "model": "tavus-gemma-4",
        "speculative_inference": true
      },
      "perception": {
        "perception_model": "raven-1",
        "ambient_awareness_queries": [
          "Is the user have an acne in his or her face?",
          "Does the user appear distressed or uncomfortable?"
        ]
      },
      "conversational_flow": {
        "turn_detection_model": "sparrow-1",
        "turn_taking_patience": "high",
        "pal_interruptibility": "low"
      }
    }
  }'

Replace <api-key> with your actual API key. You can generate one in the PAL Maker.

Step 3: Attach the tools to the PAL

Attach each variant’s tools to its PAL by tool_id. Vision tools require perception_model: "raven-1" on the PAL, which the Dermatologist configuration already sets.

curl --request POST \
  --url https://tavusapi.com/v2/pals/<health_care_pal_id>/tools \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "tool_ids": ["<get_cures_tool_id>"]
  }'

curl --request POST \
  --url https://tavusapi.com/v2/pals/<health_care_pal_id>/tools \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "tool_ids": ["<get_skin_cures_tool_id>", "<acne_detected_tool_id>"]
  }'

Step 4: Create a Conversation

Create a conversation using the following request:

cURL

curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
  "pal_id": "<health_care_pal_id>"
}'

Replace <api_key> with your actual API key.
Replace <health_care_pal_id> with the ID of the PAL configured as either a General Doctor or a Dermatologist.

Step 5: Join the Conversation

Click the link in the conversation_url field to join the conversation:

{
  "conversation_id": "c7f3fc6d799f",
  "conversation_name": "New Conversation 1747719531479",
  "conversation_url": "<conversation_link>",
  "status": "active",
  "callback_url": "",
  "created_at": "2025-05-20T05:38:51.501467Z"
}

Getting Started

Build

Deploy

Debug

Guides

Resources

Health Care Consultant