AgentLoop Console Embedded Sharing Integration Guide - AgentLoop: Central de Documentação do Alibaba Cloud

Visão geral

O console AgentLoop permite integração com sistemas de terceiros por meio de incorporação. Abra uma página específica do AgentSpace usando um link sem login e utilize parâmetros de URL para controlar a navegação, o cabeçalho da página, a entrada de troca de AgentSpace e o estado inicial de algumas páginas de negócios.

O domínio recomendado para acesso incorporado é:

https://agentloop4service.console.alibabacloud.com

Não misture o domínio regular do console com o domínio incorporado. O acesso incorporado deve sempre usar o domínio 4service mencionado neste documento para evitar que as páginas fiquem inacessíveis devido a estados de login inconsistentes.

Formato da URL da página

O formato da URL da página do AgentSpace é o seguinte:

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

Descrição dos parâmetros:

Parâmetro	Descrição
`{regionId}`	Região onde o AgentSpace está localizado, por exemplo `cn-hangzhou`
`{agentSpaceName}`	Nome do AgentSpace
`{appPath}`	Caminho da página a ser aberta

Exemplo:

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

Caminhos de página comuns:

Página	appPath	Descrição
Quick start	`quickstart`	Abre a página Quick start
Agent Insights	`agent-insight`	Abre a página de análise de observabilidade do Agent
Agent comparison	`agent-comparison`	Abre a página de comparação de Agent
AI Agent Observability	`llm_agent/app-list`	Abre a entrada principal de AI Agent Observability
Dashboard	`dashboard`	Abre a página Dashboard
Integration Center	`integratingcenter`	Abre a página Integration Center
Agent trajectory	`trajectory`	Abre a página de trajetória do Agent
Evaluation tasks	`evaluate-task`	Abre a página de tarefas de avaliação
Evaluation analysis insights	`explorer`	Abre a página de insights de análise de avaliação
Evaluator	`evaluator`	Abre a página Evaluator
Experiment plan	`experiment-plan`	Abre a página Experiment plan
Experiment record	`experiment-record`	Abre a página Experiment record

Codifique em URL a variável de caminho {agentSpaceName} durante a concatenação do endereço.

Gerar links sem login

Consulte o método de geração de links sem login do Alibaba Cloud Management Console. Utilize a página de destino do AgentLoop como Destination para gerar um link sem login que pode ser colocado em um iframe.

Etapa 1: Gerar Destination

Destination é a página do AgentLoop que os usuários abrirão após a autenticação sem login.

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

Etapa 2: Obter credenciais temporárias

O servidor do sistema de terceiros chama a API AssumeRole do STS para obter credenciais temporárias. Configure o privilégio mínimo com base no usuário, locatário ou escopo de recursos de negócios. Um token só pode ser usado uma vez. Para mais detalhes, consulte AssumeRole.

Parâmetros comuns:

Parâmetro	Descrição
`RoleArn`	ARN da função RAM a ser assumida
`RoleSessionName`	Nome da sessão. Use um identificador de usuário de negócios auditável.
`DurationSeconds`	Período de validade das credenciais temporárias
`Policy`	Opcional. Restringe ainda mais o escopo de recursos acessíveis nesta sessão.

Não salve nem transmita AccessKey de longo prazo no frontend do navegador.

Etapa 3: Obter SigninToken

Chame o single sign-on (SSO) do RAM para obter o SigninToken. O formato do link é o seguinte. Nota: defina TicketType como 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

Para evitar a exposição de informações confidenciais, chame GetSigninToken apenas no lado do servidor. Não concatene nem exponha chaves temporárias no frontend do navegador.

Etapa 4: Gerar link sem login

Anexe o SigninToken retornado ao link preparado para gerar um link de acesso sem senha.

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

Formato final da URL:

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.>

Exemplo de iframe:

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

Parâmetros incorporados

O AgentLoop suporta os seguintes parâmetros de URL para controlar a exibição e o comportamento das páginas incorporadas.

embed

Use embed para passar configurações estruturadas de incorporação como uma string JSON. Ao anexá-lo a uma URL, codifique-o em URL.

Forma legível:

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

Definição da estrutura:

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

Descrição dos parâmetros:

