How to Embed an AI Agent in Your App: Widget, SDK, and API

Three ways to embed: widget, SDK, or REST API

Pick the surface based on how much control you need over the UI and where the agent has to run. Most teams start with the widget for a pilot, then graduate to the SDK once design and product want the agent woven into a real screen. The API sits underneath both and is the right tool when there is no front end at all.

A quick way to decide: if you want an agent live this afternoon, use the widget. If the agent is a core feature your designers will own, use the SDK. If you are calling the agent from a backend service, a webhook handler, or a cron job, use the REST API.

• Embeddable widget: a small script tag loads a self-contained chat panel, so you ship an agent without touching your component tree. Use it when speed matters more than pixel-level control, like a help launcher on a marketing site or an internal tool.
• React SDK: hooks and components let you render the conversation, message list, and input inside your own design system. Use it when the agent is a first-class feature and you need custom states, theming, and placement.
• REST API: a plain HTTP interface to send a message and stream or poll the reply, with no UI assumptions. Use it for server-side calls, mobile apps through your own backend, or automation that runs without a person watching.
• Mix and match: nothing stops you from running the widget on public pages and the SDK inside the authenticated product, both pointed at the same agent and the same permission model.
• Why this matters: the surface you choose changes the developer effort but not the security model. The JWT handshake is identical whether the request comes from a widget, an SDK component, or a backend call.

How an embedded agent request flows, end to end

An embedded AI agent does not talk to your database directly. The request travels through your backend, picks up a short-lived identity token, and only then reaches the agent, which uses that token to decide what the user can read and do. Seeing the whole path makes the security model obvious and removes the temptation to take shortcuts.

The flow below is the same regardless of surface. The widget, the SDK, and an API caller all start by asking your backend for a token. Nothing about your internal systems is exposed to the browser, and the agent never receives long-lived credentials.

Step by step: embed the widget first

The widget is the shortest path to a working agent, and it doubles as a test harness for your auth setup. Get it answering questions as the correct user, and you have proven the part that everything else depends on. Here is the sequence most teams follow.

• Create the agent and connect a data source. Point the agent at the tool it needs, like Salesforce or Zendesk, so it has something real to act on instead of canned replies.
• Add a token endpoint to your backend. When a signed-in user loads the page, your server returns a short-lived JWT carrying that user's ID and scopes. This endpoint must require a valid session.
• Drop in the widget script and hand it the token. The widget calls your endpoint, attaches the token to its requests, and renders the chat panel. No agent secrets ever live in the browser.
• Ask a question that requires identity. Try something like 'show me my open deals' and confirm the agent returns this user's records, not a global list. If two test users see different data, your scoping works.
• Turn on approvals for write actions. Before the agent can update a record or send a message, require a human to approve it, so your first writes are supervised.
• Check the audit log. Every action the agent took should appear with the acting user, the tool, and the result. If it does not, stop and fix it before you ship.

Why the short-lived JWT is the whole game

The single most important decision when you embed an AI agent is how the agent learns who the user is. A short-lived JWT solves this cleanly. Your backend, which already knows the authenticated session, signs a token that names the user and lists what they can access. The token expires quickly, so a leaked one is useful for minutes, not forever.

This is what lets the agent enforce least-privilege access. A support rep's token should not grant the ability to read the finance team's data, and the agent honors that because the permissions ride along in the token. The browser never holds a static API key, and you never ship a shared service account that can see everyone's records.

There is a deeper benefit. Because identity is carried per request, the audit log can attribute every read and every action to a real person. When a deal gets updated or a ticket gets closed by the agent, you can answer who triggered it. That traceability is what makes an embedded agent safe to give real permissions, rather than a read-only toy.

If you only harden one thing, harden this. A detailed walkthrough lives in the post on authenticating an embedded chat widget with JWT, and the token claims are covered in the identity tokens docs.

Widget vs SDK vs API: which to use when

The three surfaces trade developer effort against control and reach. The table below scores them on the dimensions that usually decide the call. None is strictly better; they fit different stages and different parts of your app.

A worked example: embedding a support agent

Picture a B2B SaaS product with a logged-in customer named Priya, an admin at her company. Your team wants an AI agent inside the app's help panel that can answer questions and actually resolve issues, not just link to docs. Here is how the embed plays out.

