Run an agent from your app’s UI

By the end of this page you will have a button in your app that runs one of your agents and shows its answer on the page.

The example used throughout is a simple notes app. A Note Summarizer Task Agent takes a note’s text and returns a two-sentence summary, and the note editor gets a button that runs it.

Prerequisites

• An app workspace with an active chat session (The generation flow).
• An active AI or Task Agent in the same project, without a human approval step (Which agents you can use).
• For a Task Agent, its End node’s Output Mapping defines what your app receives. An agent that maps one output, such as summary, hands your app that value directly. See End node.

Steps

Choose Agent Action and an agent

Open the integration dialog (see Open the integration dialog). Under Integration Type, click Agent Action (The browser calls it), then pick your agent under Select Agent.

Describe the action

Field	What to enter	Example
Purpose	What the action does. It also names the integration, so it can’t be changed later.	Summarize the note
Trigger Location	Where the control should go, in plain words	next to the Save button on the note editor
Allowed Roles	Which of your app’s roles may run it. Leave it empty for any signed-in user.	Editor
Execution Mode	Wait for result or Stream progress. Both deliver the result to the app.	Wait for result

Allowed Roles only appears as a choice when your app has sign-in turned on, and it lists the roles your app declares. If the app has no sign-in, the field explains that there’s no signed-in user to check a role against.

💡

Choose Stream progress for an agent that may take longer than about 50 seconds. With Wait for result, a published app stops waiting after that, before the result arrives.

Choose what triggers it

Trigger	What happens in your app
On click (button)	A button runs the agent. This is the default.
On page load	The agent runs when the page opens.
On field change	The agent runs shortly after a field stops changing. Name the field in Trigger Field, for example form.customerId.
Interval (poll)	The agent runs straight away, then repeats every Interval (ms). The default is 30000 (30 seconds).

Map the agent’s inputs

Input Sources lists every input the agent declares, one row each. For each, choose where its value comes from when someone uses the app:

Source	Use it for
What the user types	Text the person enters for this action
Something on the page	A value already on the page, such as a form field
From the URL path	Part of the page’s address, such as an id in /notes/42
From the URL query	A query parameter, such as ?status=open
The selected item	The row or card the person has selected
The signed-in user	A detail of the person who is signed in
A fixed value	The same value every time. Type it in the box.

Most sources have a second box. For A fixed value it holds the value itself; for the others it names the value to read, and defaults to the input’s own name. What the user types has no second box. In the example, the agent’s text input comes from Something on the page, with body as the value: the note’s body field.

ℹ️

An AI Agent has a single input, message. Map whatever the agent should act on, such as the note’s text, to message.

Choose how the result appears

Pick an Output Display:

Display	What it shows	Works with
Auto (fallback)	qRaptor picks a layout from the shape of the agent’s output	AI and Task Agents
Inline text	The result as a line of text on the page	AI and Task Agents
Card	The result in a bordered card. Suits an agent that returns several values.	AI and Task Agents
Streamed text	The agent’s reply appearing as it’s written, from a Prompt Template you write	AI Agents
Streamed chat	A small chat panel with the agent	AI Agents

For a single piece of text, like the example’s summary, choose Inline text.

Add the integration

Click Add Integration. The request appears in the chat panel as an Agent Integration card, and qRaptor builds it like any other change.

Try it in the preview

When the build finishes, open the Preview tab. If your app has sign-in, sign in with a role that’s allowed to run the action (see Preview your app).

With the On click (button) trigger, the page gets a button where you described it — in this example, Summarize, next to Save Changes. The button is disabled while the agent runs.

Click it. The result appears in the display you chose — here, the summary on the note editor.

What qRaptor builds

• The call to the agent. qRaptor writes this code itself, so it isn’t generated fresh, and it’s rebuilt whenever the integration changes. It sends the mapped inputs, waits for or follows the run, and hands the result to the page.
• The control and the result. The button or page event, and the display you chose, are added to the page you described. The rest of the page’s layout and wording is generated as usual.
• The connection to the agent. Your app is allowed to call this agent, and only this agent, through this integration. Calls go to the agent’s production version.

If a call can’t complete, the person using your app sees a short message in place of the result:

Common issues

• There’s no Input Sources section. The agent declares no inputs, so there’s nothing to map.
• Streamed text and Streamed chat are greyed out. They need an AI Agent. To follow a Task Agent’s run, set Execution Mode to Stream progress instead.
• The result shows {} or a block of text with braces. The agent returns several values, or none. Check the Output Mapping on its End node, and choose Card to show several values.
• Some people can’t run the action. They see You are not permitted to run this action., or the control is disabled for them, because they don’t hold one of the Allowed Roles. Sign in with an allowed role to check.
• An AI Agent’s answer ignores the page. Its message input isn’t mapped to the content it should act on. Edit the integration and map it (see Edit or remove an integration).