Parâmetro	Valores possíveis	Descrição
`embed.sidebar`	`hidden`	Oculta toda a área lateral esquerda do AgentSpace, incluindo logotipo, seletor de AgentSpace, menu e botão de recolhimento. Adequado para cenários em que o sistema de terceiros fornece sua própria navegação.
`embed.header`	`hidden`	Oculta o cabeçalho da área de conteúdo do AgentSpace, incluindo título da página, abas superiores e área de operações à direita. Não controla a barra superior mais externa do Alibaba Cloud Management Console.
`embed.eval.dataSource`	`trace` / `atif` / `log` / `dataset`	Preenche previamente o tipo de fonte de dados ao abrir o formulário de criação de tarefa na página Evaluation tasks
`embed.eval.serviceName`	Nome do serviço	Preenche previamente o nome do serviço ao abrir o formulário de criação de tarefa na página Evaluation tasks
`embed.eval.explorer.timePicker`	`hidden`	Oculta o seletor de tempo na página Evaluation analysis insights
`embed.eval.explorer.topBar`	`hidden`	Oculta a área de pesquisa, agregação e log na parte superior da página Evaluation analysis insights
`embed.eval.explorer.filterSidebar`	`hidden`	Oculta a barra lateral de filtros na página Evaluation analysis insights
`embed.eval.explorer.timeRange.from`	Número	Hora de início inicial, um timestamp Unix em nível de segundo
`embed.eval.explorer.timeRange.to`	Número	Hora de término inicial, um timestamp Unix em nível de segundo

timeRange.from deve ser menor que timeRange.to, e ambos os valores usam timestamps Unix em nível de segundo. embed.eval apenas preenche previamente o formulário de criação de tarefa; ele não abre o formulário automaticamente.

Exemplo de geração:

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

Exemplo de URL gerada:

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 a entrada de troca de AgentSpace.

hiddenSwitch=true

Se o sistema de terceiros já fixou o AgentSpace atual, ative este parâmetro para impedir que os usuários troquem para outros espaços dentro da página incorporada.

hiddenBackHome

Oculta a entrada "Back to Home".

hiddenBackHome=true

Se o sistema de terceiros desejar que os usuários permaneçam na página especificada do AgentSpace, ative este parâmetro para impedir que eles retornem à página inicial do AgentLoop.

hiddenSwitch e hiddenBackHome são avaliados apenas pela presença. Mesmo que o valor seja false, o parâmetro ainda terá efeito desde que apareça na URL. Para restaurar a entrada de troca de AgentSpace ou a entrada da página inicial, remova o parâmetro correspondente da URL.

Combinações recomendadas de parâmetros

Ocultar navegação lateral esquerda

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

Ocultar o cabeçalho da página

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

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

Desativar troca de espaço e retorno à página inicial

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 navegação e preencher previamente parâmetros de tarefa de avaliação

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 a página Evaluation analysis insights

Gerar o endereço com a API padrão do navegador evita o tratamento manual de JSON, espaços e aspas:

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 da página de avaliação

Além da configuração embed, as páginas de avaliação leem um pequeno conjunto de parâmetros de URL que abrem um formulário específico ou restauram um estado inicial específico.

Abrir o formulário de criação de tarefa automaticamente

Caminho da página:

/app/evaluate-task

Descrição dos parâmetros:

Parâmetro	Obrigatório	Valores possíveis	Descrição
`action`	Sim	`create`	Abre o formulário de criação de tarefa automaticamente
`dataSource`	Não	`trace` / `atif` / `log` / `dataset`	Preenche previamente a fonte de dados
`datasetName`	Não	Nome do dataset	Preenche previamente o dataset quando a fonte de dados é `dataset`

Exemplo:

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

Após a página consumir esses parâmetros de uso único, action, dataSource e datasetName são removidos da barra de endereços para que uma atualização não acione o formulário novamente.

Abrir o formulário de edição de tarefa

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

editTaskId também é removido da barra de endereços após ser consumido.

Abrir detalhes da tarefa

Caminho da página:

/app/evaluate-task-detail

Descrição dos parâmetros:

Parâmetro	Obrigatório	Descrição
`taskId`	Obrigatório ao visualizar, copiar ou editar uma tarefa existente	ID da tarefa de avaliação
`type`	Não	`add`, `view`, `copy` ou `edit`. Valor padrão: `add`.
`action`	Não	O fluxo de detalhes atual suporta `start`, que localiza a área de política de execução.

Definir o estado inicial de Evaluation analysis insights

Caminho da página:

/app/explorer

Descrição dos parâmetros:

