Tasks

GPT Chat Task

Start a GPT chat completion task. Pass some messages to this task to get a response from an AI chat assistant. The assistant's response will be available in the stub the task ran from as a _update_from_chat_assistant feedback action. The task can call Stubber actions marked as ai_callable when suitable using GPT's functions functionality.

The rest of this document assumes familiarity with adding a task to a stub. See tasks documentation

# Basic usage

Start a chat with the default model.

Note: This task has a wide variety of possible use cases, see the Examples section.

# Failsafes

Due to the nature of AI chat assistants, there is a risk of infinitely repeating conversations when two auto-responding bots find themselves talking to one another. To mitigate this risk, two failsafe mechanisms are in place:

# Message Count Failsafe

The stop_on_high_messages failsafe prevents a chat from exceeding 200 messages in a single conversation. This counts all message types (user, system, and assistant) within the current chat context.

This message count can be reset by using the message_operation: "set" parameter, which clears previous messages. The failsafe can be disabled by setting stop_on_high_messages: false, or adjusted to a different limit by setting a specific number.

# Interaction Count Failsafe

The stop_on_high_interactions failsafe tracks how many times a specific chat (identified by chat_name) has interacted with a model, with a default limit of 1000 interactions.

Unlike the message count, this counter cannot be reset and persists even when messages are cleared. This provides protection against scenarios where a process might clear messages but still be caught in an infinite bot-to-bot conversation loop. The failsafe can be disabled by setting stop_on_high_interactions: false, or adjusted to a different limit by setting a specific number.

Both failsafe limits are enabled by default to prevent runaway processes.

# Parameters

# messages

optional

array

An array of message objects.
The messages to submit for a chat completion.
The messages in the array should be sorted ascending chronologically, meaning that the message at the first index in the array should be the earliest message, and the last message in the array should be the latest.

Each chat has an array of messages that is automatically handled by the Stubber system. When there is a back and forth discussion between an assistant and a user, the messages are appended to this array, unless the message_operation is set, then the messages are overwritten by the messages of the current task.

Default: []

# message_operation

optional

string

This can be either set or append. It defines the operation to use for the messages in the active chat (via gptchattaskuuid). The set operation erases the previous messages of the chat and sets the messages passed in this instance of the task as the messages for the chat completion. The append operation appends the messages of the current task to the existing messages in the chat.

Default: append

# model

optional

string

The model that the task should use to do this specific instance of chat completion. If it is the first instance of a chat, the model will be saved for next instances in the same chat. This parameter is thus not required, but recommended for at least the initial chat to set the desired model.

Common models to use are:

• gpt-4o: State of the art model, omnichannel, large context window, fast, good reasoning capabilities, better instruction following, JSON mode and more.
• gpt-4o-mini: Cost-efficient small model with strong performance, 128K token context window, supports text and vision inputs, ideal for high-volume or chained operations.

See Models for a full list of supported models.

Default: gpt-4o-mini

# submit_to_model

optional

boolean

Whether or not the task should actually submit the messages to the model/assistant for a response. This could be useful to set to false when a chat should be initiated by the assistant with a default message. Example:

Default: true

# set_model

optional

boolean

Override the model in the specific chat with this model. This will change the model for future chat instances in cases where the specific model is not specified. If a single task has model and set_model, the set_model model will be used

Examples:

• gpt-4o

Default: null

# gptchattaskuuid

optional

array

The gptchattaskuuid is the globally unique reference used inside Stubber to keep track of the specific details of a chat, such as the model details, the previous messages, token usage etc. This is by default a deterministic uuid generated from the stub's stubref, such that each stub automatically has a unique chat. It is only required to specify this if you want fine grain control over which GPT tasks should use which chats across various stubs. If you want multiple different chats on a single stub, use chat_name instead.

