Agent Workflows

An agent’s logic is a Liferay workflow, built in the same Workflow Designer you use for content approval. Agent workflows add five node types to the standard palette: AI Decision, AI Hub Agent, HTTP Request, LLM, and Service.

The AI Hub instance’s Workflow Designer offers all five. A Liferay DXP instance connected to AI Hub offers only the AI Hub Agent node, because the other four nodes run on AI Hub itself. The AI Hub Agent node sends a request to AI Hub and reads the response back, so it’s the only one Liferay DXP can run on its own. See Integrating AI Hub with Liferay DXP.

Creating and Managing Agent Workflows

Open an agent in the Agent Builder and click Edit Workflow on its Workflow panel. The button reads View Workflow when you can’t edit the agent, as with Liferay’s out-of-the-box agents.

New agent workflows contain only a Start node connected to an End node. Add nodes between the two, connect them, and click Update to save.

Beyond the agent nodes, the Workflow Designer functions in the same way it does for any other Liferay workflow. See Workflow Designer Overview and Workflow Nodes to learn more about this process and standard node options (e.g., Condition, State, Task).

Agent Workflow Nodes

Agent workflows use these five node types:

Node	Description	Available On
LLM	Sends a prompt to a language model and stores the response.	AI Hub
AI Decision	Sends a prompt to a language model and uses the answer to choose the workflow’s next path.	AI Hub
HTTP Request	Calls an external endpoint.	AI Hub
Service	Runs one of the Java delegates that ship with AI Hub.	AI Hub
AI Hub Agent	Runs an AI Hub agent and merges its response into the workflow.	AI Hub and connected Liferay DXP instances

Select a node on the canvas to configure it in the sidebar. A node’s settings are split into collapsible sections, each holding the fields for one part of its configuration, so the sections you see depend on the node’s type.

LLM

An LLM node sends a prompt to a language model and stores the response. Use it to generate content, summarize text, or classify data as a step in the workflow.

Its sections are Prompt, Retrieval-Augmented Generation, and Tools.

The Prompt section holds these fields:

Prompt: The instructions the model follows, entered in the section’s first field.

Input Variables: A JSON array naming the values the node reads. See Passing Values Between Nodes.

Output Variables: A JSON array naming where the node stores the model’s response.

User Message: The message sent to the model.

For the other two sections, see Retrieval-Augmented Generation and Tools.

An LLM node accepts at most one outgoing transition. A second one fails validation with a message naming the node, such as The Spanish Translator node cannot have multiple outgoing transitions.

AI Decision

An AI Decision node sends a prompt to a language model and uses the answer to choose which path the workflow takes next. Use it when the branch turns on a judgment about the content the workflow is handling, which the fixed logic of a Condition node can’t express.

Its sections are Prompt, Retrieval-Augmented Generation, and Tools. The Prompt section holds the same fields an LLM node’s Prompt section has. Those are the instructions the model follows, the Input Variables and Output Variables fields, and the User Message sent to the model. For the other two sections, see Retrieval-Augmented Generation and Tools.

An AI Decision node requires at least one incoming transition and at least two outgoing transitions. The model picks one by name, so name the transitions in the Prompt field. When the model names none of them, the node takes the transition whose Default toggle is set in the transition sidebar.

Important

An AI Decision node produces no output variable, even though its Prompt section shows an Output Variables field. A later node can’t read a value from an AI Decision node.

HTTP Request

An HTTP Request node calls an external endpoint. Use it to bring data into the workflow from a REST API or client extension, or to send the workflow’s result out to another system.

Its sections are HTTP Endpoint, Payload, Variables, Connection Timeout, and Authentication:

HTTP Endpoint: The URL to call and the HTTP method. The available methods are DELETE, GET, PATCH, POST, and PUT.

Payload: The request body. Variables substitute here as they do in the URL, so a {{variable}} you’ve declared in Input Variables is replaced before the call goes out.

Variables: The node’s Input Variables and Output Variables. See Passing Values Between Nodes.

Connection Timeout: How long the node waits for a response, set in the Value in Milliseconds field. If you leave it empty, the node waits 10000 milliseconds.

Authentication: Informational, with no field to fill in. AI Hub makes the request on behalf of the signed-in user and sets the Authorization header automatically. Because the node always sends that header and offers no field for your own, use it to call Liferay or another service that accepts the signed-in user’s token. You cannot call an external API that requires its own key.

An HTTP Request node requires exactly one outgoing transition, one of the five HTTP methods, and a URL. It fails validation when any of the three is missing and when it carries more than one outgoing transition. At runtime, the node fails when the endpoint returns a status outside the 200 range. On success, it stores the response body in the variable declared in its Output Variables field.

Service

A Service node runs one of the Java delegates that ship with AI Hub. Liferay’s own out-of-the-box agents use it for steps no other node covers, such as composing a payload or requesting page context.

Its Service section holds the Java Delegate field, which takes a delegate’s key. Shipped keys take the form javaDelegate#generateContent and javaDelegate#composeGapSearch. A value in any other form fails validation, and a key matching no shipped delegate fails at runtime.

A Service node requires at least one outgoing transition.

