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 |
|
|
La región donde se encuentra el AgentSpace, por ejemplo, |
|
|
Nombre del AgentSpace |
|
|
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 |
|
Descripción |
|
Quick start |
|
Abre la página Quick start |
|
Agent Insights |
|
Abre la página de análisis de observability del agente |
|
Agent comparison |
|
Abre la página de comparación de agentes |
|
AI Agent Observability |
|
Abre la entrada principal de AI Agent Observability |
|
Dashboard |
|
Abre la página Dashboard |
|
Integration Center |
|
Abre la página Integration Center |
|
Agent trajectory |
|
Abre la página de trayectoria del agente |
|
Evaluation tasks |
|
Abre la página de tareas de evaluación |
|
Evaluation analysis insights |
|
Abre la página Evaluation analysis insights |
|
Evaluator |
|
Abre la página Evaluator |
|
Experiment plan |
|
Abre la página Experiment plan |
|
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 |
|
|
El ARN del rol de RAM que se asumirá |
|
|
Nombre de la sesión. Use un identificador de usuario de negocio auditable. |
|
|
Periodo de validez de las credenciales temporales |
|
|
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 |
|
|
|
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. |
|
|
|
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. |
|
|
|
Rellena previamente el tipo de origen de datos cuando se abre el formulario de creación de tareas en la página Evaluation tasks |
|
|
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 |
|
|
|
Oculta el selector de tiempo en la página Evaluation analysis insights |
|
|
|
Oculta el área de búsqueda, agregación y registros en la parte superior de la página Evaluation analysis insights |
|
|
Número |
Hora de inicio inicial, una marca de tiempo Unix en segundos |
|
|
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.
y 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
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 |
|
|
Sí |
|
Abre automáticamente el formulario de creación de tareas |
|
|
No |
|
Rellena previamente el origen de datos |
|
|
No |
Nombre del conjunto de datos |
Rellena previamente el conjunto de datos cuando el origen de datos es |
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 |
|
|
Obligatorio al consultar, copiar o editar una tarea existente |
ID de la tarea de evaluación |
|
|
No |
|
|
|
No |
El flujo de detalles actual admite |
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 |
|
|
Cadena |
Vacío |
Instrucción de consulta inicial. Debe codificarse como URL. |
|
|
Cadena |
|
Dimensión de agregación primaria inicial. Valores compatibles: |
|
|
Cadena |
|
Dimensión de agregación secundaria inicial. Los valores son los mismos que los de |
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:
Si se pasa
traceId, se abre Trace details.Si no se pasa
traceIdy se indicatargetPage=session-explorer, se abre Session Explorer.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 |
|
|
Sí |
ID de traza. La entrada principal distingue entre mayúsculas y minúsculas, así que use esta ortografía. |
|
|
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. |
|
|
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 |
|
|
Sí |
Establézcalo en |
|
|
No |
Expresión de filtro de sesión o de traza |
|
|
No |
Instrucción de consulta que se transmite a la página de consulta interna |
|
|
No |
Modo de tiempo de la página descendente. Los enlaces profundos internos de AgentLoop pasan actualmente |
|
|
No |
Hora de inicio de la consulta. Los enlaces profundos de Session de AgentLoop utilizan actualmente marcas de tiempo Unix en segundos. |
|
|
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 |
|
|
Sí |
ID de traza. La ruta del componente también acepta la escritura en minúsculas. |
|
|
No |
Admite marcas de tiempo en segundos o en milisegundos. |
|
|
No |
Admite marcas de tiempo en segundos o en milisegundos. |
|
|
No |
Especifique el ID de span |
|
|
No |
Pestaña inicial en la página Trace details |
|
|
No |
Identificador del origen de la consulta de traza |
|
|
No |
Identificador del origen de la página |
|
|
No |
Condiciones de filtro de detalles de span |
|
|
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,GetSigninTokeny 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:
Destinationdebe usaragentloop4service.console.alibabacloud.com.Maneje correctamente la codificación de URL:
Destinationpuede contener parámetros de consulta y debe codificarse por completo al escribirse en la URL de inicio de sesión. UseURLyURLSearchParamspara 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=trueyhiddenBackHome=true.Controle la caducidad del enlace sin inicio de sesión: Actualice el enlace sin inicio de sesión antes de que caduque el
SigninTokenpara 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
embeddebe ser un JSON válido. Si el análisis sintáctico falla, se ignora toda la configuración deembed.embedse 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
embedno reconocidos no tienen ningún efecto.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 |
|
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 |
|
El usuario puede regresar a la página principal de AgentLoop |
Agregue |
|
La navegación del lado izquierdo sigue mostrándose |
Confirme que |
|
El encabezado de la página sigue mostrándose |
Confirme que |
|
La entrada de cambio sigue oculta después de pasar |
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 |
|
El nombre del servicio no se rellena previamente al crear la tarea de evaluación |
Confirme que se está ingresando a la página |
|
La sesión no se abre en la página de AI Agent |
Use la entrada actual |
|
La página no cambia después de modificar |
La configuración se analiza sintácticamente solo una vez. Vuelva a cargar la página después de cambiar la URL. |