Todos los productos
Search
Centro de documentos

AgentLoop:Guía de integración para compartir la consola de AgentLoop de forma embebida

Última actualización: Sep 06, 2026

Descripción general

La consola de AgentLoop admite la integración en sistemas de terceros mediante incrustación. Abra una página específica de AgentSpace a través de un enlace sin inicio de sesión y utilice parámetros de URL para controlar la navegación, el encabezado de la página, la entrada de cambio de AgentSpace y el estado inicial de algunas páginas de negocio.

El dominio recomendado para el acceso embebido es:

https://agentloop4service.console.alibabacloud.com

No mezcle el dominio habitual de la consola con el dominio embebido. El acceso embebido siempre debe usar el dominio 4service mencionado en este documento para evitar que las páginas queden inaccesibles por estados de inicio de sesión inconsistentes.

Formato de la URL de la página

El formato de la URL de la página de AgentSpace es el siguiente:

https://agentloop4service.console.alibabacloud.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/{appPath}

A continuación se describen los parámetros:

Parámetro

Descripción

{regionId}

La región donde se encuentra el AgentSpace, por ejemplo, cn-hangzhou

{agentSpaceName}

Nombre del AgentSpace

{appPath}

La ruta de la página que se abrirá

Ejemplo:

https://agentloop4service.console.alibabacloud.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/agent-insight

Rutas de página comunes:

Página

appPath

Descripción

Quick start

quickstart

Abre la página Quick start

Agent Insights

agent-insight

Abre la página de análisis de observability del agente

Agent comparison

agent-comparison

Abre la página de comparación de agentes

AI Agent Observability

llm_agent/app-list

Abre la entrada principal de AI Agent Observability

Dashboard

dashboard

Abre la página Dashboard

Integration Center

integratingcenter

Abre la página Integration Center

Agent trajectory

trajectory

Abre la página de trayectoria del agente

Evaluation tasks

evaluate-task

Abre la página de tareas de evaluación

Evaluation analysis insights

explorer

Abre la página Evaluation analysis insights

Evaluator

evaluator

Abre la página Evaluator

Experiment plan

experiment-plan

Abre la página Experiment plan

Experiment record

experiment-record

Abre la página Experiment record

La variable de ruta {agentSpaceName} debe codificarse como URL al concatenar la dirección.

Generar enlaces sin inicio de sesión

Consulte el método de generación de enlaces sin inicio de sesión de la consola de administración de Alibaba Cloud. Utilice la página de destino de AgentLoop como Destination para generar un enlace sin inicio de sesión que pueda colocarse en un iframe.

Paso 1: Generar Destination

Destination es la página de AgentLoop que los usuarios abrirán finalmente después de la autenticación sin inicio de sesión.

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

Paso 2: Obtener credenciales temporales

El servidor del sistema de terceros llama a AssumeRole de STS para obtener credenciales temporales. Configure el privilegio mínimo según el usuario, el inquilino o el alcance de los recursos de negocio. Un token solo puede usarse una vez. Para más detalles, consulte AssumeRole.

Parámetros comunes:

Parámetro

Descripción

RoleArn

El ARN del rol de RAM que se asumirá

RoleSessionName

Nombre de la sesión. Use un identificador de usuario de negocio auditable.

DurationSeconds

Periodo de validez de las credenciales temporales

Policy

Opcional. Se usa para restringir aún más el alcance de los recursos accesibles en esta sesión.

No guarde ni transmita un AccessKey de larga duración en el frontend del navegador.

Paso 3: Obtener SigninToken

Llame al inicio de sesión único (SSO) de RAM para obtener el SigninToken. El formato del enlace es el siguiente. Nota: TicketType debe establecerse en mini.

http://signin.alibabacloud.com/federation?Action=GetSigninToken
                    &AccessKeyId=<Temporary AK returned by STS>
                    &AccessKeySecret=<Temporary Secret returned by STS>
                    &SecurityToken=<Security Token returned by STS>
                    &TicketType=mini
Para evitar exponer información confidencial, GetSigninToken solo debe llamarse en el lado del servidor. No concatene ni exponga claves temporales en el frontend del navegador.

Paso 4: Generar el enlace sin inicio de sesión

Agregue el SigninToken devuelto al enlace preparado para generar un enlace de acceso sin contraseña.