Default: {{#deterministicuuid stub.stubref}}

# chat_name

optional

array

The human readable name of the chat, such as "supervisor" or "contractor". Each chat has a unique id, gptchattaskuuid, that is used to enable tasks to keep appending messages and instructions to the same chat, continuously building on the chat context. This unique id is generated with a combination of the stubref and the chat_name. Chats happening on different stubs are thus automatically different. If you want to have different chats on the same stub, you have to give each chat its own chat_name, and then use this chat_name in all usages of the gpt_chat_task for that chat.

Default: ""

# function_call

optional

string or object

This parameter determines whether functions will be added to the chat completion task. With this parameter set to auto, the assistant will automatically choose when to call a function, and which function to call. If the assistant calls a function and everything is set up correctly, as described here, the action with the same name as the function will be ran on the stub of the chat.

This parameter can also be used to force a specific function (and consequently, action) to be ran. This can be done by specifying the parameter as {"name": "get_weather"}. This example will force the assistant to call the get_weather function.

Default: auto

# functions

optional

array

An array of function objects to make available to the assistant. It is important to note that actions with the action_meta containing ai_function_calling: true, will be added to the functions the assistant has access to automatically.

This parameter should only rarely be required. Below is an example of a single function object:

Function objects that are generated automatically from actions have the same structure. The fields of the action becomes the properties, the help of each field becomes the description of the property. The name of the action becomes the name of the function. The description of the action becomes the description of the function.

Default: null

# temperature

optional

array

This is a parameter to change the consistency of the response of the assistant. Lower values, such as 0.15, result in more consistent responses. Higher values, such as 0.80, will generate more creative and diverse results.

Default: null

# action_result_inject_data

optional

any

This parameter defines the data that is returned to the chat assistant when the assistant calls an action. By default the entire stubpost is passed, this can use quite a lot of unnecessary tokens. To pass the result of a specific task, use {{{{skip}}}}~~stubpost.tasks.savedata{{{{/skip}}}}. To pass multiple fields or task results, define this parameter as an array or object containing the desired values.

Default: {{{{skip}}}}~~stubpost{{{{/skip}}}}

# max_tokens

optional

integer

The maximum tokens that the assistant can respond with. In general this is not required, and should mainly be used if an abnormally short response is required.

Default: null

# set_system_message

optional

string

The system message passed here will replace the system message in the existing chat. It will remain the system message for all subsequent chats in the same conversation. So it will not last just a single task instance, but will be the new system message until it is changed again.

Default: null

# response_format

optional

object

This only works for the gpt-4-1106-preview model. For the assistant to respond in only json, this parameter has to be set to {"type": "json_object"}, and you have to mention the word "json" somewhere in the system message.

Default: null

# extract_data_from_message

optional

boolean

Set this to false if you do not want the model to extract tags such as <thinking>...</thinking> or <span>...</span> as data points. This is required if you attempt to force the model to respond in HTML, since all tags will be extracted as data points and be removed from the message.

Default: true

# disable_model_response

optional

boolean

When this is set to true, the task will not publish the feedback action, by default _update_from_chat_assistant_task. The task can still execute actions, which can be disabled with disable_model_action_execution.

Default: false

# disable_model_action_execution

optional

boolean

If set up correctly, when an assistant decides to run a function, it can run an action on Stubber. When this is set to true, the task will not execute actions on Stubber's system.

Default: false

# assistant_response_action_name

optional

string

The feedback action that the task will call with the result of the chat completion.

Default: _update_from_chat_gpt

# set_assistant_response_action_name

optional

string

This will set the feedback action that the task will call with the result of the chat completion. This will be the feedback action for all future tasks in the chat.

Default: null

# append_response_to_messages

optional

string

Each chat has an array of messages that is automatically handled by the Stubber system. When there is a back and forth discussion between an assistant and a user, the messages are appended to this array, unless the message_operation is set, then the messages are overwritten. When append_response_to_messages is false, the response of the assistant is not appended to the array of messages of the chat.

Default: true

# stop_on_high_messages

optional

integer

boolean

Controls the maximum number of messages allowed in a single chat conversation before the task is blocked. This count includes all message types (user, system, assistant) present in the chat at the time of execution.

This parameter serves as a failsafe mechanism to prevent infinite conversations, particularly in bot-to-bot interactions. The default limit is set to 200 messages, which can be:

• Increased by specifying a higher number
• Disabled by setting to false (not recommended)
• Reset by using message_operation: "set" to clear previous messages

The default limit is intentionally conservative since model performance can degrade with very long message histories. It's recommended to periodically reset the conversation using message_operation: "set" rather than significantly increasing this limit.

Examples:

• false - Disables the message limit check
• 500 - Sets a custom message limit
• true - Uses the default limit (200)

Default: 200

# stop_on_high_interactions

optional

string

Controls the maximum number of model interactions allowed for a specific chat (identified by chat_name) before the task is blocked. An interaction is counted each time the chat communicates with the model, regardless of the number of messages exchanged.

This parameter provides an additional failsafe layer that:

• Persists across message resets (unlike stop_on_high_messages)
• Cannot be reset by clearing messages
• Helps prevent infinite loops in automated conversations

The interaction counter:

• Increments with each model call
• Persists even when messages are cleared via message_operation: "set"
• Is specific to each unique chat

Examples:

• false - Disables the interaction limit check
• 500 - Sets a custom interaction limit
• true - Uses the default limit (1000)

Default: 1000

# action_call_result_method

optional

string

By default, when the assistant decides to run an action, a dynamic task is added to that action to return the result of the action back to the assistant, allowing the assistant to respond on the result of the action it initiated. A custom dynamic task can be passed instead of the default one by setting this parameter to custom.

Default: null

# dynamic_tasks

optional

array

The tasks to dynamically add to an action that the assistant has chosen to run. The default task that is added, return_gpt_function_data, returns the result of the action, the stubpost, to the assistant. The assistant will then respond normally with the passed feedback action, by default _update_from_chat_assistant_task.

This parameter is only used if action_call_result_method is set to custom. If it is specified as custom, only the tasks specified in dynamic_tasks will be added to the action.

Default:

# Result

# Properties

# response

The response as it was received from Open AI.

# response.id

The unique identifier for the chat completion in Open AI's system. This is not used in Stubber.

# response.object

The type of the response object, this should always be chat.completion.

# response.created

The timestamp at which the response was created in Open AI's system.

# response.model

The exact model that was used for the chat completion. This property could be of some significance, since it is not always exactly the model that is passed as a parameter. This is the case here. No model was passed in the Basic Usage section, so the default gpt4o-mini was used, yet the value in the response is gpt4o-mini.

# response.choices

The choices object is the property that contains the message with some additional information. It should very rarely be necessary to use this property. Since the message is the desired result from this task, we include it in the top level of the response for convenience.

# response.usage

The details of the token usage can be found in this property.

• prompt_tokens: the amount of tokens that the prompt, ie. the messages, used.
• completion_tokens: the amount of tokens in the completion, ie. the response of the assistant.
• total_tokens: a sum of the prompt_tokens and the completion_tokens.

# response.system_fingerprint

This is a unique identifier for Open AI for the system that was responsible for handling the request.

# response.message

This is the response of the assistant on the prompt or messages that was provided for the task. This message will also be passed as the message of the feedback action, _update_from_chat_assistant_task.

# Action Meta

All Stubber actions have the action_meta property. For gpt_chat_task, this property can be used to make actions available to AI assistants for calling. It can also be used to change the behaviour when only specific actions are run by the AI assistant.

Here is an example action_meta object for a get_weather function. The initial ai_function_calling: true is what makes the action available for calling by AI assistants. Additional parameters are then all nested inside of ai_details.

See Action Meta for more information on the action_meta property of actions.

# Examples

In these examples, the wider picture of what happens will be shown, as the most important part of the task result is the assistant's response message, and that is fairly simple to understand. Which parameters to use in which scenario is the secret sauce of this task.

# Greet new user with the weather

We have an action called greet_new_users with the gpt_chat_task definition below.

The task definition:

The assistant calls a Stubber action get_current_weather to get the weather in a location, and then generates a welcome message which includes the weather. This requires an action, get_current_weather, with the action_meta field ai_function_calling set to true and a text field with the name location available on the stub in the correct state.

For our get_current_weather action, we added a task with an API call to api.weatherapi.com. This task is as below:

We added an api key for api.weather.com in our stub data. As for the {{stubpost.data.location}}, when the assistant decides to call a function, the properties that the assistant uses to call the function are added to the stubpost.data of the action that the Stubber system runs on behalf of the assistant. So the stubpost.data.location value will come from the assistant.

# Result

Note that in the order of things happening below, the disable_model_response: true parameter ensures that there would not be an additional assistant response between steps 2 and 3. Sometimes the assistant informs the user that it is going to call a function before actually calling the function.

The order of things happening in this example is as follows:

1. We run the greet_new_users action with the message "I am flying to New York".
2. The action runs the gpt_chat_task defined above, calling the assistant.
3. The assistant responds that the action get_current_weather, with the location parameter set to "New York", should be ran. The dynamic task that will return the result of the action to the assistant is added to the get_current_weather action request.
4. The Stubber system automatically runs the get_current_weather action, and thus the task that makes an api call to api.weather.com.
5. The dynamic task returns the entire stubpost of the get_current_weather action as a appended message to the assistant.
6. The assistant generates a greeting response as instructed in the system message, this response is added to the stub via the task feedback action, _update_from_chat_assistant_task.

Here is a screenshot of the flow in Stubber: 

# Force the model to respond in Json only

This is only available for select models. You have to mention the word "json" in the system message, or the task will error.

The task definition:

# Result

Here follows the result with the stubpost message as "Create a recommended people structure for my company, "The Pink Factory". We have technical, operations, support and sales teams with 5, 5, 10, 10 members in each respectively."