Embedding Agents

Embedding Agents

Agent4API can expose a fixed Agent as a small floating logo and chat panel on an existing site. The host adds one generated script; it does not need to adopt Agent4API's framework, login system, or API client.

Configure the public address

Open System settings in the administration page and set System Base URL to the externally reachable HTTPS address, for example https://agent.example.com. The value is used to generate scripts, iframe URLs, and the recommended OAuth callback. A trailing slash is removed automatically.

When Base URL is missing, Embed configurations may still be saved, but script copy is disabled.

Create an Embed configuration

Open Agents, select a saved Agent, and use Embedded chat. Each Agent may have multiple site-specific configurations. Configure:

• a recognizable configuration name;
• bottom_right or bottom_left logo position;
• whether the configuration is enabled;
• exact allowed host origins such as https://portal.example.com.

Origins contain only scheme, host, and optional port. Paths, wildcards, credentials, query strings, and fragments are rejected. An empty list permits any framing origin and should be used only for intentionally public Agents.

Copy the generated snippet into the host page:

<script src="https://agent.example.com/embed/PUBLIC_ID.js" async></script>

The script renders the Agent4API logo in an isolated Shadow DOM. Clicking it opens an iframe fixed to that Embed's Agent. The host does not choose or override the Agent.

Runtime sequence

1. The host downloads the public loader.
2. The loader creates the logo and an iframe with allow="tools".
3. The iframe and loader perform an exact-origin initialization handshake.
4. Agent4API creates an anonymous Embed Session bound to the Embed, Agent, and parent origin.
5. The Widget connects to the Agent endpoint through AG-UI and streams the answer.
6. If the Agent selects a host WebMCP Tool, the Widget bridges that call to the host capability and sends its result back into the same Agent run.
7. If a backend Tool needs upstream authorization, the Widget asks the user to authorize it in a top-level popup and then resumes the conversation.

Revocation and changes

Disabling or deleting an Embed prevents new public sessions. Disabling or deleting the bound Agent also makes it unavailable. Existing Embed Sessions remain constrained by their idle and absolute expiry and cannot switch to another Agent or parent origin.

Changing the Base URL regenerates the snippet returned by the administration API. Replace older snippets if the deployment origin changed.

Troubleshooting

• The script copy button is disabled: configure System Base URL.
• The logo never appears: verify the script URL, Content Security Policy, ad blockers, and that the Embed is enabled.
• The iframe reports unavailable: verify the Agent is enabled and the browser's exact location.origin is allowed.
• The iframe is blocked: inspect frame-ancestors; do not add host paths to the origin list.
• A protected Tool asks for authorization: this is expected; follow Authentication.
• A host page Tool is not visible: see WebMCP. Absence is silent by design.