Call an agent from your app’s server

By the end of this page you will have an agent that your app’s server runs on its own, at a moment you describe, with the result stored by your app.

The example continues the notes app. A Note Tagger Task Agent suggests a few short tags for a note, and the app’s server runs it every time a note is saved, then stores the tags on the note.

When would you use this?

Use a Backend Call when the agent’s work belongs to your app’s own processing rather than to something a person clicks:

• It should happen automatically, such as tagging a note when it’s saved or summarizing an order when it’s created.
• The inputs shouldn’t reach the browser, such as data the person using the app isn’t allowed to see.
• The result should be stored, so it’s there the next time anyone opens the record.

If you want a button that runs the agent and shows the answer, use an Agent Action instead.

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).
• Somewhere in your app to keep the result, if you want it stored. In the example, notes have a tags field.

Steps

Choose Backend Call and an agent

Open the integration dialog (see Open the integration dialog). Under Integration Type, click Backend Call (Your server calls it), then pick your agent under Select Agent.

Describe the call

Field	What to enter	Example
Purpose	What the call does. It also names the integration, so it can’t be changed later.	Tag a saved note
When	When the call should happen, and what to do with the result	after a note is saved, store the result in the note's tags field

Describe when, not where. qRaptor picks the right place in your app’s server code from your description, even as the app’s files change between versions.

Add the integration

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

Try it in the preview

When the build finishes, open the Preview tab and do whatever your When describes. In the example, open a note, edit it and click Save Changes. Then reopen the note: its tags are filled in, and nothing in the browser called the agent.

What qRaptor builds

• A ready-made function for the agent. Your app’s server gets a module named after the agent, for example backend/src/agents/note_tagger.py, with a run() function. For a Task Agent, its parameters are the agent’s declared inputs, such as text. For an AI Agent, it takes the message to send. You can see it in the Code tab.
• The call itself, in the part of your server code your When describes. The generated code passes the inputs and uses the result, such as saving the tags.
• The connection to the agent. Calls go to the agent’s production version, in preview and once published.

How a Backend Call differs from an Agent Action

Common issues

• Nothing happens when you do what the When describes. Make sure the build finished, then reload the preview. If it still doesn’t run, edit the integration and make the When more specific, for example naming the page and the button (see Edit or remove an integration).
• The result isn’t stored. Say where it should go in When, as in the example’s “store the result in the note’s tags field”, and make sure that field exists in your app.
• There’s no Allowed Roles field. That’s expected. A Backend Call runs as the app, not as the signed-in person, so there’s no one’s role to check. Control who can trigger the underlying action, such as saving a note, in your app instead.