ha-text-ai/RESPONSE_VARIABLE_EXAMPLE.md

Using response_variable with HA Text AI

After updating the HA Text AI integration, it now supports using the response_variable parameter in Home Assistant scripts and automations.

What Changed

• Added response schema support in the ha_text_ai.ask_question service
• Service is now correctly registered with supports_response=True flag
• You can now use response_variable to capture AI response in a variable

Example Usage in Script

action: ha_text_ai.ask_question
data:
  context_messages: 0
  temperature: 0.7
  max_tokens: 1000
  instance: sensor.ha_text_ai_gemini
  question: "What time is it?"
response_variable: ai_response

Example Usage in Automation

alias: "Get AI Response"
trigger:
  - platform: state
    entity_id: input_boolean.ask_ai
    to: "on"
action:
  - action: ha_text_ai.ask_question
    data:
      instance: sensor.ha_text_ai_gemini
      question: "What's the current weather?"
      temperature: 0.7
      max_tokens: 500
    response_variable: weather_response
  
  - action: notify.persistent_notification
    data:
      title: "AI Response"
      message: "{{ weather_response.response_text }}"

Available Fields in response_variable

When you use response_variable, you will receive an object with the following fields:

• response_text (string) - The AI response text
• tokens_used (integer) - Total number of tokens used
• prompt_tokens (integer) - Number of tokens in the prompt
• completion_tokens (integer) - Number of tokens in the completion
• model_used (string) - The AI model that was used for the response
• instance (string) - The instance name that was used
• question (string) - The original question that was asked
• timestamp (string) - ISO timestamp when the response was generated
• success (boolean) - Whether the request was successful
• error (string) - Error message if the request failed

Example Using Response Fields

action:
  - action: ha_text_ai.ask_question
    data:
      instance: sensor.ha_text_ai_gemini
      question: "Tell me a joke"
    response_variable: joke_response
  
  - condition: template
    value_template: "{{ joke_response.success }}"
  
  - action: input_text.set_value
    target:
      entity_id: input_text.last_ai_response
    data:
      value: "{{ joke_response.response_text }}"
  
  - action: input_number.set_value
    target:
      entity_id: input_number.tokens_used
    data:
      value: "{{ joke_response.tokens_used }}"

Error Handling

action:
  - action: ha_text_ai.ask_question
    data:
      instance: sensor.ha_text_ai_gemini
      question: "Test question"
    response_variable: ai_result
  
  - choose:
      - conditions:
          - condition: template
            value_template: "{{ ai_result.success }}"
        sequence:
          - action: notify.mobile_app_phone
            data:
              title: "AI Response"
              message: "{{ ai_result.response_text }}"
      - conditions:
          - condition: template
            value_template: "{{ not ai_result.success }}"
        sequence:
          - action: notify.mobile_app_phone
            data:
              title: "AI Error"
              message: "Error: {{ ai_result.error }}"

Migration from Old Approach

Old method (without response_variable):

# Ask question
- action: ha_text_ai.ask_question
  data:
    instance: sensor.ha_text_ai_gemini
    question: "Hello!"

# Wait and read response from sensor
- delay: 00:00:05
- action: notify.mobile_app_phone
  data:
    message: "{{ states('sensor.ha_text_ai_gemini') }}"

New method (with response_variable):

# Ask question and get response immediately
- action: ha_text_ai.ask_question
  data:
    instance: sensor.ha_text_ai_gemini
    question: "Hello!"
  response_variable: greeting_response

- action: notify.mobile_app_phone
  data:
    message: "{{ greeting_response.response_text }}"

The new approach is more reliable as it doesn't require waiting and reading from the sensor.