Generate Response from Model

Gets a text response from an AI model given a user prompt.

Options 

• Account Name is a text expression of the AI account for this script step to use. In the current file, use the Configure AI Account script step to set up the account and assign it this name any time before this script step runs.

• Model is the name of the text generation model to use. Specify the model name as a text expression. For supported models, see FileMaker technical specifications.

• User Prompt is a text expression for the natural language request or question to send to the model, which is usually the request made by the user.

• Agentic mode controls how this script step handles automated tool interactions:

  • On: Enables automated multistep interaction where the model can call tools repeatedly until reaching a final result.

  • Off: Performs a single interaction and stops after the first tool call without executing the tool call or returning a result in Response, allowing for manual handling and debugging. If no tool calls are made, returns the result from the model in Response.

• Response specifies the field or variable where the result of the script step is to be stored. If you specify a field and select Stream, the field must be on the current layout.

• Instructions is a text expression that provides additional context or behavioral guidelines for the model.

• Messages specifies the field or variable that contains message history to provide the model context from previous interactions. The messages are an array of JSON objects. Each JSON object must contain key-value pairs for the text of the message (content) and who provided the content (role), either the user ("user") or the model ("assistant"). For example:

  Copy

  [ 
    {
      "content": "What is the temperature in Cupertino?",
      "role": "user"
    },
    {
      "content": "The temperature in Cupertino is 72 degrees Fahrenheit.",
      "role": "assistant"
    }
  ]

• Save Message History To specifies the variable where the script step stores the message history. The format is the same as for Messages, with the message pair for the current run of this script step added to the end.

  If you want the message history to persist after the current script ends, use a global variable (which persists until the FileMaker client session ends) or store the variable's value in a field. See Using variables or the Set Field script step.

• Message History Count is a numeric expression that controls the number of previous message pairs (user question and assistant answer) to include in the variable specified by Save Message History To.

• Temperature controls the randomness or creativeness of a model's response to a prompt. Low values produce more deterministic, factual results. High values generate more creative, unexpected, or less coherent results. Refer to the model provider's documentation for valid ranges for the specific model you're using.

• Tool Definitions specifies a JSON array of available tools that the model can call during processing. See "Tool definitions" below.

• Tool Calls from Model specifies where to store information about tool calls made by the model. This may be useful for debugging or to audit the model's use of tools.

• Stream controls how the response is delivered:

  • On: The response is retrieved and delivered incrementally (word by word or in chunks). This can make the FileMaker client feel more responsive.

  • Off: The entire response is retrieved before it is made available. This may cause the FileMaker client to appear unresponsive while waiting for the complete response.

• Parameters is a text expression for a JSON object that consists of key-value pairs for additional parameters that are supported by the model provider. For example: {"temperature": 0.7, "seed": 42}. Refer to the model provider's documentation for key names of supported parameters and their valid ranges.

• Perform JavaScript in Web Viewer specifies JavaScript code to perform in a target Web Viewer after the script step completes. This option is similar to running the Perform JavaScript in Web Viewer script step as the next script step, except that the response can be passed in to the JavaScript function and streamed to the web viewer when the Stream option is On.

  • Web Viewer specifies the object name of a web viewer on the current layout.

  • Function Name is the name of the JavaScript function to call in the web viewer.

Originated in version 

22.0

Description 

This script step facilitates multistep interaction between your custom app and AI models, enabling the model to access and manipulate data through tool calls when needed. The script step operates in two distinct modes based on the Agentic mode option, each providing different levels of automation and control over the interaction.

The interaction between this script step and the model typically follows these steps:

1. This script step sends the User Prompt, any Instructions, conversation context from Messages, and available Tool Definitions to the configured Model.

2. The model analyzes the prompt and determines whether it can provide a direct response or needs to use tools to gather additional information or perform actions.

3. If tools are needed, the model generates tool calls with appropriate parameters based on the available tool definitions and the user's request.

4. This script step receives the tool calls from the model and the FileMaker client executes them. Tool execution may include the predefined tools, such as SQL queries, or calls to your own custom functions.

5. This script step sends the results of the tool execution back to the model, providing the model with the data or confirmation it needs to continue processing.

6. If the model determines that additional tools are needed to fully address the prompt, it may generate more tool calls (repeating steps 3-5). This iterative process continues until the model has sufficient information to provide a comprehensive response.

7. After the model has completed all necessary tool interactions, it generates a final response that incorporates the tool results and addresses the original user prompt.

8. This script step receives the final response, stores it in the specified Response target, and optionally updates the history of interactions in Save Message History To.

The Agentic mode option determines how the interaction is handled:

• On: Enables automated multistep interaction with tools, executing the complete workflow (steps 1-8) automatically. When the AI model determines that tools are needed to fulfill the request, it automatically calls the appropriate tools and continues processing until reaching a final result. The model can make multiple rounds of tool calls as needed, with each round building on the results of previous tool executions. This mode is for complex tasks that require multiple tool interactions, such as analyzing data across multiple tables, generating reports, or performing multistep operations.

