Usage¶
home-assistant-agent exposes the same capability three ways: as MCP tools an
agent calls, as a Python API (HomeAssistantApi) the operator import, and as a CLI.
The full tool surface and architecture are described in Overview.
As an MCP server¶
Once deployed, the server registers one typed tool per Home Assistant
client operation, named home_assistant_<operation> (for example
home_assistant_get_state, home_assistant_call_service, home_assistant_get_history),
plus the home_ingest_* KG tools. Arguments are typed tool parameters; there is no
action router and no params_json string.
Example agent prompts that map onto these tools:
- "Turn on the living-room lights" ->
home_assistant_call_service(light.turn_on) - "What was the thermostat set to yesterday afternoon?" ->
home_assistant_get_history - "List every calendar event scheduled for tomorrow" →
calendar
As a Python API¶
HomeAssistantApi is a unified REST + WebSocket client. Built it directly, or
build one straight from the environment with get_client().
from home_assistant_agent.api_client import HomeAssistantApi
api = HomeAssistantApi(
base_url="http://your-home-assistant:8123",
token="your_long_lived_access_token",
)
# Reads
config = api.get_config() # instance configuration
states = api.get_states() # all entity states
one = api.get_state("light.living_room") # a single entity
services = api.get_services() # available service domains
calendars = api.get_calendars() # configured calendars
log = api.get_error_log() # the Home Assistant error log
Build a client straight from the environment:
from home_assistant_agent.auth import get_client
api = get_client() # reads HOME_ASSISTANT_* from the environment / .env
Actions¶
State changes and service calls go through the same client:
# Set an entity state
api.update_state("input_boolean.guest_mode", "on")
# Call a service
api.call_service("light", "turn_on", {"entity_id": "light.living_room"})
# Fire an event
api.fire_event("custom_event", {"source": "home-assistant-agent"})
As a CLI¶
Both entry points are command-line programs.
Both honor the HOME_ASSISTANT_* environment variables documented in
Deployment and in
.env.example.