Agentic Workforce ME Embed SDK · v1.0.1
Put a governed AI agent in your product with one script tag.
The Agentic Workforce ME embeddable chat widget is a small, dependency-free Web Component that connects your website or app to an agent running on the platform. Every conversation is a real, audited agent run: guardrails, human-in-the-loop approvals, knowledge bases and usage accounting apply exactly as they do in the console.
<script async
src="https://console.agenticworkforce.me/embed/v1/hive-embed.js"
data-key="hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY"></script>What the widget is
<hive-chat> is a custom element rendered inside a Shadow DOM, so its styles never leak into your page and yours never leak into it. It ships as a hosted script (/embed/v1/hive-embed.js) that auto-initializes from data-* attributes, as an ESM build for bundlers (@hive/embed), and as a thin React wrapper (@hive/embed/react). Vue, Angular, Svelte and plain WebViews use the custom element directly.
- Launcher or inline. A floating bubble that opens a panel (default), or a panel that fills any container you give it.
- English and Arabic with full RTL.
locale: "auto"follows<html lang>, then the browser language; message bubbles usedir="auto". - Streaming replies over Server-Sent Events, Markdown rendering, thread persistence across reloads, keyboard and screen-reader support, full-screen on phones.
- Anonymous or identified visitors. Anonymous by default; pass a backend-signed identity JWT to attach conversations to your logged-in users.
How it fits the platform
The widget is a client of the same platform your operators manage in the console. A tenant admin binds a publishable embed key to one published agent and to the origins allowed to load it. From then on, every visitor message becomes a run on that agent:
| Platform capability | What it means for the embedded chat |
|---|---|
| Agents & manifests | The persona, model, skills, tools and knowledge bases the widget answers with are the agent’s published manifest. Change the agent in the console; the widget follows on the next run. |
| Governance & guardrails | Guardrails, tool allowlists and rate limits apply to embed runs unchanged. Embed runs are flagged with origin “Embedded widget” on the Runs page. |
| Human-in-the-loop | If the agent hits an approval policy the run pauses; the widget shows “Waiting for a human” and resumes automatically once an operator decides in the console. |
| Audit & usage | Runs, steps and usage events are recorded per tenant. Identified session mints are audited (`embed.session`, a credential exchange); key create/rotate/revoke are audited too. |
| Contacts | Identified visitors are upserted as `end_users` (with PII tags) so the same person gets the same threads and memory across visits. |
Architecture
1 · Script loader
hive-embed.js reads data-*, infers apiUrl from its own origin, drains a pre-load queue, exposes window.HiveChat.
2 · Web Component
<hive-chat> renders in a Shadow DOM from the public config, mints a 15-minute session on first open or first send, restores the visitor’s thread, emits hive:* events.
3 · Public embed API
Origin-checked, rate-limited endpoints; per-key CORS. Session tokens are HMAC-signed and scoped to tenant, key, agent, origin and visitor.
/v1/embed/*4 · Agent run
A governed LangGraph run on the bound agent. Events are redacted and relayed as SSE: text deltas, anonymous tool activity, waiting/resumed, completed/failed — never tool names, arguments, results or costs.
runs · run_steps · usage_eventsThe browser only ever holds a short-lived session token, the visitor id and the current thread id. It never sees tenant API keys, identity secrets, tool credentials or raw run state.
Browser support
The bundle targets es2020, Chrome 90+, Safari 15+ and Firefox 90+ (Edge follows Chromium). It relies on Custom Elements, Shadow DOM, fetch with streaming bodies and AbortController (visitor ids use crypto.randomUUID with a getRandomValues fallback). Styles are attached with adoptedStyleSheets; browsers without constructable stylesheets (Safari before 16.4) get an equivalent <style> fallback inside the shadow root.
Screens narrower than 480 px switch the launcher panel to full-screen. The widget honours the page’s prefers-reduced-motion setting.
Bundle size
| Build | Path | Raw | Gzip |
|---|---|---|---|
| Script tag (IIFE) | /embed/v1/hive-embed.js | ≈ 38 KB | ≈ 12 KB |
| ESM | /embed/v1/hive-embed.mjs | ≈ 36 KB | ≈ 12 KB |
| React wrapper | /embed/v1/react.mjs | ≈ 37 KB | ≈ 12 KB |
Measured on build 0.1.0. Zero runtime dependencies; React is a peer dependency of the wrapper only. The bundle is served with Cache-Control: public, max-age=3600, stale-while-revalidate=86400 and an ETag.
Versioning policy
- Hosted URL = major line.
/embed/v1/receives compatible updates in place (bug fixes, new optional options and events). Breaking changes ship as/embed/v2/;v1keeps working. - Public API
/v1/embed/*follows the same rule: additive fields may appear in responses; existing fields, status codes and error codes do not change withinv1. - npm package
@hive/embedfollows semver;HiveChat.versionreports the loaded build (currently0.1.0). - Deprecations are announced in the changelog at least one release before removal.
Where to go next
Quickstart
Create a key, paste the tag, send a message — with a verification checklist.
Installation
Script tag, ESM, React, Next.js, Vue, Angular and WebView notes.
Authentication & security
Keys, origins, identity JWTs, session tokens, CSP, rate limits and the threat model.
REST reference
Every /v1/embed/* and /v1/embed-keys endpoint with curl examples.
Release
Documentation release 1.0.1 · bundle build 0.1.0 · see the changelog.