• Off: Performs a single interaction with the AI model, executing only steps 1-3 and stopping after the first tool call. If the model determines that tools are needed, the script step stops and returns the tool call information in Tool Calls from Model rather than executing the tools automatically. This mode is useful for debugging tool interactions, understanding what tools the model wants to use, or when you want manual control over tool execution. You can examine the tool calls and then decide whether to execute them manually or modify the approach.

The flow of information between this script step and the model ensures that sensitive data remains secure while enabling AI-driven functionality. The model receives only the information explicitly provided through prompts, instructions, and tool results—it does not have direct access to your FileMaker database or files. Tool calls are executed within the controlled FileMaker environment, allowing you to maintain full control over data access and operations via FileMaker accounts and privileges while leveraging the model's analytical and reasoning capabilities.

Tool definitions

Tool use (also referred to as function calling by some model providers) enables the model to call back to your FileMaker Pro app to do or provide something the model needs to generate its final response. In agentic mode, the model can call multiple tools repeatedly until it's done. In the Tool Definitions option, you can define the following tools:

• execute_sql: A predefined tool that performs the specified SQL query, capable of executing an SQL statement passed in by the model in the same way the Perform SQL Query by Natural Language script step does.

• retrieve_image: A predefined tool that retrieves an image from the container field specified by a SQL query to specify the record ID as well as the table and field name to specify the container field where the image is stored.

• Custom functions: Any custom functions defined in your file. See Using custom functions.

Tool definitions are specified using the JSON format required by the model provider. In general, the definition is an array of objects where each specifies a tool's name, a detailed description of what the tool does and what rules the model should follow when using it, and for each input parameter, its name, data type, and description. The descriptions should be as detailed as necessary for the model to use the tool reliably. If you use the predefined tools, start by using the definitions provided below. If needed, modify them to achieve optimal results for the models you use.

To help you debug your tool definitions, set the Tool Calls from Model option to a field or variable where you can see how or whether the model called the tools. This can help reveal what you may need to add or change in the descriptions you provide in your tool definitions.

For the specific JSON format used for tool definitions and tool calls, see the model provider's documentation—for example, Anthropic, Cohere, and OpenAI.

execute_sql

Returns: The result of the SQL query as a string.

retrieve_image

Returns: JSON data in the following format, containing the image as a Base64-encoded string.

[
  {
    "data": "/9j/4AAQ...//2Q=="
  }
]

Custom functions

Follow these guidelines for tool definitions to call custom functions:

• For the function:

  • In the name key, use exactly the name of the custom function as defined in the Edit Custom Function dialog.

  • In the description key, provide a detailed description of what the custom function does and what rules the model should follow when using it.

• For parameters:

  • Define exactly the same number of parameters and in the same order as the parameters defined in the Edit Custom Function dialog. The parameter names don't need to be the same.

  • In the description key, provide a detailed description of what the model must provide in the parameter.

  • Set the value of the type key to "string" (parameters are always treated as text).

Notes 

• Common error messages include "No tool call exists for the prompt" when the model can't determine appropriate tools to use, and "Function not found" when a tool definition references a custom function that doesn't exist.

Example 1 

Configures an AI account, goes to the Contacts layout, then displays a dialog for the user to enter a question. The Generate Response from Model script step then sends the prompt and the recent message history to the model and streams the result to the Response field. For a simple question-and-answer interaction like this, Agentic mode is not selected. To maintain context with the model during the current FileMaker client session, the script step stores the most recent 10 messages in the $$Messages global variable via the Save Message History To option. Via the Messages option, the script step sends the value of the $$Messages variable to the model when this script is run subsequently in the same session. Because the Tool Definitions option isn't used, the model won't be able to answer questions about your data.

Configure AI Account [ Account Name: "my-account" ; Model Provider: OpenAI ; API key: Global::API_Key ] 

Go to Layout [ "Contacts" (Contacts) ]

Show Custom Dialog [ "Enter a question" ; $UserPrompt ]

Generate Response from Model [ Account Name: "my-account" ; Model: Global::ModelName ; User Prompt: $UserPrompt ; Response: Contacts::Response ; Messages: $$Messages ; Save Message History To: $$Messages ; Message History Count: 10 ; Stream ]

Example 2 

Configures an AI account, goes to the Contacts layout, then sends a prompt asking about data in the Contacts table to the model, which uses tools to generate a response. Because up to 10 messages are saved via $$Messages to the Messages global field, context is preserved across FileMaker client sessions.

Configure AI Account [ Account Name: "my-account" ; Model Provider: OpenAI ; API key: Global::API_Key ] 

Go to Layout [ "Contacts" (Contacts) ]

Set Variable [ $Instructions ; Value: "You are a helpful assistant that can query database information. Always provide clear, formatted responses." ]

Set Variable [ $UserPrompt ; "How many contacts do we have from Acme Anvils, and what are their names and email addresses? Add an asterisk after the contacts who are in a city where we have a sales office." ]

Generate Response from Model [ Account Name: "my-account" ; Model: Global::ModelName ; User Prompt: $UserPrompt ; Response: Contacts::Response ; Tool Calls from Model: $$ToolCalls ; Instructions: $Instructions ; Messages: Global::Messages ; Save Message History To: $$Messages ; Message History Count: 10 ; Tool Definitions: Global::ToolDefinitions ; Stream ]

