Deep-Dive: Functions and Secure Services

This module covers two advanced capabilities: custom functions that extend agent behaviour, and secure services that restrict access to authenticated users. Read this when your service uses these features or when you're planning to implement them.

Who this is for

• Technical owners who implement or maintain functions
• Platform administrators who configure secure services
• Anyone planning to add these capabilities to their service

What you'll learn

• What functions are and when to use them
• How functions integrate with agents
• How to manage AirScript variables
• How secure services authenticate users
• The setup process for secure services
• Authorisation options for controlling access

Part 1: Functions

What functions do

Functions let agents perform actions beyond answering from the knowledge base:

Functions extend what the AI can do without requiring changes to the underlying platform.

When to use functions

Good use cases:
- You need to call an external API (CRM, e-commerce, internal systems)
- You want to send emails programmatically
- You need search with custom filters not available by default
- You want to display rich content (maps, formatted data)
- You need escalation workflows with specific data capture

When you don't need functions:
- Basic Q&A from your content works fine → Use default search
- You just need exact answers → Use curated answers
- You want different handling for different question types → Use specialist agents with different prompts

How functions work

1. Agent decides to use a function — The AI reads the function schema and decides the function would help answer the user's question
2. Function is called — The AI provides arguments; the system executes your function code
3. Function returns a result — Your code replies to the AI with the result
4. Agent incorporates the result — The AI uses the function's output in its response to the user

Functions are written in AirScript, a secure subset of Python.

Function components

Each function has two parts:

The .py file — AirScript code that runs when the function is called:

async def run(air):
    location = air.args.get("location", "")
    # ... do something with location ...
    air.reply_to_llm(f"Result for {location}")

The .function file — JSON schema that tells the AI when and how to call the 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"]
  }
}

The description is critical — the AI uses it to decide when to call the function.

Global vs custom functions

Global Functions — Provided by Airgentic for common use cases:
- escalate_to_human — Collect contact details and email the conversation
- get_weather — Look up weather for a location
- create_support_ticket — Send ticket data to an external system
- check_order_status — Query an order API
- schedule_callback — Email a callback request

You can use global functions as-is or copy and customise them.

Your Functions — Functions you create or customised copies of global functions. You have full control over these.

AirScript variables

Functions often need configuration values (API keys, email addresses, endpoints).

How it works:
- Functions read variables using air.get_config('variable_name')
- Variables are defined in the agent's configuration
- When you add a function to an agent, required variables are automatically created
- Variables can be regular (visible) or secret (encrypted and masked)

Setting variable values:
1. Add the function to an agent
2. Save the agent configuration
3. Fill in the variable values in the AirScript Variables section
4. Save again

Related: Editing an Agent

Enabling functions for agents

Functions are enabled per-agent:

1. Open the agent configuration
2. In the Agent Prompts section, expand a prompt card
3. Check the functions you want this agent to use
4. Save the configuration

Only agents with a function enabled can call it. This lets you have some agents with function access and others without.

Testing functions

1. Add the function to an agent
2. Set the agent to Testing status
3. Configure any required variables
4. Use Admin Chat to test
5. Check the Trace Log to verify function calls are happening

What to check:
- Is the function being called when expected?
- Are the arguments correct?
- Is the function returning the right result?
- Is the AI using the result appropriately?

Function limitations

• Functions run in a sandboxed environment
• Only approved modules are available (no arbitrary imports)
• HTTP requests have timeout and size limits
• File system access is not available
• The air API provides the only external access

Related: Functions Overview, AirScript Functions

Part 2: Secure Services

What secure services do

A secure service restricts access to authenticated users only:

• Users must sign in through your identity provider
• Only authorised users can use chat and search
• Ideal for intranets, internal knowledge bases, HR tools

Without secure services, your service is publicly accessible.

How authentication works

The flow uses OpenID Connect (OIDC) and PKCE:

1. User opens the page with the Airgentic widget
2. Widget redirects to your identity provider's sign-in page
3. User authenticates with your IdP (Airgentic never sees passwords)
4. IdP redirects back with an authorisation code
5. Airgentic backend exchanges the code for identity proof
6. User is checked against your authorisation rules
7. If allowed, a session token is issued
8. Widget operates normally with the session token

Key security points:
- No passwords in the widget
- No secrets in the page embed code
- Standard protocols (OIDC + PKCE)
- Tokens are short-lived

Setting up a secure service

Secure service setup is a joint effort:

What your IT team does:
1. Register an application in your identity provider
2. Configure redirect URIs to match your site
3. Provide Airgentic with client ID, tenant ID, and redirect URLs
4. Embed the secure widget code on your site

What Airgentic does:
1. Enable secure mode on your service
2. Configure allowed origins
3. Set up the identity provider connection
4. Apply authorisation rules

See Secure Services Checklist for the detailed task list.

Authorisation options

After a user authenticates, you can control who is allowed access:

You can combine methods — a user matching any rule is granted access.

Supported identity providers

Secure vs public documents

When using secure services, documents can be:

• Public — Anyone with the link can view
• Secure — Only authenticated users can view citations

Use secure documents for internal or confidential content.

Common setup issues

Related: Secure Services Overview, Secure Services Checklist

When to use these features

Functions

Secure services

Related documentation

Functions

• Functions Overview — Concepts and examples
• AirScript Functions — Technical reference
• AirScript Reference — Language details
• Writing Your First Function — Getting started

Secure Services

• Secure Services Overview — Introduction
• Secure Services Checklist — Implementation tasks
• Registering in Your Identity Provider — IdP setup
• Adding the Secure Widget — Embed code
• How Secure Authentication Works — Technical explanation
• Security Settings — Admin console configuration

Back to: Optional Deep-Dives