Parâmetro	Tipo	Valor padrão	Descrição
`q`	String	Vazio	Instrução de consulta inicial. Deve ser codificada em URL.
`groupBy`	String	`none`	Dimensão primária de agregação inicial. Valores suportados: `dataItem`, `evaluator`, `task`, `evaluationRun`, `status`, `agent` e `dataset`.
`subGroupBy`	String	`none`	Dimensão secundária de agregação inicial. Os valores são os mesmos de `groupBy`, mas não podem ser idênticos à dimensão primária de agregação.

Exemplo:

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

Quando nenhuma agregação for necessária, omita groupBy e subGroupBy ou defina-os como none.

Página AI Agent Observability

A entrada principal atual da página AI Agent Observability é:

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

A entrada principal seleciona a página interna na seguinte ordem:

Se traceId for passado, Trace details será aberto.
Se traceId não for passado e targetPage=session-explorer, Session Explorer será aberto.
Em todos os outros casos, a lista de aplicações de IA será aberta.

Abrir lista de aplicações

Quando nem traceId nem targetPage forem passados, a página abrirá a lista de aplicações.

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

Descrição dos parâmetros:

Parâmetro	Obrigatório	Descrição
`traceId`	Sim	ID do Trace. A entrada principal diferencia maiúsculas de minúsculas, portanto use esta grafia.
`startTime`	Não	Hora de início da consulta. Os deep links de Trace do AgentLoop atualmente usam timestamps Unix em nível de milissegundo. Se não for passado, o valor padrão é uma hora antes da hora atual.
`endTime`	Não	Hora de término da consulta. Os deep links de Trace do AgentLoop atualmente usam timestamps Unix em nível de milissegundo. Se não for passado, o valor padrão é a hora atual.

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

Descrição dos parâmetros:

Parâmetro	Obrigatório	Descrição
`targetPage`	Sim	Defina como `session-explorer`.
`filters`	Não	Expressão de filtro de Sessão ou Trace
`queryString`	Não	Instrução de consulta passada diretamente para a página de consulta interna
`queryTimeType`	Não	Modo de tempo da página downstream. Os deep links internos do AgentLoop atualmente passam `99` junto com `startTime` e `endTime`.
`startTime`	Não	Hora de início da consulta. Os deep links de Sessão do AgentLoop atualmente usam timestamps Unix em nível de segundo.
`endTime`	Não	Hora de término da consulta. Os deep links de Sessão do AgentLoop atualmente usam timestamps Unix em nível de segundo.

Os deep links de Sessão usam timestamps em nível de segundo, enquanto os deep links de Trace usam timestamps em nível de milissegundo; portanto, converta os valores de tempo de acordo com a página que você abrir. Codifique todos os nomes de serviço, nomes de dataset, instruções de consulta e expressões de filtro com URLSearchParams.

Parâmetros de compatibilidade de rota do componente Trace

Quando o módulo dinâmico implantado registra /app/llm_agent/trace-detail, essa rota de componente suporta adicionalmente os seguintes parâmetros:

Parâmetro	Obrigatório	Descrição
`traceId` / `traceid`	Sim	ID do Trace. A rota do componente também aceita a grafia em minúsculas.
`startTime`	Não	Suporta timestamps em nível de segundo ou milissegundo.
`endTime`	Não	Suporta timestamps em nível de segundo ou milissegundo.
`spanId`	Não	Especifique o Span ID
`initialTab`	Não	Aba inicial na página Trace details
`querySource`	Não	Identificador de origem da consulta de Trace
`source`	Não	Identificador de origem da página
`spanFiltersQuery`	Não	Condições de filtro de detalhes do Span
`spanFiltersTimeSeriesQuery`	Não	Condições de filtro de série temporal do Span

A entrada principal /app/llm_agent/app-list não encaminha todos esses parâmetros avançados. Para uma entrada unificada e estável, use apenas traceId, startTime e endTime, que são suportados pela entrada principal.

Página Integration Center

O caminho da página Integration Center é:

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

Combine parâmetros incorporados conforme necessário, por exemplo:

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

Melhores práticas de integração

