One Assistant per Portal: Runtime and Rendering Boundaries for Embedded HENGSHI Data Agent

Abstract: Many SaaS portals embed a HENGSHI dashboard in an iframe while deploying their own Copilot in the portal’s right sidebar. Users then see two entry points, two conversations, and two contexts: the parent-page assistant knows the business page, while the iframe assistant knows the charts. Users do not know which assistant to ask when selecting “intelligent interpretation,” and engineers struggle to locate failures in authentication, cross-origin communication, conversation execution, or chart rendering. This article uses an embedded-dashboard SaaS portal to explain how the parent-page Copilot JS SDK can take over the iframe’s assistant, separating execution modes, rendering, permissions, and backend orchestration into verifiable boundaries. The integration baseline is the 6.2 developer manual, which is not presented as the latest version.

1. Define the target boundary from the two-assistant problem

Imagine a customer operations portal with order, customer, and support-ticket modules. A HENGSHI dashboard runs in an iframe in the middle of the page, and a data-questioning sidebar sits on the right. Without unified takeover, the parent assistant and iframe dashboard maintain their own entry points and conversations. Selecting “interpret” on a dashboard chart opens an iframe Copilot; asking another question in the right sidebar starts a separate parent-page conversation. The assistants may serve the same signed-in user without sharing the visible context of the same interaction.

This is more than duplicate UI. A parent-page Agent cannot treat iframe content as its own DOM to click, drag, or navigate. The dashboard must expose readable, interpretable, and editable business actions and objects through a bridge. If both assistants process the same dashboard in parallel, troubleshooting also faces two execution logs and event chains without a clear starting owner.

Write the product constraint first: one portal page has only one visible assistant entry point and conversation container. The dashboard retains business data and chart context; the parent page hosts Copilot. Dashboard actions such as “open assistant,” “intelligent interpretation,” and chart interpretation enter that same parent-page Copilot. This constraint establishes an acceptance condition for runtime, rendering, and security design.

2. Separate who advances the conversation from who hosts the UI

Integration discussions often treat iframe, JS SDK, and API as mutually exclusive product modes. They actually describe how capabilities are integrated. A separate question is who continuously advances a question-and-answer interaction. HENGSHI documentation distinguishes Agent mode from Workflow mode: the former retains the process of ongoing execution, state changes, tool calls, and result production; the latter is advanced by a backend workflow service, while the frontend requests execution, reads status, and displays results. Data Agent integration overview Teams should assign responsibility along each axis separately.

Integration and display form	Ongoing execution in Agent mode	Ongoing execution in Workflow mode	Portal team’s boundary
Complete ChatBI iframe	Agent runtime in the embedded page	HENGSHI backend workflow service	Embedding, authentication, and page container; reuse the complete chat and result experience
JS SDK: new Copilot(...) or Copilot.renderChat(...)	Agent frontend capabilities embedded in the page	HENGSHI backend workflow service	Page shell, entry point, mount container, and business flow; reuse chat or individual-result rendering
Parent-page JS SDK + dashboard iframe	Parent Copilot accesses the dashboard through business actions proxied by the iframe	HENGSHI backend workflow service advances the selected Workflow; parent SDK hosts entry and results	Keep only the parent assistant, configure safe communication, and ensure authentication and resource authorization on both sides; do not infer browser-Agent editing capabilities as Workflow defaults
Backend API integration	Node.js Agent service deployed by the portal	HENGSHI backend workflow service	Backend orchestration, business contract, presentation, and observability; establish the execution mode before designing the interface chain

“API” identifies an integration location, not an execution mode. For backend integration that retains Agent behavior, the documentation describes a Node.js Agent service. For execution centrally hosted on the backend, select the Workflow service. This distinction prevents teams from “using an API” while still being unable to identify who handles retries, state advancement, and service recovery.

3. Let parent-page Copilot take over the dashboard iframe

This scenario does not need two chat windows. Load HENGSHI Copilot JS SDK in the parent page and create one Copilot instance in the portal’s DOM. The iframe continues loading the real dashboard URL, adding agentHost=parent and parentOrigin. The former declares that the parent page hosts the assistant; the latter specifies the allowed parent origin. Documentation requires an origin containing only scheme, host, and port, without paths, query parameters, or wildcards.

The configuration fragment below assumes the integrator supplies hengshiHost, appId, dashboardId, and dashboardFrame, then assigns the resulting URL to the iframe.

const dashboardUrl = new URL(`/app/${appId}/dashboard/${dashboardId}`, hengshiHost);
dashboardUrl.searchParams.set('agentHost', 'parent');
dashboardUrl.searchParams.set('parentOrigin', window.location.origin);
dashboardFrame.src = dashboardUrl.toString();

After the parent loads the SDK and the iframe declares takeover through those parameters, communication is established automatically. The iframe stops displaying its own Copilot sidebar. Dashboard entry points for “open assistant,” “intelligent interpretation,” and chart interpretation instead open parent-page Copilot. The parent does not need to register iframe DOM as operable nodes manually. When the Agent reads chart context or submits dashboard changes, it uses business actions and objects exposed by the iframe, including documented bridge operations for reading, inspecting, or submitting object changes. The iframe integration guide explicitly excludes parent-page clicks, drags, or navigation targeting iframe elements from this takeover mechanism.

