API Reference

API Reference

Quick reference for Home Agent services, events, and tools.

Core Services

Key Events

Built-in Tools

Note: query_external_llm only available when external LLM is enabled.

Quick Examples

Service Call Example

Process a conversation:

service: home_agent.process
data:
  text: "Turn on the living room lights and set them to 50% brightness"
  conversation_id: "main_conversation"

Search memories:

service: home_agent.search_memories
data:
  query: "bedroom temperature preferences"
  limit: 10
  min_importance: 0.5

Event Automation Example

Track token usage:

automation:
  - alias: "Track Token Usage"
    trigger:
      - platform: event
        event_type: home_agent.conversation.finished
    action:
      - service: input_number.set_value
        target:
          entity_id: input_number.total_tokens_used
        data:
          value: >
            {{ states('input_number.total_tokens_used') | int +
               trigger.event.data.tokens.total | int }}

Alert on errors:

automation:
  - alias: "Alert on Home Agent Errors"
    trigger:
      - platform: event
        event_type: home_agent.error
    action:
      - service: notify.admin
        data:
          title: "Home Agent Error"
          message: >
            Type: {{ trigger.event.data.error_type }}
            Message: {{ trigger.event.data.error_message }}

Tool Usage Example

The LLM automatically calls these tools, but you can test them manually:

Control a device:

service: home_agent.execute_tool
data:
  tool_name: ha_control
  parameters:
    action: turn_on
    entity_id: light.living_room
    parameters:
      brightness: 128

Query entity state:

service: home_agent.execute_tool
data:
  tool_name: ha_query
  parameters:
    entity_id: sensor.living_room_temperature

Query with history:

service: home_agent.execute_tool
data:
  tool_name: ha_query
  parameters:
    entity_id: sensor.temperature
    history:
      duration: "24h"
      aggregate: "avg"

Service Details

home_agent.process

Process a conversation message.

Parameters:

• text (string, required): The message to process
• conversation_id (string, optional): ID for history tracking
• user_id (string, optional): User ID for the conversation

Example:

service: home_agent.process
data:
  text: "What's the temperature in the living room?"
  conversation_id: "main_conversation"

home_agent.add_memory

Manually store a memory.

Parameters:

• content (text, required): The memory content
• type (select, optional): Memory type (fact, preference, context, event)
• importance (number 0.0-1.0, optional): Importance score

Example:

service: home_agent.add_memory
data:
  content: "User prefers bedroom temperature at 68°F for sleeping"
  type: preference
  importance: 0.8

home_agent.clear_history

Clear conversation history.

Parameters:

• conversation_id (string, optional): Specific conversation to clear (omit to clear all)

Examples:

# Clear specific conversation
service: home_agent.clear_history
data:
  conversation_id: "living_room_conversation"

# Clear all conversations
service: home_agent.clear_history

Event Details

home_agent.conversation.finished

Triggered when a conversation completes.

Key Data Fields:

{
  "conversation_id": "main_conversation",
  "tool_calls": 3,
  "tool_breakdown": {
    "ha_query": 2,
    "ha_control": 1
  },
  "tokens": {
    "prompt": 150,
    "completion": 75,
    "total": 225
  },
  "duration_ms": 2345,
  "performance": {
    "llm_latency_ms": 1200,
    "tool_latency_ms": 450,
    "context_latency_ms": 150
  }
}

home_agent.tool.executed

Triggered after each tool execution.

Key Data Fields:

{
  "tool_name": "ha_control",
  "parameters": {
    "action": "turn_on",
    "entity_id": "light.living_room",
    "parameters": {
      "brightness": 128
    }
  },
  "result": {
    "success": true,
    "entity_id": "light.living_room",
    "new_state": "on"
  },
  "success": true,
  "duration_ms": 45.2,
  "conversation_id": "main_conversation"
}

home_agent.memory.extracted

Triggered when memories are extracted.

Key Data Fields:

{
  "conversation_id": "main_conversation",
  "memories_extracted": 3,
  "extraction_llm": "external",
  "timestamp": "2024-01-15T10:30:00"
}

Tool Details

ha_control

Control Home Assistant devices.

Actions:

• turn_on - Turn entity on
• turn_off - Turn entity off
• toggle - Toggle entity state
• set_value - Set specific value

Common Parameters:

• Lights: brightness (0-255), rgb_color ([R,G,B])
• Climate: temperature, hvac_mode (heat/cool/auto/off)
• Covers: position (0-100)
• Media: volume_level (0.0-1.0)

Examples:

// Turn on light
{
  "action": "turn_on",
  "entity_id": "light.living_room"
}

// Turn on light with brightness
{
  "action": "turn_on",
  "entity_id": "light.living_room",
  "parameters": {
    "brightness": 128
  }
}

// Set thermostat
{
  "action": "set_value",
  "entity_id": "climate.thermostat",
  "parameters": {
    "temperature": 72
  }
}

ha_query

Get entity state and attributes.

Parameters:

• entity_id (required): Entity to query (supports wildcards like light.*)
• attributes (optional): Specific attributes to retrieve
• history (optional): Retrieve historical data
  • duration: Time range (e.g., "1h", "24h", "7d")
  • aggregate: Aggregation method (avg, min, max, sum, count)

Examples:

// Query single entity
{
  "entity_id": "sensor.living_room_temperature"
}

// Query with wildcard
{
  "entity_id": "light.*"
}

// Query with history
{
  "entity_id": "sensor.temperature",
  "history": {
    "duration": "24h",
    "aggregate": "avg"
  }
}

query_external_llm

Query external LLM for complex analysis (only available when external LLM is enabled).

Parameters:

• prompt (required): Question or prompt to send
• context (optional): Additional context (sensor data, tool results, etc.)

Examples:

// Simple query
{
  "prompt": "Should I adjust the thermostat based on current conditions?"
}

// Query with context
{
  "prompt": "Analyze this energy usage data and suggest optimizations",
  "context": {
    "current_temperature": "68°F",
    "energy_usage_kwh": 45.2,
    "time_period": "last 24 hours"
  }
}

Need More Details?

See the Complete Reference for comprehensive API documentation with all services, events, and tools.