Embeds

The Embeds page at /embeds turns one of your agents or swarms into an iframe you can paste into any website. Each embed has its own API key, its own daily request cap, and a list of domains it is allowed to load on. There are two flavours:

• Agent embed — a streaming chat panel. Visitors send messages, the agent replies in real time using its full brain (tools, RAG, guardrails, memory).
• Swarm embed — a run-and-return task panel. Visitors describe a task, the swarm runs server-side end to end, and the final output is shown when it finishes.

Create an embed

• Open Embeds and click New embed.
• Pick the type (Agent or Swarm) and choose one of your own agents or swarms as the target.
• Give it a name, an optional accent colour, a greeting line, and an input placeholder.
• List the allowed domains that may load the widget — one per line, e.g. example.com. Requests from any other origin are rejected.
• Set a daily request cap per embed. Once the cap is hit, further requests return 429 for the rest of the day.

Install the widget

The create dialog gives you a ready-to-paste snippet. It looks like this:

<iframe
  src="https://agentswarms.fyi/embed/EMBED_ID?key=sk_embed_xxx"
  width="420"
  height="640"
  style="border:0;border-radius:16px;box-shadow:0 8px 40px rgba(0,0,0,.12)"
  title="AgentSwarms widget"
  allow="clipboard-write"
></iframe>

Drop it into any HTML page on one of your allowed domains. Optional query parameters:

key

Required. The sk_embed_… key for this embed.

theme

light, dark, or auto (default). Forces the widget's colour scheme independently of your parent page.

How it works

• Anonymous visitors. Nobody signs into AgentSwarms. The widget mints a stable session token per browser and stores it in the iframe's localStorage, so returning visitors resume the same session.
• Domain lock. Every request checks the browser's Origin against your allowed-domains list. Requests from other origins are rejected before any model call.
• Full agent brain. Agent embeds stream through the same tool loop, RAG retrieval, memory, and guardrails as the Playground. Swarm embeds execute the same graph as Swarm Canvas runs.
• Runs on your account. Model calls are billed to your AgentSwarms usage, not the visitor's. The daily cap is your circuit breaker.

Manage, rotate, delete

Back on /embeds, each embed row shows its key prefix, allowed domains, daily cap, and status. From there you can:

• Rotate the key — issues a new sk_embed_… and instantly invalidates the old one. Update the key= in your embed snippet after rotating.
• Edit allowed domains, theme, and cap — takes effect on the next request; no re-install needed.
• Delete — removes the embed and revokes its key. Existing iframes will stop working.

A note on the URL

Always point the iframe at the published domain — agentswarms.fyi or your custom domain. Preview URLs (anything with id-preview--) are gated by the Lovable preview login and will show a sign-in wall inside the iframe.

Common issues

• "Origin not allowed" — the parent page's domain isn't in the allowed-domains list. Add it (exact host, no protocol) and reload.
• "Daily cap reached" — raise the cap on the embed, or wait until UTC midnight for the counter to reset.
• Sign-in wall inside the iframe — you're pointing at a preview URL. Switch the src to the published domain.