AgentLoop 控制台内嵌分享接入指南

步骤一：生成 Destination

Destination 是用户免登录后最终打开的 AgentLoop 页面。

const destination = new URL(
  'https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/evaluate-task'
);

destination.searchParams.set('hiddenSwitch', 'true');
destination.searchParams.set('hiddenBackHome', 'true');
destination.searchParams.set(
  'embed',
  JSON.stringify({
    sidebar: 'hidden',
    header: 'hidden',
    eval: {
      dataSource: 'trace',
      serviceName: '{serviceName}',
    },
  })
);

步骤二：获取临时身份

第三方系统服务端调用 STS AssumeRole，获取临时身份。建议按用户、租户或业务资源范围配置最小权限。一个Token只能使用一次，详情可参考AssumeRole - 获取扮演角色的临时身份凭证。

常用参数：

请勿在浏览器前端保存或传输长期 AccessKey。

步骤三：获取 SigninToken

调用RAM单点登录SSO，获取SigninToken。拼接链接的形式如下。注意：TicketType必须指定为mini。

http://signin.aliyun.com/federation?Action=GetSigninToken
                    &AccessKeyId=<STS返回的临时AK>
                    &AccessKeySecret=<STS返回的临时Secret>
                    &SecurityToken=<STS返回的安全Token>
                    &TicketType=mini

为避免泄露敏感信息，GetSigninToken 应仅在服务端调用，不要在浏览器前端拼接或暴露临时密钥。

步骤四：生成免登录链接

将返回的SigninToken拼接到准备好的链接中，生成免密访问链接。

const loginUrl = new URL('https://signin.aliyun.com/federation');

loginUrl.searchParams.set('Action', 'Login');
loginUrl.searchParams.set('LoginUrl', 'https://{your-domain}/login-expired');
loginUrl.searchParams.set('Destination', destination.toString());
loginUrl.searchParams.set('SigninToken', signinToken);

console.log(loginUrl.toString());

最终 URL 形态：

http://signin.aliyun.com/federation?Action=Login
                            &LoginUrl=<登录失效跳转的地址，一般配置为自建Web配置302跳转的URL。需要使用encodeURL对LoginUrl进行转码。>
                            &Destination=<实际访问页面。如果有参数，则需要使用encodeURL对参数进行转码。>
                            &SigninToken=<获取的登录Token，需要使用encodeURL对Token进行转码。>

iframe 示例：

<iframe
  src="{loginUrl}"
  width="100%"
  height="100%"
  frameborder="0"
  allowfullscreen
></iframe>

embed

embed 用于传递结构化内嵌配置，值为 JSON 字符串。实际拼接到 URL 时，需要进行 URL 编码。

可读形式：

?embed={"sidebar":"hidden","header":"hidden","eval":{"dataSource":"trace","serviceName":"{serviceName}"}}

结构说明：

interface EmbedConfig {
  sidebar?: 'hidden';
  header?: 'hidden';
  eval?: {
    dataSource?: 'trace' | 'atif' | 'log' | 'dataset';
    serviceName?: string;
    explorer?: {
      timePicker?: 'hidden';
      topBar?: 'hidden';
      filterSidebar?: 'hidden';
      timeRange?: {
        from: number;
        to: number;
      };
    };
  };
}

参数说明：

embed.eval 只在用户打开新建任务表单时生效预填，不会自动打开表单。需要进入页面即打开表单时，使用「评估页面参数」中的 action=create。

生成示例：

const targetUrl = new URL(
  'https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/evaluate-task'
);

targetUrl.searchParams.set(
  'embed',
  JSON.stringify({
    sidebar: 'hidden',
    header: 'hidden',
    eval: {
      dataSource: 'trace',
      serviceName: '{serviceName}',
    },
  })
);

console.log(targetUrl.toString());

使用 URL 和 URLSearchParams 生成地址，可以避免手工处理 JSON、中文、空格和引号带来的编码错误。生成后的 URL 示例：

https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/evaluate-task?embed=%7B%22sidebar%22%3A%22hidden%22%2C%22header%22%3A%22hidden%22%2C%22eval%22%3A%7B%22dataSource%22%3A%22trace%22%2C%22serviceName%22%3A%22%7BserviceName%7D%22%7D%7D

hiddenSwitch

隐藏 AgentSpace 切换入口。

hiddenSwitch=true

如果第三方系统已经固定当前 AgentSpace，建议开启该参数，避免用户在内嵌页面中切换到其他空间。该参数按「是否存在」判断：即使传入 hiddenSwitch=false，只要参数出现在 URL 中，切换入口仍然隐藏。需要恢复切换入口时，从 URL 中删除该参数。

hiddenBackHome

禁止通过 AgentLoop Logo 返回首页。

hiddenBackHome=true

