Agentic Apps – Message Hints

A practitioner’s guide to the $OraMessageHint signal — what the hints are, how they work, when each one fires, and which one to design for.

What Is a Message Hint?

In an agentic app, a single agent does many different jobs. The same agent might write a one-line summary at the top of the screen, render a chart in a dashboard tile, suggest a few priority actions, answer a typed question, and draft an email — all within one session. The app needs a way to tell the agent which of those jobs it is being asked to do at any given moment. That signal is the message hint.

Every time the app calls an agent, it attaches a hint value. The agent reads it from $context.$app.$OraMessageHint and responds accordingly. Think of it as the app’s shorthand: a small label that says “right now I need a summary,” or “right now the user clicked an action button — handle it.”

Because the hint carries this intent, you don’t build a separate agent for every screen element. You build one agent that recognizes the hint and branches its logic. This is what makes the capability “built in, not bolted on” — the orchestration is part of the framework, not something you wire up by hand.

How It Works

The mechanism is intentionally simple. On every request to an agent, the framework populates $context.$app.$OraMessageHint with one of a fixed set of values. Your agent’s workflow inspects that value and routes to the node that produces the right kind of output.

You read the hint in an expression as {{ $context.$app.$OraMessageHint }}, or inside a Code node as $context.$app.$OraMessageHint.

The Ten Message Hint Values

There are ten hint values, and they fall into two natural families. Initialization hints fire automatically the moment an app loads. Interactive hints fire later, in response to what the user does.

Complete Reference

When Are Hints Triggered?

Hints arrive in a predictable rhythm. Understanding the sequence is what lets you design prompts that respond to the right trigger at the right time.

Startup: the five initialization hints

After initialization: the interactive hints

Once the app is live, the remaining hints fire in response to user activity. Each one carries its own piece of context so your agent has what it needs to respond.

When to Use Which Hint

Since the framework chooses the hint, “using” a hint really means deciding which hints your agent should handle, and what each handler produces. Use this as a design checklist when building an agent for an app.

• Want a headline number or status line at the top? Handle Summary (and InitSubtitle for the tagline).
• Want charts, cards, or record views on first load? Handle InitDisplay and select the widgets the agent may produce.
• Want the app to suggest next steps? Handle InitActions to surface priority insights, and InvokeAction to process the click when the user takes one.
• Want the user to ask free-form questions? Handle Query, and make the agent’s description specific so the orchestrator routes the right questions to it.
• Need the app to draft a message? The communication hints (InitCommunications, FillParameters, SendCommunication) cover that — see the reference table above.
• Want expandable detail panels? Handle AdditionalContent and branch on $OraPanelName.

A Closer Look: InitDisplay and InitActions

These two initialization hints do the heavy lifting of an app’s first screen. InitDisplay builds what the user sees; InitActions tells them what to do about it. Both reward careful configuration, and both follow the same shape: enable the feature on the agent, write a specific prompt, and return the right structured output.

InitDisplay — building the initial view

When the hint is InitDisplay, the agent returns one or more oraInfoDisplay blocks. Each block carries a key attribute plus a small JSON payload describing what to render.

InitActions — surfacing what to do next

When the hint is InitActions, the agent’s workflow must produce one or more oraInsight entries — each a suggested next step the user can act on with a single click.

The Context That Travels With Each Hint

Hints rarely arrive alone. The framework also populates context variables that give the agent what it needs to respond. These are the ones you’ll reach for most often.

Putting It Together: the Routing Pattern

The standard way to build an agent for an app is a single workflow that branches on the hint. A Switch node reads $context.$app.$OraMessageHint and routes each request to the handler that produces the right output.

/* Route based on $OraMessageHint */

if  $OraMessageHint == "Summary"
      -> summary generation node
if  $OraMessageHint == "InitDisplay"
      -> initial display node
if  $OraMessageHint == "InitActions"
      -> actions generation node
if  $OraMessageHint == "Query"
      -> query handler  (include $chatHistory)
if  $OraMessageHint == "InvokeAction"
      -> action handler  (use $OraAction for context)

Things to Remember

• Don’t try to trigger hints. The framework fires them based on the app lifecycle and user activity. Design your agent to recognize and respond.
• Branch on the hint in one workflow. A single agent with a Switch on $OraMessageHint is the intended pattern — not a separate agent per behavior.
• Pass chat history yourself for queries. The user’s question and prior turns are separate; include both for coherent follow-ups.
• Expose the agent first. Enable Expose to Agentic Apps on the Output Tab and select widgets, or the agent won’t appear in the app builder.
• Write specific agent descriptions. Orchestrator routing for Query depends on them.
• Invest in InitDisplay and InitActions. They build the first screen and tell users what to do next. Select widgets, write specific display and action prompts, and pair InitActions with InvokeAction.