> For the complete documentation index, see [llms.txt](https://library.zoom.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://library.zoom.com/technical-library/pt/servicos-corporativo-for-plan/zoom-virtual-agent/zoom-virtual-agent-analytics-reporting.md).

# Análises e Relatórios

Explore relatórios do Zoom Virtual Agent, métricas do Painel, filtros e insights de engajamento.

### Análises e relatórios para Zoom Virtual Agent

Os administradores podem criar uma única assinatura contendo os diferentes relatórios descritos nesta seção. Eles podem filtrar assinaturas por agentes específicos, grupos de agentes ou tipos de denunciar, como Overview, Virtual Agent Performance, Knowledge Performance, Query Insight, Conversation Details e Consumer Engagement Surveys. Os destinatários recebem um único e-mail com todos os relatórios selecionados, identificados pelo tipo de denunciar e pelo escopo do agente.

As assinaturas de relatórios agora oferecem cadência de entrega ampliada, cobertura do Painel e conteúdo do e-mail. Os administradores podem Escolher qualquer dia da semana para a entrega semanal ou mudar para a entrega diária. Uma seleção mais ampla de painéis autorizados está Disponível para assinatura, e o modelo de e-mail de denunciar foi revisado para incluir mais métricas e um resumo gerado por IA.

Os filtros do Painel também suportam precisão por hora do dia e vistas guardadas. Além de intervalos de datas, os administradores podem definir horas de início e de fim até à hora e ao minuto para isolar uma janela, como um único turno de trabalho ou um período de tráfego de pico, e também estão disponíveis intervalos de datas relativos. Um painel filtrado pode ser guardado como uma vista com nome que captura os seus filtros e seleções de gráficos para reutilização rápida, e uma vista guardada pode ser partilhada com todos os utilizadores da conta.

Nos relatórios Detalhes da conversa e Insights de consultas, uma vista guardada também armazena o esquema da tabela: a seleção das colunas, a ordem das colunas e a direção da ordenação. Ao reabrir a vista, a tabela é restaurada exatamente como foi configurada, para que os administradores não tenham de reorganizar as colunas nem voltar a ordenar os dados em cada visita.

As subscrições de relatórios podem incluir uma vista guardada. Ao configurar uma subscrição, os administradores podem selecionar uma vista guardada, e os envios agendados refletem essa vista em vez da versão padrão do relatório. Assim, os relatórios enviados por e-mail correspondem à mesma estrutura de dados que os administradores analisam na tela.

#### <mark style="color:azul;">O Data Dictionary fornece definições de métricas transparentes para as análises do Virtual Agent</mark>

As análises do Zoom Virtual Agent incluem um Data Dictionary integrado. Os administradores podem navegar pelos conjuntos de dados e relatórios para entender definições de métricas, cálculos, filtros e orientação de interpretação. As definições podem ser exportadas para compartilhamento, ajudando a esclarecer KPIs e incentivar a adoção entre as equipes.

#### <mark style="color:azul;">As métricas do Painel oferecem drill-down no próprio local e dicas de ferramenta nas colunas</mark>

Os administradores podem clicar em qualquer métrica no Painel do Zoom Virtual Agent para fazer drill-down nas conversas por trás dela. Filtros Ativo do Painel são aplicados automaticamente, para que você possa ir da lista de conversas a uma transcrição individual e voltar sem perder o contexto. Cada tabela de denunciar também adiciona dicas de ferramenta em seus cabeçalhos de coluna. Passe o mouse sobre uma métrica para ver sua definição e um link direto para a entrada completa do Data Dictionary.

#### <mark style="color:azul;">O denunciar Virtual Agent Performance detalha os resultados de Ferramenta, Habilidade e latência durante o engajamento do usuário final</mark>

A denunciar de desempenho do Virtual Agent fornece dados para indicadores-chave de desempenho do agente de IA.

* **Métricas principais:** Número de ferramentas invocadas, únicas e total; número de competências invocadas, únicas e total; métricas de latência (latência do primeiro token P90/P50); tendência da latência; taxa de contenção; taxa de escalonamento; utilização do envolvimento; e poupança de custos.
  * **Métrica de iniciação**: Uma nova métrica melhorada que mede quando e como os envolvimentos são iniciados, proporcionando uma visibilidade mais clara sobre a forma como os utilizadores acedem à experiência do Virtual Agent. Esta métrica ajuda os administradores a avaliar o desempenho dos pontos de entrada, analisar estratégias de Roteamento e compreender como as alterações aos fluxos de trabalho ou às interfaces de entrada influenciam o comportamento geral dos envolvimentos.
  * **Métricas do total de mensagens**: Fornece contagens agregadas de todas as mensagens trocadas nos envolvimentos do Zoom Virtual Agent e do Zoom AI Expert Assist. Estas métricas ajudam os administradores a analisar o volume de conversas, comparar padrões de mensagens entre canais e compreender melhor a carga multimodal nos fluxos de trabalho de Suporte orientados por IA.
  * **Medidas de proteção**: Uma vista agregada da atividade das medidas de proteção de segurança do back-end, incluindo o total de violações, a taxa de violações por cada 1000 envolvimentos, uma discriminação por categoria e uma tendência ao longo do tempo. Ao aprofundar a análise, a vista agregada abre as conversas afetadas no relatório Detalhes da conversa, pré-filtradas pela categoria de medida de proteção selecionada. Os relatórios de medidas de proteção abrangem voz e chat.
* **Filtros:** Intervalo de datas, tipo de agente (voz, chat, chatbot) e agente de IA específico.
  * **Grupos de tópicos** também estão disponíveis como filtro e dimensão de exibição nos relatórios de análises, permitindo que os supervisores consultem dados de desempenho por categoria empresarial.
* **Caso de uso:** Ajuda os administradores a avaliar a eficiência dos agentes de IA, monitorar a utilização de ferramentas e habilidades e acompanhar as tendências de latência e contenção para melhorar o desempenho e o retorno sobre o investimento (ROI).

{% hint style="info" %}
**Nota**

O denunciar do AI Agent tem uma configuração de economia de custos que afeta o desempenho do agente virtual com base em um custo de token predefinido.
{% endhint %}

#### <mark style="color:azul;">O denunciar de Desempenho do Conhecimento fornece detalhes sobre como os artigos de conhecimento são usados durante os atendimentos</mark>

Este denunciar oferece uma visão sobre como os artigos da sua Base de Conhecimento contribuem para resolver os problemas dos seus Clientes/clientes.

* **Métricas principais**: Interações assistidas por conhecimento, taxa de interações assistidas por conhecimento, artigos referenciados e média de artigos referenciados por interação.
* **Filtros**: Intervalo de datas, tipo de agente (voz, chat, chatbot), agente de IA específico e fonte do artigo.
  * O filtro de fonte do artigo tem dois valores — sugerido por IA e adicionado manualmente — e cada linha do artigo mostra um rótulo de fonte, para que os administradores possam auditar quanto o mecanismo de recomendação está contribuindo.
* **Caso de utilização**: Ajuda os administradores a avaliar a eficácia dos conteúdos de conhecimento e a otimizá-los para melhorar as taxas de resolução.
* **Insígnias de Ativo/Inativo da KB**: Estes Recursos adicionam um ícone em forma de insígnia aos artigos da KB que foram substituídos ou atualizados. As versões antiga e nova permanecem visíveis no denunciar ZVA, com indicadores de estado claros que mostram se cada artigo está ativo ou inativo.

A tabela de artigos inclui uma coluna designada **Contenção** que apresenta a taxa de contenção de cada artigo nas interações por chat e voz. A taxa é o número de interações contidas que utilizaram o artigo dividido pelo número total de interações que o utilizaram. Isto mostra aos administradores quais os artigos que efetivamente ajudam a resolver problemas, e não apenas quais os que o agente recupera.

Os administradores também podem ver por que motivo os utilizadores finais classificaram um artigo como não útil. O widget **Distribuição dos motivos de avaliação como não útil** , em **Análises e denunciar** > **Desempenho da base de conhecimento**, detalha os envios pouco úteis por motivo selecionado pelo usuário final. Selecionar um motivo no gráfico filtra a visualização, permitindo que os administradores identifiquem por que artigos específicos têm desempenho inferior e priorizem as atualizações de conteúdo.

#### <mark style="color:azul;">O denunciar Query Insight oferece uma visão detalhada das consultas dos consumidores tratadas por agentes virtuais</mark>

Este denunciar fornece uma visão panorâmica dos dados de consulta, incluindo volume de consultas, cobertura de correspondência, ligação de engajamento e resultados ao nível do tópico.

* **Principais métricas:** Total de consultas, média de consultas por interação, tópicos populares, tópicos resolvidos, tópicos encaminhados e tendências de correspondência de consultas.
* **Filtros:** Intervalo de datas, tipo de agente (voz, chat, chatbot), agente de IA, tipo de correspondência da consulta, artigo, tópico, resultado da interação, base de conhecimento e idioma.
* **Caso de uso:** Ajuda administradores e analistas a compreender o comportamento das consultas, avaliar a cobertura dos tópicos e identificar áreas para melhorar a qualidade das respostas e o desempenho da automação.

As análises do Zoom Virtual Agent também oferecem Grupos de Tópicos, uma hierarquia de dois níveis que organiza automaticamente tópicos granulares em categorias alinhadas ao negócio, como "Faturamento e Pagamentos" ou "Envio e Entrega". Os supervisores podem identificar os principais motivos de contato à primeira vista através do nível da categoria, mantendo ao mesmo tempo a capacidade de analisar mais profundamente tópicos específicos.

As regras de redação configuradas nas preferências do tenant do Zoom Virtual Agent agora se aplicam de forma uniforme em todo o painel Query Insights, incluindo a lista de consultas e as vistas de detalhe. Anteriormente, estas áreas apresentavam enunciados brutos independentemente do conjunto de regras configurado; agora respeitam o mesmo conjunto de regras de redação que o restante do produto.

O relatório Insights de consultas suporta três opções de exportação: a vista da tabela de consultas, os dados de envolvimento das consultas listadas na tabela e os rastos dos agentes relativos a esses envolvimentos.

#### <mark style="color:azul;">As análises de comparação mostram dois recortes de dados lado a lado</mark>

Os administradores podem comparar dois recortes de dados diretamente nos painéis do Zoom Virtual Agent, sem exportar nem mudar de ecrã. Em qualquer relatório, clique em Comparar, selecione um conjunto de filtros e o painel é apresentado novamente num layout de duas coortes para que possa ler os dois recortes em comparação. As análises de comparação funcionam em conjunto com as funcionalidades de exploração detalhada e de filtragem cruzada do painel.

#### <mark style="color:azul;">A filtragem cruzada recalcula as visualizações do painel por dimensão</mark>

Os supervisores podem clicar num valor dimensional nas páginas Query Insights, Detalhes da Conversa, Desempenho da Base de Conhecimento e Desempenho do Agente para filtrar cruzadamente todas as visualizações da página. Os valores clicáveis incluem tópicos, agentes, ferramentas ou segmentos do gráfico.

Um chip de filtro mostra a seleção Ativo e pode ser removido clicando em **x**, selecionando o valor novamente ou clicando fora dele. É possível combinar vários filtros cruzados entre si e com as configurações existentes da barra de filtros para mostrar resultados correspondentes. Ao passar o cursor sobre um elemento filtrável, o cursor muda para o formato de ponteiro e aparece uma dica que antecipa a ação.

#### <mark style="color:azul;">O relatório Detalhes da Conversa fornece insights de conversas baseados em engajamento para agentes virtuais</mark>

A geração de relatórios Detalhes da Conversa fornece dados para os principais indicadores de engajamento do agente de IA.

* **Métricas principais:** Total de interações, interações com vários turnos, duração média e total das interações e registos de interação com metadados (tópicos, ferramentas, competências, motivos de escalonamento e responsáveis). Em implementações com várias instâncias, o relatório também inclui um **Instância** coluna que identifica qual instância tratou cada interação.
* **Filtros:** Intervalo de datas, tipo de agente (voz, chat, chatbot), agente de IA, ferramenta, resultado do envolvimento, último a responder, competência, tópico, transferência aceite (apenas voz) e acionamento da salvaguarda de fim pelo agente de IA (apenas voz) e — para implementações com várias instâncias — instância e grupo de instâncias.
* **Caso de utilização:** Permite que os administradores analisem a qualidade do envolvimento, acompanhem o desempenho dos agentes de IA e das competências e revejam o comportamento ao nível das conversas para efeitos de otimização, supervisão operacional e relatórios internos.

Quando uma conversa aciona uma barreira de segurança de back-end, o relatório Detalhes da Conversa assinala-a com uma insígnia de barreira de segurança na interação afetada e um painel que mostra quais categorias de barreira foram acionadas e em que turno. Os administradores podem filtrar a lista de interações por categoria de infração — por exemplo, crimes violentos, abuso do Intérprete de código, privacidade ou difamação — para rever apenas as conversas que acionaram uma regra. Estas são as barreiras de segurança de back-end do Zoom, não barreiras que um administrador escreve nas Orientações do Agente.

Detalhes da Conversa também inclui uma faixa de visualização configurável no topo do Painel. Pode criar as suas próprias visualizações para variáveis — tanto do sistema como personalizadas — escolhendo entre gráficos de setores, barras e linhas. As visualizações podem ser adicionadas, movidas e redimensionadas, e as suas configurações persistem ao nível da conta para a sua próxima sessão. Os gráficos fixados respeitam os filtros ativos da página, dando-lhe uma visão clara da distribuição das variáveis exatamente onde precisa dela.

#### <mark style="color:azul;">O denunciar de Pesquisas de Envolvimento do Consumidor apresenta o Feedback/feedback do consumidor recolhido através de inquéritos pós-interação no Zoom Virtual Agent</mark>

Este denunciar reúne Feedback/feedback de pesquisas pós-engajamento para medir a satisfação dos consumidores, o sucesso da resolução e as oportunidades de melhoria.

* **Principais métricas:** Atribuído ao agente, lançamentos, respostas, taxa de resposta, taxa de conclusão, tendência de lançamentos, respostas às perguntas da pesquisa e distribuição de feedback em texto livre.
* **Filtros:** Intervalo de datas, agente de IA e bot (incluindo variantes, caso existam várias).
* **Caso de uso:** Permite que os administradores avaliem o sentimento dos clientes, meçam o desempenho do chatbot e identifiquem oportunidades para melhorar a qualidade dos atendimentos e a satisfação dos usuários.

#### <mark style="color:azul;">As métricas de resolução implícita inferem os resultados dos clientes a partir do comportamento de envolvimento</mark>

Os administradores podem avaliar o desempenho do agente virtual com resolução implícita, que infere automaticamente a resolução e a satisfação do usuário com base no comportamento real, como a conclusão de fluxos de trabalho e os níveis de interação.

Esta métrica oferece uma alternativa aos inquéritos tradicionais quando as taxas de resposta de CSAT explícitas são baixas. Também funciona em conjunto com as métricas baseadas em inquéritos existentes, em vez de as substituir. Os dados de resolução implícita estão disponíveis no Portal web do Zoom, na API ou em relatórios para download, ajudando os administradores a otimizar a eficácia do Zoom Virtual Agent.

A lógica que determina a resolução implícita foi aperfeiçoada para interpretar as conversas com mais precisão, reduzindo as classificações incorretas em ambas as direções. Como resultado, a Taxa de Resolução reflete com maior exatidão os resultados reais. Os administradores poderão observar uma ligeira variação da métrica à medida que a melhoria entra em vigor.

As análises do Zoom Virtual Agent também apresentam uma métrica de **resolução sem retorno** para voz e chat. Um atendimento é considerado resolvido sem retorno quando é resolvido sem encaminhamento e o mesmo cliente não volta a entrar em contato dentro do período de retorno definido. Como combina a contenção com o que o cliente faz em seguida, essa métrica oferece aos administradores um indicador mais confiável da resolução efetiva do que a contenção por si só.

As Configurações relacionadas com os relatórios de cada agente são definidas numa secção dedicada às Configurações de relatórios da configuração do agente. Essa secção reúne três definições: objetivos alcançados, resultados das conversas e resolvido sem retorno. Estas definições afetam apenas os relatórios, não o comportamento do agente. Os objetivos alcançados e os resultados das conversas aplicam-se aos agentes de chamadas Realizadas, e a definição resolvido sem retorno aplica-se aos agentes de chamadas Recebidas.

#### <mark style="color:azul;">O Registo de Interações fornece um registo detalhado de cada interação com agentes de IA e de voz, incluindo resultados, duração e transcrições para gravar e rever</mark>

<div data-with-frame="true"><img src="https://1821044411-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FctBXUMeBy4rtLMmMkKRG%2Fuploads%2FBekwbdgq0PzE6LyvSslJ%2Funknown.png?alt=media&amp;token=228a0e64-0379-4341-8546-1567ff1ccd6d" alt=""></div>

O registro de engajamento fornece uma visão detalhada de cada interação tratada pelos seus agentes de IA ou de voz. Ele ajuda você a analisar como cada conversa foi conduzida, se foi contida pela IA ou encaminhada para um agente ao vivo, e as principais métricas de desempenho desse engajamento.

Este denunciar é valioso para supervisores, administradores e analistas que precisam de visibilidade sobre a eficácia dos agentes, a experiência do cliente e o desempenho do sistema.

**Principais colunas no registro de engajamento**

* **ID do atendimento**: Um identificador exclusivo para cada interação. Você pode usar esse ID para pesquisar e analisar conversas específicas.
* **Canal**: Indica se o atendimento ocorreu por meio de um agente de chat ou de voz.
* **Origem**: Mostra o ponto de entrada em que a interação foi iniciada, como a central de contato Zoom.
* **Cliente**: O cliente ou usuário final que iniciou o atendimento. Pode aparecer como um número de telefone para chamadas de voz ou como um Nome de usuário para sessões de chat.
* **Agente de IA**: Identifica o agente de IA que realizou a interação.
* **Ferramenta / Habilidade / Tópico / Artigo**: Mostra quais ferramentas, habilidades ou recursos de conhecimento o agente de IA usou durante o atendimento, como "consultar status do chamado" ou "solicitação de transferência para um agente".
* **Resultado do atendimento**: O resultado final do atendimento. "Contenção" significa que o agente de IA resolveu o problema sem encaminhamento. "Encaminhamento" indica que a interação foi transferida para um agente humano. Os motivos do encaminhamento são apresentados quando aplicável, como "encaminhamento previsto" ou "encaminhamento solicitado".
* **Hora de início / Hora de término**: As datas e horas de início e término do atendimento.
* **Último respondente**: Indica quem concluiu o atendimento: o agente de IA ou um agente humano após o encaminhamento.
* **Duração do atendimento**: O tempo total de duração do atendimento.
* **Turnos de interação**: O número de trocas de mensagens ou falas entre o agente de IA e o cliente.
* **Duração da interação**: O tempo durante o qual o cliente participou da interação, especialmente útil para chamadas de voz.
* **Transferência aceita / Agente de IA saiu**: Mostra se a transferência para um agente humano foi bem-sucedida e se o agente de IA saiu do atendimento.

Este relatório oferece suporte à auditabilidade, revisão e treinamento, fornecendo trilhas de auditoria que podem melhorar o desempenho tanto da IA quanto do agente humano.

Por exemplo, se o Agente de Helpdesk de TI mostrar um alto número de escalonamentos para tarefas de criação de tickets, os supervisores podem revisar transcrições para identificar por que os usuários estão solicitando um agente humano e atualizar a configuração da IA ou os dados de treinamento.

**Agent Tracing fornece visibilidade passo a passo sobre a tomada de decisão do agente virtual**

Ao revisar um engajamento, os administradores podem usar o Agent Tracing para ver a cadeia completa de decisões, desde o processamento da entrada até a resposta final. Isso oferece suporte à solução de problemas, à revisão de Garantia de Qualidade e à otimização do desempenho.

O Agent Tracing fornece um rastreamento unificado, legível por humanos, vinculado a um engajamento específico. Inclui uma transcrição completa do cliente juntamente com as ações do sistema. Cada etapa do pipeline é marcada com data e hora, com durações de início e fim.

O Agent Tracing inclui:

* Captura da entrada
* Classificação de NLU/intenção
* Etapas de pesquisa e recuperação (ou seja, reescrita de consultas e seleção de fontes)
* Inferência do LLM
* Chamadas de ferramenta/função
* Renderização da resposta

O Agent Tracing também fornece resumos no nível do engajamento que aceleram a solução de problemas. Um resumo de chamadas de ferramenta lista todas as ferramentas invocadas durante o engajamento, cada uma com seu status de sucesso ou falha, para que os administradores não precisem mais examinar o rastreamento turno a turno para encontrar uma chamada específica. Um resumo de variáveis oferece uma visão consolidada de cada variável definida durante o mesmo engajamento. Juntos, esses resumos destacam execuções de script, gatilhos de habilidade e o caminho geral da interação de relance.

O Agent Tracing também captura rastreamento detalhado e informações de depuração para ferramentas nativas, incluindo a ferramenta SMS, a ferramenta de e-mail, salvar resposta e encerrar conversa. Para cada invocação de ferramenta, o rastreamento registra o motivo pelo qual a ferramenta foi selecionada, os parâmetros de entrada passados, a saída da resolução de variáveis, o status de execução e quaisquer erros retornados. O rastreamento também mostra por que uma conversa terminou, incluindo se foi acionada por uma instrução ou por um tempo limite após novas tentativas de lembrete.

{% hint style="info" %}
**Nota**

Você pode encontrar o Agent Tracing nas análises do Virtual Agent. Ele está acessível a partir do Registro de engajamento ao revisar interações individuais.
{% endhint %}

Para validar alterações no agente antes da implantação, veja a seção de Avaliação abaixo.

#### <mark style="color:azul;">A Avaliação valida alterações no agente antes da implantação por meio de testes de cenários e comparação de versões</mark>

Ao alterar a configuração de um agente, a orientação, as Skills ou as Ferramentas, os administradores precisam verificar se essas alterações não degradarão o desempenho antes de publicar em produção. A Avaliação oferece um ambiente de teste estruturado para isso.

Os administradores podem executar avaliações em qualquer versão do agente publicada ou histórica, não apenas no rascunho atual. As avaliações são executadas em modo somente leitura no instantâneo da versão selecionada, portanto o agente Ativo não é modificado. Isso ancora os resultados em uma configuração específica e conhecida.

Em seguida, você pode avaliar duas versões do agente lado a lado usando o mesmo conjunto de cenários. Os resultados exibem métricas por versão (como taxas de sucesso dos cenários, pontuações de correspondência de comportamento e muito mais), para que os administradores possam ver exatamente onde o desempenho mudou entre as versões. Uma visualização detalhada da transcrição permite que os administradores examinem casos de teste individuais para ver como as respostas diferem.

Antes de uma avaliação ser executada, o sistema valida a integridade dos casos de teste. Isso inclui verificar ferramentas ausentes, variáveis não definidas ou incompatibilidades de esquema. Isso evita execuções de avaliação desperdiçadas e elimina falsos negativos causados por erros de configuração, em vez do comportamento real do agente.

A Avaliação apoia os esforços dos administradores para fazer alterações no agente prontas para produção, o que pode ajudar a acelerar os ciclos de iteração e gerenciar o risco. Combinada com o Agent Tracing, ela cria um fluxo de trabalho robusto de diagnóstico e validação.

#### <mark style="color:azul;">O Painel do ZVA Receptionist oferece às implantações menores uma visão de desempenho em uma única tela</mark>

Para implantações menores do ZVA Receptionist que não precisam do pacote completo de análises, um painel em uma única tela apresenta o desempenho em linguagem simples. Cada valor é agregado a partir das métricas existentes, portanto não é necessária nenhuma nova instrumentação. Uma linha de destaque mostra ligações atendidas, tempo de chamadas atendidas (expresso em horas) e custo economizado. Um anel de contenção se combina com uma contagem de escalonamentos e um link "Leia estas conversas" que leva diretamente aos engajamentos subjacentes. O painel também apresenta os principais motivos pelos quais as pessoas ligaram e um detalhamento de resultados resolvidos/não resolvidos, e uma tabela por agente e um registro simplificado de conversas completam a tela — tudo delimitado por uma única linha de filtro.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://library.zoom.com/technical-library/pt/servicos-corporativo-for-plan/zoom-virtual-agent/zoom-virtual-agent-analytics-reporting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
