react-agent-remoter

面向 React 项目的 OpenTiny WebAgent 对话组件包。它基于 @opentiny/next-remoter 的 useNextAgent 做了 React 桥接，并提供两种使用层级：

• NextAgentWidget: 开箱即用的默认浮动聊天组件
• NextAgentProvider + NextAgentFloatingPanel: 逻辑层和默认浮动面板分层使用

官方文档

• OpenTiny useNextAgent 文档：use-next-agent

安装

npm install react-agent-remoter @opentiny/next-sdk @opentiny/next-remoter

接入前提

• 业务项目需要自行提供 llmConfig、agentRoot 和 model
• 如果要让智能体操控 Web 应用，需要先建立 WebAgent 会话并传入 sessionId
• apiKey 建议从环境变量或服务端下发，不要直接写死在业务代码中

最小用法

import { NextAgentWidget } from 'react-agent-remoter';

export function App() {
  return (
    <NextAgentWidget
      agentRoot="https://agent.opentiny.design/api/v1/webmcp-trial/"
      llmConfig={{
        apiKey: 'your-api-key',
        baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
        providerType: 'openai',
      }}
      model="qwen3.5-plus"
      title="业务 AI 助手"
      welcomeMessage="我可以帮助你完成后台页面操作。"
    />
  );
}

Provider + UI 分层

import {
  NextAgentFloatingPanel,
  NextAgentProvider,
} from 'react-agent-remoter';

export function App() {
  return (
    <NextAgentProvider
      agentRoot="https://agent.opentiny.design/api/v1/webmcp-trial/"
      llmConfig={{
        apiKey: 'your-api-key',
        baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
        providerType: 'openai',
      }}
      model="qwen3.5-plus"
    >
      {(controller) => (
        <NextAgentFloatingPanel
          controller={controller}
          title="自定义业务助手"
          welcomeMessage="这里可以先复用默认 UI，再逐步替换成你自己的设计。"
        />
      )}
    </NextAgentProvider>
  );
}

可用能力

• 右下角浮标打开/关闭聊天框
• 消息流式展示、停止生成、新会话
• sessionId 初始化和运行时追加
• 通过 ref 调用 open、close、submit、stop、addSessionId
• 通过 Provider 自定义 UI 层

核心参数

• agentRoot: WebAgent 服务地址
• llmConfig: 大模型连接配置，至少包含 apiKey、baseURL、providerType
• model: 当前对话使用的模型名
• sessionId: 当前受控 Web 应用的会话 ID，支持多个值用英文逗号分隔
• systemPrompt: 传给智能体的系统提示词

组件关系

• NextAgentWidget: 开箱即用组件，内部等价于 NextAgentProvider + NextAgentFloatingPanel
• NextAgentProvider: 只提供逻辑层，适合完全自定义 UI
• NextAgentFloatingPanel: 默认的浮动按钮 + 对话框 UI
• DefaultNextAgentWidget: 兼容旧名字的别名，后续更推荐使用 NextAgentFloatingPanel

示例代码

• 基础示例见 examples/basic.tsx