AgentLoop:AgentLoop Console Embedded Sharing Integration Guide

Step 1: Generate Destination

Destination is the AgentLoop page that users will ultimately open after login-free authentication.

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}',
    },
  })
);

Step 2: Obtain temporary credentials

The third-party system server calls STS AssumeRole to obtain temporary credentials. Configure least privilege based on user, tenant, or business resource scope. A token can only be used once. For details, see AssumeRole.

Common parameters:

Do not save or transmit long-term AccessKey in the browser frontend.

Step 3: Obtain SigninToken

Call RAM single sign-on (SSO) to obtain the SigninToken. The link format is as follows. Note: TicketType must be set to mini.

http://signin.aliyun.com/federation?Action=GetSigninToken
                    &AccessKeyId=<Temporary AK returned by STS>
                    &AccessKeySecret=<Temporary Secret returned by STS>
                    &SecurityToken=<Security Token returned by STS>
                    &TicketType=mini

To avoid exposing sensitive information, GetSigninToken should only be called on the server side. Do not concatenate or expose temporary keys in the browser frontend.

Step 4: Generate login-free link

Append the returned SigninToken to the prepared link to generate a password-free access link.

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());

Final URL format:

http://signin.aliyun.com/federation?Action=Login
                            &LoginUrl=<The address to redirect to when login expires, typically configured as a URL that performs a 302 redirect in your custom web service. Use encodeURL to encode LoginUrl.>
                            &Destination=<The actual page to access. If there are parameters, use encodeURL to encode them.>
                            &SigninToken=<The obtained login token. Use encodeURL to encode the token.>

iframe example:

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

embed

embed is used to pass structured embedding configuration as a JSON string. When appended to a URL, it must be URL-encoded.

Readable form:

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

Structure definition:

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;
      };
    };
  };
}

Parameter descriptions:

timeRange.from must be smaller than timeRange.to, and both values use second-level Unix timestamps. embed.eval only pre-fills the create task form; it does not open the form automatically.

Generation example:

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',
    eval: {
      dataSource: 'trace',
      serviceName: '{serviceName}',
    },
  })
);

console.log(targetUrl.toString());

Generated URL example:

https://agentloop4service.console.alibabacloud.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/evaluate-task?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

hiddenSwitch

Hides the AgentSpace switching entry.

hiddenSwitch=true

If the third-party system has already fixed the current AgentSpace, enable this parameter to prevent users from switching to other spaces within the embedded page.

hiddenBackHome

Hides the "Back to Home" entry.

hiddenBackHome=true

If the third-party system wants users to stay on the specified AgentSpace page, enable this parameter to prevent users from returning to the AgentLoop home page.

hiddenSwitch and hiddenBackHome are evaluated by presence only. Even if the value is false, the parameter still takes effect as long as it appears in the URL. To restore the AgentSpace switching entry or the home page entry, remove the corresponding parameter from the URL.

Hide left-side navigation

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

Hide the page header

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

Hide both the left-side navigation and the page header

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

Disable space switching and return to home

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

Hide navigation and pre-fill evaluation task parameters

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

Simplify the Evaluation analysis insights page

Generating the address with the standard browser API avoids manual handling of JSON, spaces, and quotation marks:

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());

Open the create task form automatically

Page path:

/app/evaluate-task

Parameter descriptions:

Example:

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}');

After the page consumes these one-time parameters, action, dataSource, and datasetName are removed from the address bar so that a refresh does not trigger the form again.

Open the task edit form

/app/evaluate-task?editTaskId={taskId}

editTaskId is also removed from the address bar after it is consumed.

Open task details

Page path:

/app/evaluate-task-detail

Parameter descriptions:

Set the initial state of Evaluation analysis insights

Page path:

/app/explorer

Parameter descriptions:

Example:

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');

When no aggregation is needed, omit groupBy and subGroupBy or set them to none.

Open application list

When neither traceId nor targetPage is passed, the page opens the application list.

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

Open Trace details

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

Parameter descriptions:

Open 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}');

Parameter descriptions:

Session deep links use second-level timestamps while Trace deep links use millisecond-level timestamps, so convert the time values according to the page you open. Encode all service names, dataset names, query statements, and filter expressions with URLSearchParams.

Trace component route compatibility parameters

When the deployed dynamic module registers /app/llm_agent/trace-detail, that component route additionally supports the following parameters:

The /app/llm_agent/app-list main entry does not forward all of these advanced parameters. For a stable, unified entry, use only traceId, startTime, and endTime, which the main entry supports.