AI Hub Agent

An AI Hub Agent node runs an AI Hub agent, so a workflow on a connected Liferay DXP instance can call one. Use it to run an agent you’ve already built instead of rebuilding its logic as nodes.

Its sections are AI Hub Agent and Connection Timeout:

AI Hub Agent: The Agent Definition External Reference Code field identifies the agent to run. The node fails validation when this field is empty.

Connection Timeout: How long the node waits for the agent’s response, set in the Value in Milliseconds field. If you leave it empty, the node waits 120000 milliseconds.

The node sends the workflow’s values to AI Hub, merges the agent’s response back into them, then follows its default transition. It requires at least one incoming transition and exactly one outgoing transition.

Retrieval-Augmented Generation

Configure the Retrieval-Augmented Generation section to have the node answer from content in the connected Liferay DXP instance rather than from the model alone. The node searches that instance and passes what it finds to the model along with the prompt.

The section appears on LLM and AI Decision nodes and holds one field, which takes a JSON object. The field’s placeholder provides an example:

{"contentRetriever": {"key": "liferay", "blueprintExternalReferenceCode": "BLUEPRINT_EXTERNAL_REFERENCE_CODE"}}

Set key to liferay to turn that search on. The node searches as the signed-in user, so it reads only content that user can already reach.

Add blueprintExternalReferenceCode to narrow the search to one Search Blueprint. Omit the key to search without that restriction.

The search returns at most five results, and it drops any result whose score falls below five. A node can therefore receive nothing at all when the match is weak. Narrowing the search to a Search Blueprint keeps unrelated content out of those five results.

The field controls this search and nothing else. It has no effect on the agent’s data sources. A node on an agent with data sources attached answers from them whether the field is set or not. If the agent has no data sources and the field is empty, the node answers from the prompt and the user message. When the agent runs inside a chat session, the node also sees that conversation’s history.

Tools

Configure the Tools section to give the node a built-in tool. Only one tool is available, image generation.

The section appears on LLM and AI Decision nodes and holds one field, which takes a JSON array. The image generation tool works on an LLM node only, and an AI Decision node ignores it.

Each entry is an object with externalReferenceCode and type keys. Set type to tool and externalReferenceCode to L_IMAGE_GENERATION, the only code the node acts on:

[
    {
        "externalReferenceCode": "L_IMAGE_GENERATION",
        "type": "tool"
    }
]

A tool entry with any other code is ignored without an error.

Passing Values Between Nodes

To move a value from one node to the next, declare it as a named workflow variable.

Important

Transitions set the order nodes run in and carry no data, and an AI Decision node’s choice of path is no exception. Every value a node works with comes from a variable it declares.

On the agent form, Input Variables names the values the agent receives and Output Variable names the value the workflow returns. From there, each node declares what it reads and writes. Input Variables and Output Variables live in the Prompt section on an LLM or AI Decision node, and in the Variables section on an HTTP Request node.

Both fields take a JSON array of objects, each with a name and a type:

[{"name":"tone", "type":"string"}]

type is string or json. A string variable substitutes as it stands. Set json when the value goes into a JSON payload, such as an HTTP Request node’s Payload field. The node then escapes the backslashes, quotation marks, line breaks, and tabs in the value as it reads it, so the payload stays valid JSON.

A bare variable name is not valid JSON. The field doesn’t parse, the node declares nothing, and the literal {{tone}} reaches the model instead of the value.

With that shape in hand, wire the values through:

1. Under Input Variables, list the variables the node reads. Give each one the name of a value already in the workflow.

2. Reference a declared variable inside the node’s other fields by wrapping its name in double curly braces.

   In an LLM node whose Input Variables include text, a User Message reading Translate this text to Spanish: {{text}} sends the agent’s text value to the model.

3. Under Output Variables, name the node’s result. A later node reads that result by declaring the same name under its own Input Variables.

Only the first entry in Output Variables is written back, so a second entry never reaches a later node.

A node substitutes only the variables you’ve declared in its Input Variables. Anything else stays literal, so an undeclared {{text}} reaches the model as those exact characters. Declare a variable in every node that references it.

For a worked example, see Building a Custom Agent.

The Liferay Search Agent

Liferay’s out-of-the-box Liferay Search agent answers questions from the content in the connected Liferay DXP instance. Its workflow is a Start node, one LLM node, and an End node. The agent takes request in and returns response.

The LLM node’s Prompt section holds these values:

Field	Value
Prompt	You are the Liferay Knowledge Assistant, a specialized AI agent designed to assist users by retrieving accurate information specifically from the Liferay Digital Experience Platform (DXP) instance or using the chat history. Your tone is professional, helpful, and concise.
Input Variables	[{"name": "request", "type": "string"}]
Output Variables	[{"name": "response", "type": "string"}]
User Message	{{request}}

Its Retrieval-Augmented Generation section sets the liferay content retriever:

{"contentRetriever": {"key": "liferay"}}

Its Tools section holds an empty array, so the node uses no tools.

Related Topics

• Agents
• Building a Custom Agent
• Workflow Nodes
• Workflow Designer Overview