I've recently been working on a project to create a Chatbot using AI Hub. Although the documentation at https://learn.liferay.com/w/ai-hub/integrating-ai-hub-with-liferay-dxp is very helpful at completing this task, there are some things that it leaves out. I thought these might be helpful to others, so I thought I'd share them here.

1. The building blocks (quick orientation)

When you're using AI Hub, you're going to be defining a bunch of different things:

Agent — a single task with its own workflow (a canvas of nodes). Built-in agents (Change Tone, Fix Spelling and Grammar, Improve Writing, Liferay Search, Make Longer, Make Shorter) are read-only; custom agents are yours to edit. An agent has input variable(s), one output variable, an optional set of data sources, and optional guardrails.

Instruction — a reusable block of guidance applied at runtime across many agents (tone, brand voice, policy). It carries a rule plus the response to give when the rule fires, and a scope (Everywhere / CMS only / Click-to-Chat only).

Guardrail — an enforced safety check that runs outside the model, so it holds even when a prompt tries to talk around it. Input guardrails screen the user message; output guardrails screen the model reply. Guardrails attach per-agent.

Data source — a crawled website (same domain, up to 3 link levels deep, max 500 pages) that agents query by semantic search. Attach to the agents that need grounded answers.

Supervisor (AI Assistant / Chatbot) — the router. The AI Assistant lives in the CMS editor; a Chatbot is a deployable widget scoped to a chosen set of Assigned Agents. Either one reads the request and routes it to the best-matching agent(s), and can combine agents for one request.

2. Agent vs. Instruction: which one to build

This is the most common design decision. The rule of thumb: an agent does work; an instruction shapes how all work is done.

Why it matters: instructions are defined once and reused, so they keep tone and policy consistent without editing each agent. Reserve new agents for genuinely new capabilities — every custom agent is a maintained asset (and, on some tiers, a limited one, e.g. up to five custom agents on Activate).

3. One forking agent vs. several agents the supervisor picks between

When a job has several branches (e.g. translate to Spanish, French, or German), you can build one agent with a large branching workflow, or several small single-purpose agents that a chatbot / the AI Assistant routes between. Prefer several focused agents.

Why separate agents usually win

• Routing is what the supervisor is for. The AI Assistant and chatbots already compare the request to each available agent and pick the best match — even combining two (translate + shorten) for one request. Small, clearly-described agents make that routing accurate.
• Descriptions drive selection. Each agent's title and description are how the supervisor decides. One giant forking agent has a single description, so the router can't see the branches inside it — a French request may never reach the French branch. Separate agents each advertise exactly what they do.
• Simpler workflows, easier testing. A focused workflow is easier to reason about, duplicate, and debug than one canvas with many conditional paths.
• Independent governance. Guardrails and data sources attach per-agent. Separate agents let you ground or lock down only the branch that needs it, instead of one agent carrying every rule.
• Permissions and reuse. Per-agent permissions and reuse across chatbots are cleaner when each capability is its own agent.

When a single forking workflow is justified

• The branches are internal steps the user should never pick between (e.g. detect language → normalize → translate as one pipeline).
• The branches share heavy setup (same data sources, same pre/post-processing) and splitting would duplicate a lot of workflow.
• You're near an agent-count limit and the branches are minor variations of one task.

Practical pattern: build one small agent per user-visible capability, give each a sharp description, assign the relevant set to a chatbot (or let the CMS AI Assistant see them), and let the supervisor route. Use forking inside an agent only for steps the user shouldn't have to name.

4. How to formulate an agent's prompt