The portal must also unify presentation. Only the parent page displays the sidebar, while dashboard buttons pass the current chart, dashboard, or action intent to parent Copilot. Do not leave a second chat panel in the iframe or send the same question to both conversations. When a user moves from reports back to orders, the portal can hide or show the same Copilot instance rather than repeatedly destroying and recreating it.

4. Bridging supplies context, not authentication or resource permission

parentOrigin has a narrow responsibility: the iframe accepts parent-page messages only from that exact origin. It creates no login session, grants no dashboard access, and does not automatically map the portal’s business tenant to HENGSHI resource permissions. The portal must ensure that both the iframe page and parent SDK can access HENGSHI interfaces as the current user. A project may use existing single sign-on or complete login according to its authentication design. The user must also have read access to the target dashboard and charts.

Check “the same user” at three levels: the portal session exists, HENGSHI authentication is available, and the user has dashboard access in the current tenant. A blank chart or 403 at the third level must not be treated as successful bridging. If the iframe uses sandbox, configuration must allow scripts and same-origin capabilities. CSP or X-Frame-Options can also block embedding if the HENGSHI site rejects the portal. These are prerequisites for embedding; do not bypass them through permissive communication in Copilot code.

Conversation boundaries also need explicit constraints. The Data Agent sidebar suits continued analysis, creation, interpretation, and editing around the current page. Standalone ChatBI is better suited to an entry point that continuously produces charts and dashboards through data questions. A portal can choose its primary entry point, while exposing only parent Copilot on the same page. In Agent mode, switching pages or historical conversations during an ongoing interaction interrupts execution. Demonstrations and troubleshooting should retain the current conversation and page. The Data Agent and ChatBI FAQ documents this execution limit and troubleshooting materials.

5. Separate backend orchestration from frontend rendering

The parent SDK offers two display granularities. new Copilot(...) mounts the complete chat window, including messages, input, recommended questions, chart results, and conversation interaction. Copilot.renderChat(...) embeds an individual question-and-answer result in a business module. Both retain the portal page shell while reusing HENGSHI frontend capabilities. The JS SDK guide also states that it does not convert HENGSHI responses into a portal’s custom chart protocol.

This boundary directly affects technical choices. Teams rendering results in an existing ECharts container must not assume backend responses are standard ECharts options. Define a result model, field validation, and conversion layer in the interface contract, and own chart compatibility and interaction testing for the custom renderer. Teams wishing to reuse HENGSHI conversations, charts, and result cards should use JS SDK rendering, avoiding a second chart semantics and conversation UI implementation.

Backend APIs suit teams with an existing AI gateway, multi-Agent system, or workflow orchestrator, but API integration must not imply a particular execution mode. This article describes Node.js Agent and Workflow backend-service responsibilities only from the 6.2 overview. It does not provide specific REST paths, request fields, or response fields. Implementation teams should establish backend contracts and rendering adaptation from documentation for the deployed version before freezing calling code and error handling.

6. Test the responsibility boundaries

Include these cases in portal integration checks. They are a testing architecture proposed here from publicly documented capabilities, not a product promise of an automated test suite.

1. Context switching between dashboards: Open dashboards A and B in the same portal and enter parent Copilot through each chart’s interpretation action. Check that every request’s chart and dashboard context comes from the current iframe and that only one sidebar remains visible.
2. Conversation and page restarts: Refresh the parent, close and reopen Copilot, and switch the iframe URL during execution. Record whether the ongoing interaction stops, whether history recovers according to product design, and whether a restart incorrectly inherits the previous dashboard’s context.
3. Incorrect origin configuration: Change the scheme, port, or host separately, or supply a path in parentOrigin. Expect no fallback to permissive communication, and use the console to identify why communication was rejected.
4. Unauthorized tenants and resources: Enter the portal as a user without read access to the target dashboard. Verify an actionable authorization failure and ensure the Agent cannot read chart objects or submit changes through the bridge.
5. SDK rerendering and custom data presentation: Send the same interaction to Copilot.renderChat(...) and the portal’s own data view. Test HENGSHI result-card and chart rerendering in the former, and the custom adapter’s fields, empty results, and error states in the latter. Do not treat this as an equivalent test of ECharts options.
6. Service-failure separation: Collect conversation-card execution logs, failing browser Fetch/XHR responses, system DEBUG logs, and real-time debugging exports together. Distinguish model, retrieval, permission, data, frontend communication, and backend service failures with that evidence.

7. Version baseline and delivery judgment

Capability statements here use the 6.2 SDK overview, JS SDK, and iframe integration manual as their baseline. Official release records show that 6.3.2 was publicly released on September 23, 2026. Project documentation should therefore state the actual deployed SDK and service versions, and rerun cross-origin, conversation, and permission cases before upgrades. Do not treat 6.2 examples as defaults for every later version.

Documented capabilities: Parent-page Copilot takes over dashboard iframes using agentHost=parent and exact parentOrigin; JS SDK provides complete chat and individual-result rendering; Agent and Workflow are execution modes independent of iframe, JS SDK, and API integration. Engineering recommendations in this article: Organize portal code and tests around “one visible assistant, authentication on each side, and business context passed through the bridge.” Decide custom backend and chart-rendering approaches only after obtaining valid API contracts.

HENGSHI’s view: Embedded Data Agent integration requires one assistant operating within correct page, conversation, permission, and rendering boundaries, beyond simply adding a chat window. Parent-page takeover gives users a single entry point and helps engineers assign each failure to an inspectable responsibility.