OpenAI Assistants

Run OpenAI Assistants from your workflow: multi-turn threads, streaming replies, run control, and the function-tool callback loop.

This Module drives pre-configured (or workflow-created) OpenAI Assistants. A thread keeps the conversation context across turns, so the same Session can exchange many messages with the Assistant without you managing history. If your Assistant uses function tools, the tool-loop Tasks let your workflow execute each tool call and feed the results back.

How it works

An Assistant is a configured AI persona on OpenAI's side (model, instructions, tools). A thread is one conversation with it. The first time OpenAICreateThreadTask runs in a Session, it creates a thread and stores its ID in the Session under openaiAssistantThreadId; later invocations in the same Session reuse it, so context is preserved across turns. Each invocation starts a run — the Assistant working on your message — which the Task waits on until the reply is ready.

Configuration

Each OpenAI Module is configured separately, per Environment — this Module has its own API key, so you can reuse the key you set on the core OpenAI Module or use a dedicated one (for example to track this capability's spend on its own).

Field	Type	Required	Example	Description
OpenAI API Key	string	Yes	sk-...	Your OpenAI API key for this Module. Stored securely. Find it in OpenAI Console → API keys → Create new secret key.
OpenAI Organization	string	No	org-abc123	Your OpenAI organization ID, if your account belongs to one.

Tasks

All Tasks in this Module are Generic (all Channels) — they run the same regardless of how the Session was started.

Output fields: type a variable name without braces (for example reply) and pick its type (string, number, true/false, object, date). The Task saves its result there, and any later Task can use it by writing {reply}.

OpenAICreateThreadTask

Runs a pre-configured Assistant on a multi-turn thread. The first invocation creates the thread; subsequent invocations reuse the thread id stored in the Session under openaiAssistantThreadId, so context is preserved across turns.

Property	Type	Required	Example	Description
Assistant ID	string	Yes	asst_abc123	The OpenAI Assistant ID (asst_…).
Input	string	Yes	{userMessage}	User message. Supports {variable} placeholders.
Output Variable	string	Yes	reply	Variable name (no braces). Receives the assistant reply.

The Task polls the Run status every 5 seconds, for up to 2 minutes. Beyond that it fails with ModuleException.

Example: Set Assistant ID = asst_abc123, Input = {userMessage}, Output Variable = reply. On the first turn the Task creates a thread and saves the Assistant's answer to reply; on the next turn with {userMessage} = "And what about refunds?", the same thread is reused and the Assistant answers with full context.

OpenAICreateThreadStreamTask

Streaming variant of OpenAICreateThreadTask. The reply arrives chunk by chunk; the Task collects the chunks into the final reply and can also save the ordered chunk list. Function tools are not supported here — use OpenAIRunAssistantWithToolsTask if your Assistant has function tools.

Property	Type	Required	Example	Description
Assistant ID	string	Yes	asst_abc123	The OpenAI Assistant ID (asst_…).
Input	string	Yes	{userMessage}	User message. Supports {variable} placeholders.
Output Variable	string	Yes	reply	Variable name (no braces). Receives the final aggregated reply text.
Chunks Output Variable	string	No	chunks	Optional. Receives the list of streamed text pieces (in order).

Example: Set Assistant ID = asst_abc123, Input = {userMessage}, Output Variable = reply, Chunks Output Variable = chunks. The Task saves the full reply to reply and the ordered streamed pieces to chunks.

OpenAICreateAssistantTask

Creates a new OpenAI Assistant and saves its ID. Use this when you want to provision Assistants from a workflow rather than the OpenAI Console.

Property	Type	Required	Example	Description
Model	string	Yes	gpt-4o-mini	Model the Assistant will run on.
Name	string	No	Support assistant	Display name. Supports {variable} placeholders.
Instructions	string	No	You answer billing questions.	System instructions for the Assistant. Supports {variable} placeholders.
Vector Store IDs (file search)	string	No	{vectorStoreId}	Optional. Comma-separated vector store IDs to attach for file search. Create stores with the OpenAI Files & Vector Stores Module.
Output Variable	string	Yes	assistantId	Variable name (no braces). Receives the Assistant ID (asst_…).

Example: Set Model = gpt-4o-mini, Name = Support assistant, Instructions = You answer billing questions., Output Variable = assistantId. The Task saves the new ID (e.g. asst_xyz789) to assistantId; pass it as {assistantId} to OpenAICreateThreadTask.

OpenAIDeleteAssistantTask

Deletes an OpenAI Assistant by ID.

Property	Type	Required	Example	Description
Assistant ID	string	Yes	{assistantId}	Assistant ID to delete. Supports {variable} placeholders.

Example: Set Assistant ID = {assistantId} as the last step of a Process that provisioned a temporary Assistant, so it doesn't accumulate on the account.

OpenAICancelRunTask

Cancels an in-progress Assistant run.

Property	Type	Required	Example	Description
Thread ID	string	Yes	{openaiAssistantThreadId}	Thread ID. Supports {variable} placeholders.
Run ID	string	Yes	{runId}	Run ID. Supports {variable} placeholders.

Example: Set Thread ID = {openaiAssistantThreadId} and Run ID = {runId} on an error-handling branch to stop a run that is no longer needed.

OpenAIRunAssistantWithToolsTask

Runs an Assistant that may use function tools. This Task is a gateway: it exits via the tools branch with the pending tool calls saved to a variable, or via the completed branch with the final reply. Label the two Sequence Flows after it accordingly, and use OpenAISubmitToolOutputsTask to feed tool results back and resume the run.

Property	Type	Required	Example	Description
Assistant ID	string	Yes	asst_abc123	OpenAI Assistant ID (asst_…).
Input	string	Yes	{userMessage}	User message. Supports {variable} placeholders.
Reply Output Variable	string	Yes	reply	Variable name (no braces). Receives the final assistant reply when the run completes.
Tool Calls Output Variable	object	Yes	toolCalls	Variable name (no braces). Receives the list of pending tool calls when tools are requested. Each entry has id, name, arguments (raw JSON string).

Example: Set Assistant ID = asst_abc123, Input = {userMessage}, Reply Output Variable = reply, Tool Calls Output Variable = toolCalls. When the Assistant calls its lookup_order tool, the Task exits via tools with toolCalls = [{id: "call_1", name: "lookup_order", arguments: "{\"orderId\":\"A42\"}"}]; when no tool is needed, it exits via completed with the answer in reply.

OpenAISubmitToolOutputsTask

Submits tool outputs back to a paused Assistant run (the one OpenAIRunAssistantWithToolsTask exited via the tools branch). This Task is the same kind of gateway: it exits tools if more tool calls are needed, or completed with the final reply.

Property	Type	Required	Example	Description
Tool Outputs Variable	string	Yes	{toolOutputs}	Name (in {var} form) of a variable holding a list of {id, output} entries — one per tool call.
Reply Output Variable	string	Yes	reply	Variable name (no braces). Receives the final assistant reply when the run completes.
Tool Calls Output Variable	object	Yes	toolCalls	Variable name (no braces). Receives the next batch of pending tool calls if the run requests more.

Example: Set Tool Outputs Variable = {toolOutputs} where {toolOutputs} is [{id: "call_1", output: "{\"status\":\"shipped\"}"}], Reply Output Variable = reply, Tool Calls Output Variable = toolCalls. The run resumes and exits completed with "Your order A42 has shipped." in reply.

Common recipes

Let an Assistant call your own functions

Run a tool-enabled Assistant; whenever it requests a function call, execute it with a JavaScript Module script and feed the results back until the reply is complete. Input and Output Tasks come from the Standard Module.

1. InputTask — Output Variable = userMessage.
2. OpenAIRunAssistantWithToolsTask — Assistant ID = asst_abc123, Input = {userMessage}, Reply Output Variable = reply, Tool Calls Output Variable = toolCalls. Label the outgoing Sequence Flows tools and completed.
3. tools branch: JSTask — read each {toolCalls} entry (id, name, arguments), execute the matching logic, and save a list of {id, output} entries to toolOutputs.
4. OpenAISubmitToolOutputsTask — Tool Outputs Variable = {toolOutputs}, Reply Output Variable = reply, Tool Calls Output Variable = toolCalls. Its tools branch loops back to the JSTask; completed continues.
5. OutputTask — Message = {reply}.

Best practices

1. One Assistant per persona, one thread per Session — let OpenAICreateThreadTask manage the thread automatically instead of creating Assistants per message.
2. Use the tools Task for tool-enabled Assistants — OpenAICreateThreadStreamTask does not support function tools; route those Assistants through OpenAIRunAssistantWithToolsTask.
3. Keep tool handlers fast — the run waits while your workflow executes tool calls; long tool branches risk hitting the 2-minute run budget.
4. Clean up provisioned Assistants — Processes that create temporary Assistants should end with OpenAIDeleteAssistantTask.

Troubleshooting

OpenAICreateThreadTask: assistant run timed out after 120s

The Assistant run did not reach a terminal state in 2 minutes (the Task checks every 5 seconds). Check the run in OpenAI Console → Threads for the underlying status; common causes are tool calls hanging or rate limits.

Error codes

Code	Name	Description
3005	TaskInvalidData	A required property is missing or an output field is not a valid variable name — details
4001	ModuleException	OpenAI rejected the request, the call failed, or the run timed out — details
4008	ModuleMissingConfiguration	The OpenAI API key is not set in the OpenAI Module's Environment configuration — details
4009	ModuleInputEmpty	A required input resolved to an empty value at runtime — details
4012	ModuleInvalidData	The Session data could not be read or OpenAI's response could not be processed — details

See the Error Code Reference for the full list.

Related pages

• OpenAI Module — the family core; the API key is configured there.
• OpenAI Files & Vector Stores — upload documents and build the vector stores your Assistant's file search uses.