Functions Overview

Learn about function types and how to extend AI capabilities

Functions are the core mechanism for extending your AI assistant’s capabilities. Each function defines what the AI can do and how it executes actions.

Function Structure

Every function consists of two parts:

Function Definition

- spec:
    name: function_name
    description: What this function does
    parameters:
      type: object
      properties:
        param_name:
          type: string
          description: Parameter description
  function:
    type: function_type
    # Type-specific configuration

Specification (spec)

The spec follows OpenAI’s function schema format:

• name: Function identifier (used by AI to call the function)
• description: Clear explanation of what the function does
• parameters: JSON schema defining expected parameters

Write clear, detailed descriptions. The AI uses these to decide when and how to call functions.

Function Implementation

The function section defines how to execute the function:

• type: Function type (see below)
• Additional configuration specific to the function type

Function Types

Native

Built-in functions provided by the component

Template

Return dynamic values using Jinja2 templates

Script

Execute sequences of Home Assistant services

REST

Fetch data from external REST APIs

Scrape

Extract data from web pages

Composite

Chain multiple function types together

SQLite

Query Home Assistant’s database

Bash

Execute shell commands with security controls

Read File

Read file contents safely with path restrictions

Write File

Write content to files safely with path restrictions

Edit File

Safely edit files with find-and-replace operations

Reserved Parameters

Delay Parameter

Add a delay to execute functions in the background after a specified time:

spec:
  name: delayed_action
  description: Execute action after a delay
  parameters:
    type: object
    properties:
      # Your regular parameters here
      delay:
        type: object
        description: Time to wait before execution
        properties:
          hours:
            type: integer
            minimum: 0
          minutes:
            type: integer
            minimum: 0
          seconds:
            type: integer
            minimum: 0

Default Functions

Extended OpenAI Conversation includes this default function:

execute_services

- spec:
    name: execute_services
    description: Use this function to execute service of devices in Home Assistant.
    parameters:
      type: object
      properties:
        list:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
                description: The domain of the service
              service:
                type: string
                description: The service to be called
              service_data:
                type: object
                description: The service data object to indicate what to control.
                properties:
                  entity_id:
                    type: string
                    description: The entity_id retrieved from available devices.
                required:
                - entity_id
            required:
            - domain
            - service
            - service_data
  function:
    type: native
    name: execute_service

This function allows the AI to control any exposed Home Assistant entity.

Adding Custom Functions

Add functions through the Options configuration:

1. Open Options

   Navigate to Settings > Voice Assistants > Edit Assistant > Options

2. Edit Functions

   Scroll to the “Functions” field

3. Add YAML

   Paste your function definition in YAML format

4. Save

   Click “Submit” to apply changes

Best Practices

Clear descriptions

Write detailed descriptions that explain exactly what the function does and when to use it. The AI relies on these descriptions to choose the right function.

✅ Good: “Get the current weather and forecast for a specific location using the weather entity”

❌ Bad: “Get weather”

Specific parameters

Define all required parameters with clear descriptions and appropriate types.

properties:
  entity_id:
    type: string
    description: The entity_id retrieved from available devices. Must start with domain, followed by dot character.

Test thoroughly

Test each function with various inputs before deploying to production. Check edge cases and error handling.

Use appropriate types

Choose the simplest function type that meets your needs. Don’t use composite functions when a template would suffice.

Next Steps

Native Functions

Built-in functions

Template Functions

Dynamic templates

Script Functions

Service sequences