Priya is already signed in, so the page asks your backend for a token. The backend checks her session, then mints a JWT that says she is Priya, an admin at her account, with permission to see her own organization's tickets and billing. The widget loads with that token and shows a chat panel in the help drawer.

Priya types: 'Why was I charged twice this month?' The agent uses her token to look up her account's invoices, finds a duplicate charge, and drafts a refund. Because refunds are a write action, the embed is configured to pause and ask a human on your team to approve. A support lead approves it, the refund is issued, and the agent tells Priya it is done. Every step, the lookup, the proposed refund, and the approval, lands in the audit log against Priya's request and the approver's name.

Notice what did not happen. The agent never saw another customer's invoices, because the token scoped it to Priya's account. No static API key sat in the browser. And the one risky action waited for a person. That is the difference between an embedded chatbot that talks and an embedded agent that does governed work.

Common pitfalls when embedding an AI agent

Most embedding problems are not about the chat UI. They show up the moment the agent starts acting on real data for real users. These are the ones that cause incidents and rework.

• Shipping a long-lived or shared token. If the browser holds a static key or a service account, every user effectively shares one identity and the agent cannot scope data per person. Always mint a short-lived JWT per session.
• Trusting the client to enforce permissions. Hiding a button in the UI is not access control. Permissions must ride in the token and be enforced where the agent runs, not in the front end.
• Letting the agent write without approvals on day one. Turning an embedded agent loose with create and delete rights before you trust it is how a bad refund or a wrong status update happens. Gate writes with human-in-the-loop approval first, then loosen.
• Skipping the audit log. If you cannot say which user triggered an action and what the agent did, you cannot debug, you cannot pass a security review, and you cannot give the agent real permissions safely.
• Forgetting token refresh. Short-lived tokens expire, which is the point. If you do not handle silent refresh, long sessions break mid-conversation. Refresh before expiry from the backend that holds the session.
• Treating prompt injection as someone else's problem. Embedded agents read content from CRMs, tickets, and emails, which can contain hostile instructions. Pair input handling with least-privilege scoping so a malicious record cannot make the agent exceed the user's permissions.

How much developer effort each path takes

Effort scales with how much UI you own and how much of the auth plumbing you build yourself. The chart gives a rough sense of relative integration time across the three surfaces, including the shared token endpoint you need regardless. Treat these as directional, since your stack and review process move the numbers.

Embedding for mobile and server-side flows

Not every embed lives in a web page. A mobile app, a backend workflow, or a scheduled task can all call the same agent through the REST API, and the identity model does not change. Your backend still mints the short-lived JWT; the only difference is where the request originates.

For mobile, do not embed agent credentials in the app binary. The app authenticates the user against your backend as usual, your backend returns a short-lived token, and the app calls the API with it. This keeps the same per-user scoping you get on the web and avoids shipping secrets that someone can extract from the app.

For server-side and scheduled work, the token represents the user or system the run is acting on behalf of. A nightly job that prepares each account manager's pipeline summary, for example, runs once per manager with that manager's scope, so nobody sees data they should not. The agent can deliver the finished result to Slack or Teams, and the audit log records each run against its owner.

A simple decision framework

Use this to choose without overthinking it. Default to the widget for a first version, since it forces you to prove the auth handshake with the least code. Move to the SDK when product wants the agent to feel native and own its own screen real estate. Reach for the REST API when the caller is not a browser at all.

Across all three, the rule is the same: never let the front end be the security boundary. The short-lived JWT, the per-user scope, the approvals on writes, and the audit log are what make an embedded agent something you can give real access to. The UI surface is a preference. The governance is not optional.

• Choose the widget when you want a working, scoped agent fast and can live with a prebuilt panel.
• Choose the React SDK when the agent is a core feature and your team needs full control over layout, theming, and states.
• Choose the REST API when there is no browser: mobile backends, server routes, webhooks, or scheduled runs.
• Choose more than one when public and authenticated areas of your product have different needs but share one agent and one permission model.

Once the surface is picked, the build is mostly the token endpoint plus a thin integration. Get identity right, prove it with two test users, and the rest is iteration.