Set Field [ Global::Messages ; $$Messages ]

The ToolDefinitions field contains the following using the JSON format for the model provider OpenAI:

[
  {
    "function": {
      "description": "Respond to the user’s questions by executing the appropriate SQL query using this function. Strictly follow these rules:\r 1. The input should be a fully formed SQL query.\r 2. Perform separate SQL instead of one nested SQL.\r 3. Escaping special characters for SQL query.\r 4. If the result of the toolCall is a raw string that reads 'empty' or 'null', the answer should contain the quoted raw string, which is case sensitive.\r 5. Convert the user’s request into an SQL query using standard SQL syntax only. Ensure that table names and field names match exactly as they appear in the database schema.",
        "name": "execute_sql",
        "parameters": {
          "properties": {
            "sql_query": {
              "description": "Generate a fully formed SQL query based on following rules:\r 1. Enclose all table and field names in double quotes.\r 2. Format dates as \"DATE 'YYYY-MM-DD'\", times as \"TIME 'HH:MM:SS'\" and timestamps as \"TIMESTAMP 'YYYY-MM-DD HH:MM:SS'\".\r 3. Return queries in plain text (not JSON).\r 4. Use \"FETCH FIRST n ROW ONLY\" instead of \"LIMIT\".\r 5. Support single queries only.\r 6. No semicolon is needed at the end of SQL query.\r 7. Don't generate nested SQL queries.\r 8. Use \"LIKE\" instead of \"ILIKE\".\r 9. Keep all comparisons case-sensitive.\r 10. Do not include fields that are not included in the question.\r 11. Use unquoted ROWID in queries.\r 12. Only utilize the following database schema:\rCREATE TABLE \"Contacts\" (\r\"First Name\" varchar(255),\r\"Last Name\" varchar(255),\r\"Email\" varchar(255),\r\r\"City\" varchar(255),\r\"Company\" varchar(255)\r);\r\r",
              "type": "string"
            }
          },
          "type": "object",
          "required": ["sql_query"]
        }
      },
      "type": "function"
  },
  {
    "function": {
      "description": "Check whether our company has a sales office in a specified city. If it does, this function returns 'yes'; otherwise, it returns 'no'.",
        "name": "CityHasSalesOffice",
        "parameters": {
          "properties": {
            "city": {
              "description": "The name of a city",
              "type": "string"
            }
          },
          "type": "object",
          "required": ["city"]
        }
      },
      "type": "function"
  }
]

For execute_sql, use the function description and parameter description provided above. In the sql_query parameter, use the description provided above followed by the schema for the Contacts table.

The custom function CityHasSalesOffice returns "yes" or "no" depending on whether the specified city has a sales office.

Possible response streamed to the Response field:

We have 4 contacts from Acme Anvils. Here are their names, email addresses, and an asterisk indicating if they are in a city with a sales office:

1. Alea Marks, aleamarks165@example.com
2. Kelly Holden, kellyholden1361@example.com *
3. Kelsey Cummings, kelseycummings1396@example.com
4. Kuame Savage, kuamesavage7146@example.com

The $$ToolCalls variable contains several calls to execute_sql and CityHasSalesOffice.

[
  {
    "index": 0,
    "id": "call_e7...",
    "type": "function",
    "function": {
      "name": "execute_sql",
      "arguments": "{\"sql_query\":\"SELECT COUNT(*) FROM \\\"Contacts\\\" WHERE \\\"Company\\\" = 'Acme Anvils'\"}"
    }
  },
  {
    "index": 0,
    "id": "call_o0...",
    "type": "function",
    "function": {
      "name": "execute_sql",
      "arguments": "{\"sql_query\":\"SELECT \\\"First Name\\\", \\\"Last Name\\\", \\\"Email\\\", \\\"City\\\" FROM \\\"Contacts\\\" WHERE \\\"Company\\\" = 'Acme Anvils'\"}"
    }
  },
  {
    "index": 0,
    "id": "call_ev...",
    "type": "function",
    "function": {
      "name": "CityHasSalesOffice",
      "arguments": "{\"city\": \"Onitsha\"}"
    }
  },
  {
    "index": 1,
    "id": "call_IC...",
    "type": "function",
    "function": {
      "name": "CityHasSalesOffice",
      "arguments": "{\"city\": \"Berlin\"}"
    }
  },
  {
    "index": 2,
    "id": "call_Pw...",
    "type": "function",
    "function": {
      "name": "CityHasSalesOffice",
      "arguments": "{\"city\": \"Saint-Malo\"}"
    }
  },
  {
    "index": 3,
    "id": "call_Uy...",
    "type": "function",
    "function": {
      "name": "CityHasSalesOffice",
      "arguments": "{\"city\": \"Wanneroo\"}"
    }
  }
]

Related topics 

• Configure AI Account script step

• Perform JavaScript in Web Viewer script step

• GetTableDDL function

• About custom functions

• Script steps reference