OpenAI Agents

Run an OpenAI agent that calls your own functions, where each function is a branch of your Process.

An agent step sends the user's message to an OpenAI model (Responses API) together with the functions you list in its form. When the model wants a function, the step tells your Process which one and with what arguments; your Process does the work with any Tasks you like and hands the result back; the agent then answers. The agent keeps an OpenAI conversation, so it remembers what was said earlier in the Session.

This Module replaces OpenAI Assistants, which OpenAI shut down on 26 August 2026.

How it works

• The agent step does not branch. It writes one variable, {agent} by default. {agent.next} is the name of the function to run now, or completed when the model has answered.
• A Switch picks the branch. Put a Switch on {agent.next} after the agent step: one case per function, and completed as the default branch.
• Each function branch ends with Function result. It gives the function's result back and connects back to the agent step.
• Arguments are typed. The model's arguments for a function land in a variable named like the function ({lookup_order}), so a later Task reads {lookup_order.orderId}. Numbers are numbers, yes / no values are true or false, lists are lists.
• Several calls at once. A model can ask for several functions in one turn. The engine runs one branch at a time, so the agent hands the calls out one after another ({agent.pending} says how many are left) and sends all the results back in one request when the last branch is done. Set Parallel calls off when a call depends on the previous one's result: the model then asks for one function per turn.

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.

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

Tasks

All Tasks in this Module are Generic (all Channels).

OpenAIAgentTask

Runs the agent. On a new turn it sends Input; when it is re-entered from a Function result it hands out the next requested call, or sends the results to the model.

Property	Type	Required	Example	Description
Model	string	Yes	gpt-6-luna	The model. Pick one or type any model your account offers.
Reasoning effort	choice	No	low	Reasoning models only.
Instructions	string	No	You are the support assistant of {companyName}.	Who the agent is and how it behaves; sent with every request.
Input	string	Yes	{userMessage}	The user's message that starts a turn.
Functions	list	No	see below	What the agent can ask your Process to do.
Parallel calls	yes / no	No	On	On: several calls per turn, handed out one at a time. Off: one call per turn.
Tool choice	choice	No	Auto	Auto, Required (must call a function at the start of a turn) or None.
Web search, Code interpreter, File search		No		OpenAI's built-in tools; File search takes vector store IDs from the Files Module.
Keep the conversation	yes / no	No	On	On: the turns of the Session join one OpenAI conversation, so the agent remembers them.
Conversation ID	string	No	{conversationId}	Continue an existing conversation instead of creating one.
Max function rounds	number	No	10	Most model calls in one turn before the step stops with an error.
Max output tokens	number	No	800	Cap on output tokens per model call.
Store the result in	object	Yes	agent	Receives next, function, arguments, callId, pending, reply, responseId, conversationId.

A function has a Name (letters, digits and _, the value of {agent.next}), a Description (the model reads it to decide when to call it), its Parameters, and optionally Store the arguments in (default: a variable named like the function).

A parameter has a name, a type, whether it is required, and a description:

Type	The model sends	Options	Your variable gets
Text	text	format (date, time, date and time, duration, email, host name, IPv4, IPv6, UUID), pattern	text
Number	a number	minimum, maximum	a number
Whole number	a whole number	minimum, maximum	a whole number
Yes / no	true or false		true or false
Choice	one of your choices	the choices	text
List	a list of one of the types above	item type, min and max items, choices	a list
Object	an object	its fields (one level, any type above)	an object

The agent sends OpenAI a strict schema built from this table, so the model must follow it; arguments that still don't fit stop the step with an error instead of reaching your branch with the wrong type. An optional parameter the model leaves out is empty.

OpenAIFunctionResultTask

Ends a function branch and connects back to the agent step.

Property	Type	Required	Example	Description
Result	string	No	{order}	What the function produced. A variable holding an object or list is sent as JSON.
The function failed	yes / no	No		On: the model is told the function failed, with the message below.
Error message	string	No	Order not found	What went wrong, in words the model can pass on.
Agent result	string	Yes	{agent}	The agent step's Store the result in variable.

Common recipes

A support agent that looks up and cancels orders

1. InputTask (Standard Module): Output Variable = userMessage.
2. OpenAIAgentTask: Model = gpt-6-luna, Instructions = You are the support assistant. Use the functions to look up or cancel orders., Input = {userMessage}, Store the result in = agent. Functions:
   • lookup_order: "Finds an order and its status", parameter orderId (Text, pattern ^[A-Z][0-9]+$).
   • cancel_order: "Cancels an order not yet shipped", parameters orderId (Text) and reason (Choice: duplicate, changed_mind, not required).
3. Switch: Value to check = {agent.next}; cases equals lookup_order → lookup_order, equals cancel_order → cancel_order; When nothing matches = completed.
4. lookup_order branch: HTTP Task GET https://shop.example.com/orders/{lookup_order.orderId} into order, then OpenAIFunctionResultTask Result = {order}, connected back to the agent.
5. cancel_order branch: Data Task that updates the order {cancel_order.orderId}, then OpenAIFunctionResultTask Result = cancelled (or The function failed + Error message), connected back to the agent.
6. completed branch: OutputTask Message = {agent.reply}, then back to the InputTask for the next message.

When the user asks about A42 and to cancel B7 in one message, the model asks for both functions at once: the Switch first takes lookup_order, then cancel_order, and the agent answers once both results are in.

Best practices

1. Describe functions for the model. The description and the parameter descriptions are all the model knows: say what the function does and when to use it.
2. Give every function an error path. Report failures with The function failed rather than letting the branch end with an error: the model can then explain the problem to the user.
3. Add an error flow after the agent step. OpenAI errors, the rounds limit and malformed arguments all leave the step through its error flow.
4. Keep branches quick. The user is waiting for the answer while the branches run.

Troubleshooting

OpenAIAgentTask: function 'lookup_order' returned no result.

The agent step was re-entered before the branch answered. End every function branch with OpenAIFunctionResultTask (with the same Agent result) before connecting back to the agent.

OpenAIFunctionResultTask: no function call is waiting in {agent}.

The Function result step ran outside a function branch, or its Agent result names a different variable than the agent's Store the result in.

OpenAIAgentTask: the model kept calling functions

The model reached Max function rounds in one turn. Check that each function's result answers what the model asked, or raise the limit.

Error codes

Code	Name	Description
3005	TaskInvalidData	A function or parameter is not valid, an output field is not a variable, or a Function result has nothing to answer details
4001	ModuleException	OpenAI rejected the request, the model's response failed, the rounds limit was reached, or the arguments did not fit details
4008	ModuleMissingConfiguration	The OpenAI API key is not set in this Module's Environment configuration details
4009	ModuleInputEmpty	Input resolved to an empty value at the start of a turn details
4022	ModuleLogWarning	The step's model is retired by OpenAI and its replacement was used details

See the Error Code Reference for the full list.

Related pages

• OpenAI Module: the family core, with chat, the Responses API, conversations and moderation.
• OpenAI Files & Vector Stores: build the vector stores the agent's File search uses.
• Standard Module: Input, Output and Switch.