Gere links sem login no lado do servidor: Complete AssumeRole, GetSigninToken e a URL final de Login no lado do servidor. O frontend do navegador recebe apenas a URL final acessível do iframe.
Sempre use o domínio 4service: Destination deve usar agentloop4service.console.alibabacloud.com.
Trate a codificação de URL corretamente: O próprio Destination pode conter parâmetros de consulta e deve ser totalmente codificado ao ser escrito na URL de Login. Use URL e URLSearchParams para geração.
Oculte a navegação do console conforme necessário: Se o sistema externo já fornecer navegação, use uma combinação de embed={"sidebar":"hidden","header":"hidden"}, hiddenSwitch=true e hiddenBackHome=true.
Controle a expiração do link sem login: Atualize o link sem login antes que o SigninToken expire para evitar que a página dentro do iframe fique inacessível devido ao estado de login expirado.
Autorização de privilégio mínimo: Limite as permissões da função RAM aos recursos necessários do AgentLoop, logging e observabilidade de acordo com os requisitos de negócios.

Regras de análise e compatibilidade de parâmetros

embed deve ser um JSON válido. Se a análise falhar, toda a configuração embed será ignorada.
embed é analisado apenas uma vez durante o ciclo de vida da página atual. Recarregue a página após alterar o parâmetro.
Campos embed não reconhecidos não têm efeito.
A navegação interna preserva embed, hiddenSwitch e hiddenBackHome.
Os parâmetros de URL controlam apenas a exibição e o estado inicial. Eles não fornecem controle de acesso, e ocultar um menu ou cabeçalho não substitui a verificação de permissões de RAM, AgentSpace ou dados.
Codifique todas as entradas do usuário, nomes de serviço, nomes de dataset, instruções de consulta e expressões de filtro com URLSearchParams.
Parâmetros de consulta e campos de tempo de execução não listados neste documento não fazem parte do protocolo público de integração. Não os concatene por conta própria e não os adicione à documentação online.

Perguntas frequentes

Problema	Solução de problemas
Not logged in mostrado no iframe	Confirme se `agentloop4service.console.alibabacloud.com` está sendo usado e se `Destination` foi totalmente codificado em URL.
No permission mostrado no iframe	Confirme se as permissões da função RAM cobrem o AgentSpace de destino e seus recursos associados.
Usuário consegue trocar de AgentSpace	Adicione `hiddenSwitch=true` à URL.
Usuário consegue retornar à página inicial do AgentLoop	Adicione `hiddenBackHome=true` à URL.
Navegação lateral esquerda ainda aparece	Confirme se `embed` é um JSON válido, está corretamente codificado em URL e contém `{"sidebar":"hidden"}`.
Cabeçalho da página ainda aparece	Confirme se `embed` contém `{"header":"hidden"}`. Não use `hideHeader=true`.
Entrada de troca ainda está oculta após passar `hiddenSwitch=false`	Este parâmetro é avaliado pela presença. Remova-o da URL para restaurar a entrada.
Formulário de criação de tarefa não abre automaticamente	Use `action=create`. `embed.eval` apenas preenche previamente o formulário.
Nome do serviço não preenchido previamente ao criar tarefa de avaliação	Confirme se a página `app/evaluate-task` está sendo acessada e se o nome do serviço correspondente a `embed.eval.serviceName` existe.
Sessão não é aberta na página AI Agent	Use a entrada atual `app/llm_agent/app-list` e passe `targetPage=session-explorer`.
Página não muda após modificar `embed`	A configuração é analisada apenas uma vez. Recarregue a página após alterar a URL.

AgentLoop:Guia de integração de compartilhamento incorporado do console AgentLoop

Visão geral

Formato da URL da página

Gerar links sem login

Etapa 1: Gerar Destination

Etapa 2: Obter credenciais temporárias

Etapa 3: Obter SigninToken

Etapa 4: Gerar link sem login

Parâmetros incorporados

embed

hiddenSwitch

hiddenBackHome

Combinações recomendadas de parâmetros

Ocultar navegação lateral esquerda

Ocultar o cabeçalho da página

Ocultar tanto a navegação lateral esquerda quanto o cabeçalho da página

Desativar troca de espaço e retorno à página inicial

Ocultar navegação e preencher previamente parâmetros de tarefa de avaliação

Simplificar a página Evaluation analysis insights

Parâmetros da página de avaliação

Abrir o formulário de criação de tarefa automaticamente

Abrir o formulário de edição de tarefa

Abrir detalhes da tarefa

Definir o estado inicial de Evaluation analysis insights

Página AI Agent Observability

Abrir lista de aplicações

Abrir Trace details

Abrir Session Explorer

Parâmetros de compatibilidade de rota do componente Trace

Página Integration Center

Melhores práticas de integração

Regras de análise e compatibilidade de parâmetros

Perguntas frequentes