如果第三方系统只希望用户停留在指定 AgentSpace 页面，建议开启该参数。该参数同样按「是否存在」判断：传入 hiddenBackHome=false 不会恢复入口，需要从 URL 中删除该参数。

隐藏左侧导航

https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/agent-insight?embed=%7B%22sidebar%22%3A%22hidden%22%7D

只隐藏页面 Header

可读形式：

?embed={"header":"hidden"}

URL 参数：

https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/agent-insight?embed=%7B%22header%22%3A%22hidden%22%7D

同时隐藏左侧导航和页面 Header

可读形式：

?embed={"sidebar":"hidden","header":"hidden"}

URL 参数：

https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/agent-insight?embed=%7B%22sidebar%22%3A%22hidden%22%2C%22header%22%3A%22hidden%22%7D

禁止切换空间和返回首页

https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/agent-insight?hiddenSwitch=true&hiddenBackHome=true

隐藏导航并预填评估任务参数

https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/evaluate-task?hiddenSwitch=true&hiddenBackHome=true&embed=%7B%22sidebar%22%3A%22hidden%22%2C%22eval%22%3A%7B%22dataSource%22%3A%22trace%22%2C%22serviceName%22%3A%22%7BserviceName%7D%22%7D%7D

精简评估分析洞察页面

内嵌评估分析洞察页面时，如果第三方系统自行提供搜索和筛选能力，可以隐藏页面自带的时间选择器、顶部区域和筛选侧栏，并指定初始时间范围：

const targetUrl = new URL(
  'https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/explorer'
);

targetUrl.searchParams.set(
  'embed',
  JSON.stringify({
    sidebar: 'hidden',
    header: 'hidden',
    eval: {
      explorer: {
        timePicker: 'hidden',
        topBar: 'hidden',
        filterSidebar: 'hidden',
        timeRange: {
          from: 1785427200,
          to: 1785513600,
        },
      },
    },
  })
);

console.log(targetUrl.toString());

timeRange.from 和 timeRange.to 都使用秒级 Unix 时间戳，且 from 必须小于 to。

自动打开新建任务表单

页面路径为 /app/evaluate-task。

const targetUrl = new URL(
  'https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/evaluate-task'
);

targetUrl.searchParams.set('action', 'create');
targetUrl.searchParams.set('dataSource', 'dataset');
targetUrl.searchParams.set('datasetName', '{datasetName}');

console.log(targetUrl.toString());

页面消费这些一次性参数后，会从地址栏移除 action、dataSource 和 datasetName，避免刷新时重复触发。

打开任务编辑表单

https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/evaluate-task?editTaskId={taskId}

editTaskId 被消费后同样会从地址栏移除。

打开评估任务详情

页面路径为 /app/evaluate-task-detail。

指定评估分析洞察初始状态

页面路径为 /app/explorer。

const targetUrl = new URL(
  'https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/explorer'
);

targetUrl.searchParams.set('q', 'status: success');
targetUrl.searchParams.set('groupBy', 'evaluator');

console.log(targetUrl.toString());

无聚合需求时不传 groupBy 和 subGroupBy，或将其设置为 none。

打开应用列表

不传 traceId，也不传 targetPage 时，页面默认打开 AI 应用列表。

https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/llm_agent/app-list?hiddenSwitch=true&hiddenBackHome=true

打开 Trace 详情

传入 traceId 时，页面打开对应 Trace 详情。

https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/llm_agent/app-list?traceId={traceId}&startTime={startTime}&endTime={endTime}&hiddenSwitch=true&hiddenBackHome=true

参数说明：

spanId、initialTab、querySource、source、spanFiltersQuery 和 spanFiltersTimeSeriesQuery 不由主入口转发，仅在 Trace 组件路由下可用，参见「Trace 组件路由兼容参数」。

打开 Session Explorer

需要从第三方系统直达某个会话时，传入 targetPage=session-explorer 并携带筛选条件：

const targetUrl = new URL(
  'https://agentloop4service.console.aliyun.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/llm_agent/app-list'
);

targetUrl.searchParams.set('targetPage', 'session-explorer');
targetUrl.searchParams.set(
  'filters',
  'attributes.gen_ai.session.id: "{sessionId}"'
);
targetUrl.searchParams.set('queryTimeType', '99');
targetUrl.searchParams.set('startTime', '{startTime}');
targetUrl.searchParams.set('endTime', '{endTime}');

console.log(targetUrl.toString());

参数说明：

Session 深链的时间参数为秒级，Trace 深链的时间参数为毫秒级，拼接前需确认单位。

Trace 组件路由兼容参数

当部署的动态模块注册了 /app/llm_agent/trace-detail 时，该组件路由额外支持以下参数：

这组参数不会由 /app/llm_agent/app-list 主入口全部转发。需要统一稳定入口时，以主入口支持的 traceId、startTime 和 endTime 为准。