const loginUrl = new URL('https://signin.alibabacloud.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());

Formato final de la URL:

http://signin.alibabacloud.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.>

Ejemplo de iframe:

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

Parámetros embebidos

AgentLoop admite los siguientes parámetros de URL para controlar la visualización y el comportamiento de las páginas embebidas.

embed

embed se utiliza para pasar la configuración de incrustación estructurada como una cadena JSON. Cuando se agrega a una URL, debe codificarse como URL.

Forma legible:

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

Definición de la estructura:

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

A continuación se describen los parámetros:

Parámetro

Valores posibles

Descripción

embed.sidebar

hidden

Oculta toda el área izquierda de AgentSpace, incluido el logotipo, el selector de AgentSpace, el menú y el botón de contracción. Recomendado cuando el sistema de terceros proporciona su propia navegación.

embed.header

hidden

Oculta el encabezado del área de contenido de AgentSpace, incluidos el título de la página, las pestañas superiores y el área de operaciones de la derecha. No controla la barra superior externa de la consola de administración de Alibaba Cloud.

embed.eval.dataSource

trace / atif / log / dataset

Rellena previamente el tipo de origen de datos cuando se abre el formulario de creación de tareas en la página Evaluation tasks

embed.eval.serviceName

Nombre del servicio

Rellena previamente el nombre del servicio cuando se abre el formulario de creación de tareas en la página Evaluation tasks

embed.eval.explorer.timePicker

hidden

Oculta el selector de tiempo en la página Evaluation analysis insights

embed.eval.explorer.topBar

hidden

Oculta el área de búsqueda, agregación y registros en la parte superior de la página Evaluation analysis insights

embed.eval.explorer.filterSidebar

hidden

Oculta la barra lateral de filtros en la página Evaluation analysis insights

embed.eval.explorer.timeRange.from

Número

Hora de inicio inicial, una marca de tiempo Unix en segundos

embed.eval.explorer.timeRange.to

Número

Hora de finalización inicial, una marca de tiempo Unix en segundos

timeRange.from debe ser menor que timeRange.to, y ambos valores usan marcas de tiempo Unix en segundos. embed.eval solo rellena previamente el formulario de creación de tareas; no lo abre automáticamente.

Ejemplo de generación:

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

Ejemplo de URL generada:

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

Oculta la entrada de cambio de AgentSpace.

hiddenSwitch=true

Si el sistema de terceros ya fijó el AgentSpace actual, habilite este parámetro para evitar que los usuarios cambien a otros espacios dentro de la página embebida.

hiddenBackHome

Oculta la entrada "Back to Home".

hiddenBackHome=true

Si el sistema de terceros necesita que los usuarios permanezcan en la página especificada de AgentSpace, habilite este parámetro para evitar que regresen a la página principal de AgentLoop.

hiddenSwitch y hiddenBackHome se evalúan únicamente por su presencia. Incluso si el valor es false, el parámetro surte efecto mientras aparezca en la URL. Para restaurar la entrada de cambio de AgentSpace o la entrada de la página principal, elimine el parámetro correspondiente de la URL.

Combinaciones de parámetros recomendadas

Ocultar la navegación del lado izquierdo

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

Ocultar el encabezado de la página

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

Ocultar tanto la navegación del lado izquierdo como el encabezado de la página

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

Deshabilitar el cambio de espacio y el regreso a la página principal

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

Ocultar la navegación y rellenar previamente los parámetros de la tarea de evaluación

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

Simplificar la página Evaluation analysis insights

Generar la dirección con la API estándar del navegador evita el manejo manual de JSON, espacios y comillas:

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

Parámetros de las páginas de evaluación

Además de la configuración de embed, las páginas de evaluación leen un pequeño conjunto de parámetros de URL que abren un formulario específico o restauran un estado inicial determinado.

Abrir automáticamente el formulario de creación de tareas

Ruta de la página:

/app/evaluate-task

A continuación se describen los parámetros:

Parámetro

Obligatorio

Valores posibles

Descripción

action

Sí

create

Abre automáticamente el formulario de creación de tareas

dataSource

No

trace / atif / log / dataset

Rellena previamente el origen de datos

datasetName

No

Nombre del conjunto de datos

Rellena previamente el conjunto de datos cuando el origen de datos es dataset

Ejemplo:

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

Una vez que la página consume estos parámetros de un solo uso, action, dataSource y datasetName se eliminan de la barra de direcciones para que una actualización no vuelva a activar el formulario.

Abrir el formulario de edición de tareas

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

editTaskId también se elimina de la barra de direcciones después de consumirse.

Abrir los detalles de la tarea

Ruta de la página:

/app/evaluate-task-detail

A continuación se describen los parámetros:

Parámetro

Obligatorio

Descripción

taskId

Obligatorio al consultar, copiar o editar una tarea existente

ID de la tarea de evaluación

type

No

add, view, copy o edit. Valor predeterminado: add.

action

No

El flujo de detalles actual admite start, que ubica el área de políticas de ejecución.

Establecer el estado inicial de Evaluation analysis insights

Ruta de la página:

/app/explorer

A continuación se describen los parámetros:

Parámetro

Tipo

Valor predeterminado

Descripción

q

Cadena

Vacío

Instrucción de consulta inicial. Debe codificarse como URL.

groupBy

Cadena

none

Dimensión de agregación primaria inicial. Valores compatibles: dataItem, evaluator, task, evaluationRun, status, agent y dataset.

subGroupBy

Cadena

none

Dimensión de agregación secundaria inicial. Los valores son los mismos que los de groupBy, pero no puede ser idéntica a la dimensión de agregación primaria.

Ejemplo:

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

Cuando no se requiere agregación, omita groupBy y subGroupBy, o establézcalos en none.

Página de AI Agent Observability

La entrada principal actual de la página AI Agent Observability es:

https://agentloop4service.console.alibabacloud.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/llm_agent/app-list

La entrada principal selecciona la página interna en el siguiente orden:

  1. Si se pasa traceId, se abre Trace details.

  2. Si no se pasa traceId y se indica targetPage=session-explorer, se abre Session Explorer.

  3. En todos los demás casos, se abre la lista de aplicaciones de IA.

Abrir la lista de aplicaciones

Cuando no se pasan ni traceId ni targetPage, la página abre la lista de aplicaciones.

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

Abrir 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

A continuación se describen los parámetros:

Parámetro

Obligatorio

Descripción

traceId

Sí

ID de traza. La entrada principal distingue entre mayúsculas y minúsculas, así que use esta ortografía.

startTime

No

Hora de inicio de la consulta. Los enlaces profundos de Trace de AgentLoop utilizan actualmente marcas de tiempo Unix en milisegundos. Si no se pasa, el valor predeterminado es una hora antes de la hora actual.

endTime

No

Hora de finalización de la consulta. Los enlaces profundos de Trace de AgentLoop utilizan actualmente marcas de tiempo Unix en milisegundos. Si no se pasa, el valor predeterminado es la hora actual.

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

A continuación se describen los parámetros:

Parámetro

Obligatorio

Descripción

targetPage

Sí

Establézcalo en session-explorer.

filters

No

Expresión de filtro de sesión o de traza

queryString

No

Instrucción de consulta que se transmite a la página de consulta interna

queryTimeType

No

Modo de tiempo de la página descendente. Los enlaces profundos internos de AgentLoop pasan actualmente 99 junto con startTime y endTime.

startTime

No

Hora de inicio de la consulta. Los enlaces profundos de Session de AgentLoop utilizan actualmente marcas de tiempo Unix en segundos.

endTime

No

Hora de finalización de la consulta. Los enlaces profundos de Session de AgentLoop utilizan actualmente marcas de tiempo Unix en segundos.

Los enlaces profundos de Session usan marcas de tiempo en segundos, mientras que los de Trace usan marcas de tiempo en milisegundos. Por lo tanto, convierta los valores de tiempo según la página que abra. Codifique todos los nombres de servicios, nombres de conjuntos de datos, instrucciones de consulta y expresiones de filtro con URLSearchParams.

Parámetros de compatibilidad de rutas del componente Trace

Cuando el módulo dinámico desplegado registra /app/llm_agent/trace-detail, esa ruta del componente admite además los siguientes parámetros:

Parámetro

Obligatorio

Descripción

traceId / traceid

Sí

ID de traza. La ruta del componente también acepta la escritura en minúsculas.

startTime

No

Admite marcas de tiempo en segundos o en milisegundos.

endTime

No

Admite marcas de tiempo en segundos o en milisegundos.

spanId

No

Especifique el ID de span

initialTab

No

Pestaña inicial en la página Trace details

querySource

No

Identificador del origen de la consulta de traza

source

No

Identificador del origen de la página

spanFiltersQuery

No

Condiciones de filtro de detalles de span

spanFiltersTimeSeriesQuery

No

Condiciones de filtro de series temporales de span

La entrada principal /app/llm_agent/app-list no reenvía todos estos parámetros avanzados. Para una entrada estable y unificada, use solo traceId, startTime y endTime, que son los que admite la entrada principal.

Página de Integration Center

La ruta de la página Integration Center es:

https://agentloop4service.console.alibabacloud.com/agentloop/region/{regionId}/agentspace/{agentSpaceName}/app/integratingcenter

Combine los parámetros embebidos según sus necesidades, por ejemplo:

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

Prácticas recomendadas de integración

  • Genere los enlaces sin inicio de sesión en el lado del servidor: AssumeRole, GetSigninToken y la URL de inicio de sesión final deben completarse en el lado del servidor. El frontend del navegador solo recibe la URL final del iframe accesible.

  • Use siempre el dominio 4service: Destination debe usar agentloop4service.console.alibabacloud.com.

  • Maneje correctamente la codificación de URL: Destination puede contener parámetros de consulta y debe codificarse por completo al escribirse en la URL de inicio de sesión. Use URL y URLSearchParams para la generación.

  • Oculte la navegación de la consola según sea necesario: Si el sistema externo ya proporciona navegación, use una combinación de embed={"sidebar":"hidden","header":"hidden"}, hiddenSwitch=true y hiddenBackHome=true.

  • Controle la caducidad del enlace sin inicio de sesión: Actualice el enlace sin inicio de sesión antes de que caduque el SigninToken para evitar que la página dentro del iframe quede inaccesible por un estado de inicio de sesión caducado.

  • Autorización con privilegio mínimo: Los permisos del rol de RAM deben limitarse a los recursos necesarios de AgentLoop, registros y observability según los requisitos de negocio.

Reglas de análisis sintáctico y compatibilidad de parámetros

  • embed debe ser un JSON válido. Si el análisis sintáctico falla, se ignora toda la configuración de embed.

  • embed se analiza sintácticamente solo una vez durante el ciclo de vida de la página actual. Vuelva a cargar la página después de cambiar el parámetro.

  • Los campos de embed no reconocidos no tienen ningún efecto.

  • La navegación interna conserva embed, hiddenSwitch y hiddenBackHome.

  • Los parámetros de URL solo controlan la visualización y el estado inicial. No proporcionan control de acceso, y ocultar un menú o un encabezado no sustituye la verificación de permisos de RAM, AgentSpace o de datos.

  • Codifique todas las entradas de usuario, nombres de servicios, nombres de conjuntos de datos, instrucciones de consulta y expresiones de filtro con URLSearchParams.

  • Los parámetros de consulta y los campos de tiempo de ejecución que no se enumeran en este documento no forman parte del protocolo de integración público. No los concatene usted mismo ni los agregue a la documentación en línea.

Preguntas frecuentes

Problema

Solución de problemas

El iframe muestra que no se ha iniciado sesión

Confirme que se está usando agentloop4service.console.alibabacloud.com y que Destination se codificó completamente como URL.

El iframe muestra falta de permisos

Confirme que los permisos del rol de RAM cubren el AgentSpace de destino y sus recursos asociados.

El usuario puede cambiar de AgentSpace

Agregue hiddenSwitch=true a la URL.

El usuario puede regresar a la página principal de AgentLoop

Agregue hiddenBackHome=true a la URL.

La navegación del lado izquierdo sigue mostrándose

Confirme que embed es un JSON válido, está codificado correctamente como URL y contiene {"sidebar":"hidden"}.

El encabezado de la página sigue mostrándose

Confirme que embed contiene {"header":"hidden"}. No use hideHeader=true.

La entrada de cambio sigue oculta después de pasar hiddenSwitch=false

Este parámetro se evalúa por su presencia. Elimínelo de la URL para restaurar la entrada.

El formulario de creación de tareas no se abre automáticamente

Use action=create. embed.eval solo rellena previamente el formulario.

El nombre del servicio no se rellena previamente al crear la tarea de evaluación

Confirme que se está ingresando a la página app/evaluate-task y que existe el nombre de servicio correspondiente a embed.eval.serviceName.

La sesión no se abre en la página de AI Agent

Use la entrada actual app/llm_agent/app-list y pase targetPage=session-explorer.

La página no cambia después de modificar embed

La configuración se analiza sintácticamente solo una vez. Vuelva a cargar la página después de cambiar la URL.