An agent node has a Prompt (the LLM's standing instruction) and a User Message template that injects inputs via placeholders like {{text}}. Liferay's own example is a strong template — it works because it stacks four things:

• Role — "You are an expert translator." Give the model a clear persona.
• Scope — "Your sole task is to translate the provided text to Spanish…" State the one job and bound it.
• Edge cases — "If the text is already in Spanish, return it unchanged." Name the tricky inputs and say what to do.
• Output format — "Output only the translated text, with no explanations or commentary." Constrain the shape of the reply.

Recommendations: keep one job per agent (matches the routing model); write the prompt as standing behavior and put the variable content in the User Message template; reference inputs by their exact variable names; specify the output format explicitly (the supervisor may chain your output into another agent, so clean, comment-free output matters); and don't bake policy that belongs in a reusable instruction or a guardrail into the prompt.

Naming for routing: the description isn't decoration — it's how the supervisor finds the agent. Write descriptions that name the trigger and the result ("Translates text to French") rather than vague labels ("Language helper").

5. How to write instructions

• State both halves. Every instruction is a rule plus the response when it fires — e.g. "Do not provide financial advice. If the user asks for investment recommendations, reply that you aren't authorized to give financial advice." Don't write the rule without the fallback response.
• Scope deliberately. Set Where to Use — Everywhere, CMS only, or Click-to-Chat only — so a rule meant for the public chatbot doesn't reshape the authoring assistant.
• Use the trigger when it should be conditional. Leave When to Use blank to apply to all in-scope requests, or set a contextual trigger to fire only in specific situations.
• Write once, reuse. Put tone, brand voice, and cross-cutting policy in instructions rather than repeating them inside each agent prompt.
• Remember precedence. Liferay's read-only system instructions take priority and can't be overridden by custom instructions — design around them, not against them.

The precedence rule has another important interpretation. Liferay’s read-only system instructions are the system-level prompts, instructions represent the your system-level prompts. They combine to constrain the agents from going off the rails regardless of what their individual prompts might be.

6. Adjusting guardrails

Guardrails run through Google Cloud Model Armor, outside the model; use them for anything that must hold regardless of prompt wording. Instructions ask the model to behave; guardrails enforce.

Input guardrails (screen the user message)

• Malicious URI Filter — blocks harmful links.
• Prompt Injection and Jailbreak Filter — catches attempts to override the agent's instructions.
• Sensitive Data Protection — scans for and protects PII before it reaches the model.

Output guardrails (screen the model reply)

Set a Responsible AI threshold (None, Low and Above, Medium and Above, or High) for each of Hate Speech, Dangerous, Sexually Explicit, and Harassment. Higher categories block more aggressively.

Recommendations

• Attach selectively. Guardrails apply per-agent and each run adds cost and latency. Put strict input guardrails on public, user-facing agents (chatbots on external sites); lighter rules may suffice for internal CMS authoring agents.
• Pair input and output. Combine input screening (injection, PII, malicious links) with output screening (harmful/off-policy content) for full coverage.
• Tune thresholds to audience. Raise output thresholds for public deployments; relax them where over-blocking would frustrate trusted internal users.
• Enable multilanguage detection when non-English input is expected, so screening isn't limited to English.
• Use guardrails, not prompts, for safety. Because they sit outside the model, guardrails hold even when a prompt tries to talk its way around the rule. Never rely on prompt wording alone for security-critical limits.

7. Set External Reference Codes (ERCs) with business meaning

Every AI Hub component (agents, chatbots, instructions, and the rest) carries an External Reference Code (ERC), a unique identifier used for system identification. By default this is an opaque UUID. Even if the ERC isn't something you interact with much today, set it to a value that carries business meaning rather than leaving the generated UUID in place.

For an instruction that governs response formatting, for example, prefer an ERC like <PROJECT>-RESPONSE-FORMATTING over a random UUID. The convention is cheap to adopt and pays off in several ways:

• Readable and stable. A meaningful ERC is a durable, human-legible handle for the component: easier to reference in tickets, runbooks, and conversations than a UUID.
• Portable across environments. A deterministic, business-meaningful code lets you line up the same logical component across dev, test, and production instead of reconciling different generated IDs.
• Future-proofs for headless / API access. Plans for headless API access aren't confirmed, but if and when that day comes, a valid, well-chosen ERC is exactly the stable key an API call would target. Setting sensible ERCs now puts you ahead of the game rather than retrofitting them later.

Recommendation: adopt a simple, consistent ERC naming convention early, e.g. <PROJECT>-<COMPONENT-TYPE>-<PURPOSE>, and apply it to every agent, chatbot, and instruction as you create them, while the set is still small.

8. One-page cheat sheet

Conclusion

Hopefully these tips will help you make the most of your AI Hub agent building experience!

Leave a comment below if you have suggestions and/or questions.