Data Agent Integration Overview
Do not start by choosing between iframe, JS SDK, and API.
The more important question is: how much of the experience do you want to keep in your own system, and where do you want HENGSHI to take over?
Data Agent does not expose just one thing. It exposes three layers of capability:
First: what HENGSHI can provide
1. Data Q&A capability
This layer is responsible for understanding the question, reasoning, querying data, generating the answer, and producing chart-related results.
This is the right layer when your own backend, multi-agent system, workflow, or AI gateway wants to call HENGSHI as a capability provider. The typical integration path is API Integration.
Key points:
- Best for backend orchestration and routing
- You can use
/chat/completionsand SSE to get progress and results - If you want to display text or cards inside your own frontend, that display responsibility is still on your side
2. Result rendering capability
This layer is responsible for rendering a Data Agent result into a user-facing card, chart, and interactive result experience.
This is the right layer when “the page shell is yours, but you do not want to build the result rendering yourself.” The typical integration path is JS SDK Integration.
Key points:
- You keep your own page, entry point, layout, and business flow
- HENGSHI renders the result card, charts, and answer experience
Copilot.renderChat(...)is suitable for embedding one result into a pagenew Copilot(...)is suitable for embedding a full chat window
3. Full page capability
This layer provides the complete ChatBI / Data Agent page as a ready-made product surface.
If you want the fastest path with the least frontend work, the typical integration path is iframe Integration.
Key points:
- Fastest to integrate
- HENGSHI owns the page, conversation flow, and result rendering
- You have the least control over the internal chat UI
The difference is not “which one has more features”
The real difference is the control boundary.
| What you want to keep on your side | What HENGSHI takes over | Recommended path |
|---|---|---|
| You keep routing, orchestration, and frontend presentation; HENGSHI provides only data Q&A capability | Question understanding, data retrieval, answer generation | API Integration |
| You keep your own page and entry point, but do not want to build result rendering | Result cards, charts, and rendering experience | JS SDK Integration |
| You want the fastest way to reuse the complete ChatBI page | Full chat page, conversation UI, result presentation | iframe Integration |
The three boundaries that are easiest to misunderstand
API is not “standard chart-rendering output”
If you call the API, what you get back is a Data Agent result protocol.
It should not be interpreted as:
- standard ECharts options
- a chart protocol your existing frontend can consume with zero adaptation
- a complete chart UI that works out of the box without HENGSHI rendering
JS SDK is not a “protocol-to-chart converter”
The JS SDK is an embedding method for HENGSHI’s frontend rendering capability.
It solves “embed HENGSHI’s rendering experience into your page”, not “convert HENGSHI protocol into your own chart protocol”.
iframe is not a deep frontend customization path
iframe is the fastest way to reuse the full page, but it is not the right approach if you need deep customization inside the chat UI.
How to choose
Ask yourselves three questions first
- Do you already have your own backend orchestration, multi-agent system, or AI gateway?
- Do you want to keep your own page and business shell?
- Are you willing to own result rendering and frontend adaptation yourself?
A simple decision rule
- Want the fastest full experience: read iframe Integration
- Want to keep your own page but reuse HENGSHI rendering: read JS SDK Integration
- Want to integrate HENGSHI as a backend data Q&A capability: read API Integration