Agentic Workforce ME Developer PortalDocs 1.1 · Widget 0.1.0

Getting started

Quickstart

Create an embed key in the console, paste one script tag, see it work in five minutes.

Three steps

  1. Create an embed key in the console

    Open the console, go to Agents → your agent → Embed tab and click New embed key.

    • Name — e.g. “Marketing site”.
    • Allowed origins — the exact origins that will host the widget, one per line: https://www.acme.com, http://localhost:5173. Origins are exact — scheme, host and port must match; no paths. An empty list allows nothing (every request is 403 EMBED_ORIGIN_DENIED). The single wildcard entry * allows every origin — use it only while prototyping.
    • Identify signed-in users — leave off for now; see identified users later.

    Click Create key. The publishable key (hive_pk_…) is shown once — copy it. You can always rotate it later; you cannot read it again.

    Optional: in Configure → Appearance set the brand color, position and corner radius; in Text & language set the welcome message and the language. Everything here is stored server-side and applied to every page that uses the key on its next load — you do not need to redeploy your site to restyle the widget.

  2. Paste the script tag

    The Install section of the key shows a ready snippet. It looks like this — put it anywhere in your HTML (the end of <body> is conventional):

    index.htmlHTML
    <script async
  src="https://console.agenticworkforce.me/embed/v1/hive-embed.js"
  data-key="hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY"></script>

    The src origin is the platform origin that serves the widget bundle (https://console.agenticworkforce.me for the hosted platform). The loader infers apiUrl from it, so you only ever pass the key.

  3. See it work

    Reload your page from an allowed origin. A launcher bubble appears at the bottom corner; click it, type a message, and the agent’s reply streams in. Reload again — the conversation is still there.

npm / ESM variant

If you bundle your front end, install the package and initialize programmatically. Because the script did not come from the platform origin, pass apiUrl explicitly.

Shell
npm install @hive/embed   # or vendor /embed/v1/hive-embed.mjs
main.tsTypeScript
import { HiveChat } from '@hive/embed';

const chat = HiveChat.init({
  key: 'hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY',
  apiUrl: 'https://console.agenticworkforce.me',
});

// chat.open(); chat.send('Hello'); chat.destroy();

See Installation for React, Next.js, Vue and Angular.

Verification checklist

CheckHow
Bundle loadscurl -I https://console.agenticworkforce.me/embed/v1/hive-embed.js → 200 with etag, cache-control, content-type: application/javascript.
Key resolvescurl https://console.agenticworkforce.me/v1/embed/config -H "X-Hive-Embed-Key: hive_pk_…" -H "Origin: https://www.acme.com" → 200 JSON with agent.name.
Origin allowedBrowser devtools → Network → the config request is 200 and, after you open the panel, the session request is 200 with access-control-allow-origin equal to your origin.
Reply streamsruns/…/events request stays open with content-type: text/event-stream and llm.delta frames arrive.
Run is governedConsole → Runs shows the run with origin Embedded widget.

Common mistakes

The API omits Access-Control-Allow-Origin on a denial, so the browser console shows only a generic CORS / network error. The problem+json code is visible in the devtools Network tab (response body) or with curl. After fixing a key or origin problem, reload the page: a widget that failed its setup stays in the offline state until the next load.

SymptomCauseFix
Console: CORS error; Network tab: 403 EMBED_ORIGIN_DENIEDPage origin not on the key’s allowlist (port or scheme mismatch is the usual culprit), or the list is empty.Add the exact origin under Allowed origins. Compare window.location.origin with the list character by character. Reload.
401 EMBED_KEY_INVALIDKey was rotated or revoked, or is truncated in your snippet.Paste the current key from the console (rotation invalidates the old key immediately) and reload.
401 EMBED_KEY_DISABLEDKey is paused (“Key enabled” switched off).Re-enable it in the console, then reload the page.
Widget never appears; console shows a CSP violationYour page’s Content-Security-Policy lacks the platform origin.Add script-src and connect-src for the origin. See CSP.
409 AGENT_NOT_PUBLISHEDThe agent bound to the key has no published version.Publish the agent in the console.
409 EMBED_RUN_IN_FLIGHT on sendA previous message in this thread is still running.Wait for run.completed / run.failed; the widget already disables the composer while a run is active.
Messages send, nothing comes backA proxy in front of the platform buffers the SSE stream, or the worker is down.Disable response buffering for /v1/embed/; check the run in the console.