Coming Soon — This feature is currently in development and not yet available. This guide is a preview of what's coming.

Custom functions let your agents perform actions beyond answering from the knowledge base. Use them to search and return context, call external APIs, send emails, escalate to a human, or run any logic you define. You manage functions from the Edit Functions screen (Agents, Prompts & Functions → Functions).

How It Works

Functions are written in AirScript, a reduced-feature-set version of Python. Each function must define a single entry point:

async def run(air):

The air object is passed in by the system and provides a safe API for interacting with the conversation, the knowledge base, email, and HTTP. You cannot import arbitrary modules or access the file system — only the operations exposed on air and the built-in json module are available. This keeps functions secure and predictable.

When the AI decides it needs to use a function (for example, to search or send an email), it calls your run(air) with arguments derived from the conversation. Your code runs, then control returns to the agent so it can respond to the user.

Your Functions vs Global Functions

On the Edit Functions screen you will see two lists:

• Your Functions — Functions you have created or customised for your service. You can edit and delete these.
• Global Functions — Functions provided by the platform for all customers (e.g. get_weather, escalate_to_human). You can open and customise them; saving creates a copy in Your Functions. You cannot delete the global originals.

Both Your Functions and Global Functions can be used by your agents. If you have a customised copy of a function that also exists globally, your copy takes priority. This is the same copy-on-write pattern used for prompts.

Function Files

Each function consists of two files with the same base name:

1. A .py file — The AirScript code. Must define async def run(air):. Use air.args to read arguments and air methods to search, reply, send email, etc. See AirScript Functions for full details.
2. A .function file — A JSON schema that describes the function to the LLM: its name, description, and parameters. The AI uses this to decide when to call the function and what arguments to pass.

Example .function file for a weather function:

{
  "type": "function",
  "name": "get_weather",
  "description": "Get the current weather for a location.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city or location to get the weather for."
      }
    },
    "required": ["location"],
    "additionalProperties": false
  },
  "strict": true
}

The name must match the filename (without extension). The description is critical: the LLM uses it to choose when to call this function. The parameters follow the usual JSON Schema format; the LLM will fill these from the conversation and pass them to your code as air.args.

Writing a Function

A minimal example is the get_weather function. It takes a location from the LLM, calls a weather API, and returns the result to the agent.

Code (.py):

async def run(air):
    """Get the current weather for a location."""
    location = air.args.get("location", "")
    if not location:
        air.reply_to_llm("No location was provided.")
        return

    air.send_interim_message_to_user()
    response = await air.http_get(f"https://wttr.in/{location}?format=j1")

    if not response:
        air.reply_to_llm(f"Could not retrieve weather for {location}.")
        return

    data = json.loads(response)
    temp = data["current_condition"][0]["temp_C"]
    air.reply_to_llm(f"The temperature in {location} is {temp}°C.")

• air.args.get("location", "") — Reads the argument defined in the schema.
• air.send_interim_message_to_user() — Tells the user something like "Please wait a moment..." while the API call runs.
• await air.http_get(url) — Makes an HTTP request and returns the response body.
• air.reply_to_llm(message) — Sends the result back to the LLM so it can respond to the user.

Important points when writing functions:

• Use await for async methods such as air.search(), air.send_message_to_user(), air.send_email(), air.http_get(), and air.http_post().
• The json module is available without importing (e.g. json.loads(), json.dumps()).
• You cannot use arbitrary import statements or access files; the environment is sandboxed for security.
• Use air.reply_to_llm(message) to send a result back to the LLM (e.g. success or error text) so it can respond appropriately to the user.

AirScript Variables

Many functions need configuration values like API keys, email addresses, or custom settings. These are stored as AirScript Variables in the agent's configuration and read at runtime using air.get_config('variable_name').

When you add a function to an agent, any variables it requires are automatically created for you. The system scans the function's code for air.get_config() calls and creates the corresponding variables — marking sensitive ones (containing words like token, key, password) as secret.

After saving the agent configuration, you'll be prompted to fill in the variable values. Secret variables are stored in an encrypted vault and masked in the admin console.

→ Editing an Agent — AirScript Variables — Full details on managing variables

Bundled Examples

Five example functions are provided as Global Functions. You can use them as-is (by adding them to an agent) or copy and customise them for your service.

← Back to Agents, Prompts & Functions overview