Agent integrations overview
By the end of this page you will know the four ways to connect an agent to a generated app, which one fits your need, and which agents you can use.
What an agent integration is
An agent integration connects one of your project’s agents to a Web app you’re building with Vibe Coding. qRaptor writes the code that calls the agent, wires it into your app, and routes every call to the agent’s production version.
There are four types, in two groups.
Chat surfaces give people a conversation with an agent. They work with AI Agents only.
| Type | What it adds |
|---|---|
| Floating Chat | A chat widget over some or all of your app’s pages |
| Chat Page | A dedicated page with a full chat interface |
Callable types run an agent as part of what your app does, and use the result. They work with AI Agents and Task Agents.
| Type | Who calls the agent | What it adds |
|---|---|---|
| Agent Action | The browser | A button or page event that runs the agent and shows the result on the page |
| Backend Call | Your app’s server | A function your app’s own server code calls, with no one watching the screen |
Which one do you want?
| You want… | Use |
|---|---|
| A help assistant people can open from any page | Floating Chat |
| A page whose whole purpose is a conversation | Chat Page |
| A button that runs an agent and shows the answer, like Summarize on a note | Agent Action |
| Something to happen on its own when data changes, like tagging every note when it’s saved | Backend Call |
An Agent Action happens in front of the person using the app. A Backend Call happens on the server, so the browser never sees the agent’s inputs or the call itself.
Which agents you can use
The agent must be in the same project as the app, and:
- Active, which means it has a version promoted to production. See versioning for Task Agents and AI Agents. Drafts aren’t offered.
- Free of human approval steps. An agent containing one appears greyed out in the picker, with the reason: Contains a human approval step — not supported in apps yet.
- The right type for the integration: AI Agents for chat surfaces, AI or Task Agents for the callable types.
Your app always calls a production version of the agent, never a draft. In preview, that’s whichever version is in production at the moment of the call. A published app keeps the version that was in production when you published it; publish again to pick up a newer one.
Open the integration dialog
In the app’s chat panel, click the + button (More options) next to the message box, then click Add agent integration.
The dialog is titled Agent Integrations. If the app has no integrations yet, it opens straight on the form to add one. Otherwise it opens on a list of the app’s integrations, where you can add another or change an existing one (see Edit or remove an integration).
Choose a type under Integration Type. The four cards sit in their two groups: Chat surfaces · AI agents only and Callable · AI or Task agents.
Then pick an agent under Select Agent. Each agent shows an AI or Task badge, and only agents that fit the chosen type are listed.
The app’s chat panel sometimes suggests Add Agent Integration as a next step. Clicking that suggestion opens the same dialog.
Common issues
- An agent you expected isn’t in the list. It isn’t active yet, or its type doesn’t fit the integration. Promote a version of it to production, and check the type you picked: chat surfaces list AI Agents only.
- An agent is greyed out. It contains a human approval step, which apps can’t run yet. Remove the step from the agent, or use one without it.
- Publishing fails with “Cannot deploy: the following embedded agent(s) have no PRODUCTION version”. An agent the app uses no longer has a production version. Promote one, then publish again.
- Publishing fails with “Cannot deploy: the following agent(s) have changed since this app’s code was generated against them”. The agent’s inputs or outputs changed after the integration was added, so the app’s code no longer matches it. Remove the integration and add it again, so the code is regenerated against the current version, then publish.