includes

Remote function signatures to include in SWAIG functions. Will allow you to include functions that are defined in a remote location that can be executed during the interaction with the AI. To learn more about how includes works see the request flow section.

Properties

SWML usage

1
version: 1.0.0
2
sections:
3
  main:
4
    - ai:
5
        prompt:
6
          text: "You are a helpful assistant that can check weather."
7
        SWAIG:
8
          includes:
9
            - url: "https://example.com/swaig"
10
              function: ["get_weather"]
11
              meta_data:
12
                user_id: "12345"

Request flow

SWAIG includes creates a bridge between AI agents and external functions. When a SWML script initializes, it follows this two-phase process:

Initialization Phase: SWAIG discovers available functions from configured endpoints and requests their signatures to understand what each function can do.

Runtime Phase: The AI agent analyzes conversations, determines when functions match user intent, and executes them with full context.

Signature request

During SWML script initialization, SWAIG acts as a function discovery service. It examines your includes configuration, identifies the remote functions you’ve declared, then systematically contacts each endpoint to gather function definitions.

How it works: Looking at our SWML configuration example, SWAIG sends a targeted request to https://example.com/swaig specifically asking for the get_weather function definition. Along with this request, it forwards any meta_data you’ve configured—giving your server the context it needs to respond appropriately.

The discovery request:

1
{
2
  "version": "2.0",
3
  "action": "get_signature",
4
  "content_type": "text/swaig",
5
  "content_disposition": "function signature request",
6
  "functions": ["get_weather"]
7
}

What your server should return: Your endpoint must respond with complete function definitions that tell SWAIG everything it needs to know. Each function signature follows the SWAIG functions structure and describes the function’s purpose and required parameters:

1
[
2
  {
3
    "function": "function_name1",
4
    "description": "Description of what this function does",
5
    "parameters": {
6
      "type": "object",
7
      "properties": {
8
        "param1": {
9
          "type": "string",
10
          "description": "Parameter description"
11
        }
12
      },
13
      "required": ["param1"]
14
    },
15
    "web_hook_url": "https://example.com/swaig",
16
    "web_hook_auth_user": "optional_username",
17
    "web_hook_auth_password": "optional_password"
18
  }
19
]

Your server can optionally include web_hook_auth_user and web_hook_auth_password in each function definition to set HTTP basic authentication credentials for the function’s web_hook_url.

Function execution request

When the AI agent determines that a function call matches user intent—such as when a user requests weather information SWAIG packages the required information and sends it to the configured endpoint. The full details of the request can be found in the web_hook_url documentation.

Example request format:

1
{
2
  "content_type": "text/swaig",
3
  "function": "function_name1",
4
  "argument": {
5
    "parsed": [{"city": "New York"}],
6
    "raw": "{\"city\":\"New York\"}",
7
    "substituted": "{\"city\":\"New York\"}"
8
  },
9
  "meta_data": {
10
    "custom_key": "custom_value"
11
  },
12
  "meta_data_token": "optional_token",
13
  "app_name": "swml app",
14
  "version": "2.0"
15
}

SWAIG provides arguments in multiple formats—parsed for direct access, raw for the original text, and substituted with variable replacements applied. This flexibility supports edge cases and complex parsing scenarios.

Response formats:

When your function completes, it needs to send a response back to SWAIG. You have three main options depending on what you want to accomplish:

1
{
2
  "response": "The weather in New York is sunny and 75°F"
3
}

More information about the response format can be found in the web_hook_url documentation.

Flow diagram

The following diagram illustrates the complete SWAIG includes process from initialization to function execution:

Reference implementation

The following implementations demonstrate the essential pattern: define functions, map them to actual code, and handle both signature requests and function executions.

1
from flask import Flask, request, jsonify
2

3
app = Flask(__name__)
4
FUNCTIONS = {
5
    "get_weather": {
6
        "function": "get_weather",
7
        "description": "Get current weather for a city",
8
        "parameters": {
9
            "type": "object",
10
            "properties": {
11
                "city": {"type": "string", "description": "The city name"}
12
            },
13
            "required": ["city"]
14
        },
15
        "web_hook_url": "https://example.com/swaig"
16
    }
17
}
18
def get_weather(city, meta_data=None, **kwargs):
19
    # Logic to get weather data
20
    # ...
21
    temperature = 75
22
    result = f"The weather in {city} is sunny and {temperature}°F"
23
    # Return both a response AND an action
24
    actions = [{"say": result}]
25
    return result, actions
26

27
# Connect function names to actual functions
28
FUNCTION_MAP = {
29
    "get_weather": get_weather
30
}
31

32
@app.route('/swaig', methods=['POST'])
33
def handle_swaig():
34
    data = request.json
35

36
    # SWAIG is asking what we can do
37
    if data.get('action') == 'get_signature':
38
        requested = data.get('functions', list(FUNCTIONS.keys()))
39
        return jsonify([FUNCTIONS[name] for name in requested if name in FUNCTIONS])
40

41
    # SWAIG wants us to actually do something
42
    function_name = data.get('function')
43
    if function_name not in FUNCTION_MAP:
44
        return jsonify({"response": "Function not found"}), 200
45

46
    params = data.get('argument', {}).get('parsed', [{}])[0]
47
    meta_data = data.get('meta_data', {})
48

49
    # Call the function and get results
50
    result, actions = FUNCTION_MAP[function_name](meta_data=meta_data, **params)
51
    return jsonify({"response": result, "action": actions})
52

53
if __name__ == '__main__':
54
    app.run(debug=True)

Testing the implementation

To test the implementation, start the server and simulate SWAIG requesting function signatures. This command requests signatures from the endpoint:

$
curl -X POST http://localhost:5000/swaig \
>
  -H "Content-Type: application/json" \
>
  -d '{"action": "get_signature"}'

Expected response: A successful response returns function definitions in this format:

1
[
2
  {
3
    "description": "Get current weather for a city",
4
    "function": "get_weather",
5
    "parameters": {
6
      "properties": {
7
        "city": {
8
          "description": "The city name",
9
          "type": "string"
10
        }
11
      },
12
      "required": [
13
        "city"
14
      ],
15
      "type": "object"
16
    },
17
    "web_hook_url": "https://example.com/swaig"
18
  }
19
]