AgentLoop：AgentLoop 控制台內嵌分享接入指南

步驟一：產生 Destination

Destination 是使用者免登入後最終開啟的 AgentLoop 頁面。

const destination = new URL(
  'https://agentloop4service.console.alibabacloud.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.alibabacloud.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.alibabacloud.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.alibabacloud.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.alibabacloud.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.alibabacloud.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.alibabacloud.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/agent-insight?hiddenSwitch=true&hiddenBackHome=true

隱藏導航並預填評估任務參數

https://agentloop4service.console.alibabacloud.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.alibabacloud.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.alibabacloud.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.alibabacloud.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.alibabacloud.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.alibabacloud.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/llm_agent/app-list?hiddenSwitch=true&hiddenBackHome=true

開啟 Trace 詳情

傳入 traceId 時，頁面開啟對應 Trace 詳情。

https://agentloop4service.console.alibabacloud.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.alibabacloud.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 為準。