As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Monitore agentes de IA usando CloudWatch
Para obter visibilidade das recomendações em tempo real que os agentes de IA fornecem aos seus agentes e das intenções do cliente que eles detectam por meio da compreensão da linguagem natural, você pode consultar CloudWatch os registros. CloudWatch Os registros oferecem visibilidade de toda a jornada de contato: a conversa, os gatilhos, as intenções e as recomendações. Você também pode usar essas informações para depuração ou fornecê-las Suporte quando entrar em contato com eles para obter ajuda.
Este tópico explica como habilitar o registro em log para agentes de IA.
**Topics**
+ [Permissões obrigatórias do IAM](#permissions-cw-q)
+ [Habilitar registro em log](#enable-assistant-logging)
+ [Tipos de log compatíveis](#supported-log-types-q)
+ [Verifique as cotas CloudWatch de registros](#cwl-quotas)
+ [Documentando CloudWatch eventos usando o Interactive Handler](#documenting-cw-events-ih)
+ [Exemplos de consultas comuns para depurar logs do assistente](#example2-assistant-log)
## Permissões obrigatórias do IAM
Antes de ativar o registro em um assistente do Connect, verifique se você tem as seguintes AWS Identity and Access Management permissões. Eles são necessários para a conta de usuário que está conectada ao console Connect Customer:
+ `wisdom:AllowVendedLogDeliveryForResource`: necessário para permitir a entrega de logs para o recurso de assistente.
Consulte um exemplo de perfil do IAM com todas as permissões necessárias para seu destino de registro em log específico em [Logging that requires additional permissions [V2]](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html#AWS-vended-logs-permissions-V2). Esse tópico contém exemplos de diferentes destinos de registro, como registros enviados para registros e CloudWatch registros enviados para o Amazon S3. Os exemplos mostram como permitir atualizações em seu recurso específico de destino de registro.
## Habilitar o registro para agentes de IA
Para ativar o registro para agentes de IA, você usa a CloudWatch API. Execute as etapas a seguir.
1. Obtenha o ARN do seu * assistente * (também conhecido como [* domínio *](ai-agent-initial-setup.md#ai-agent-requirements)). Depois de [ criar um assistente](ai-agent-initial-setup.md#enable-ai-agents-step1), você pode obter seu ARN no console Connect Customer ou chamando a [ GetAssistant ](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_GetAssistant.html) API. O ARN segue esse formato:
`arn:aws:wisdom:your-region:your-account-id:assistant/assistant-id`
1. Chamada [ PutDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html): use essa CloudWatch API para criar uma fonte de entrega para o assistente. Passe o ARN do assistente como o `resourceArn`. Para `logType`, especifique `EVENT_LOGS` a fim de coletar logs do assistente.
```
{
"logType": "EVENT_LOGS",
"name": "{{your-assistant-delivery-source}}",
"resourceArn": "arn:aws:wisdom:{{your-region}}:{{your-account-id}}:assistant/{{assistant_id}}
}
```
1. Chamada [ PutDeliveryDestination](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html): use essa CloudWatch API para configurar onde os registros serão armazenados. Você pode escolher CloudWatch Logs, Amazon S3 ou Amazon Data Firehose como destino para armazenar registros. Você deve especificar o ARN de uma das opções de destino de onde seus logs serão armazenados. Você pode escolher o `outputFormat` dos logs como um destes: `json`, `plain`, `w3c`, `raw` ou `parquet`.
O exemplo a seguir mostra como configurar os registros para serem armazenados em um grupo de CloudWatch registros da Amazon e no formato JSON.
```
{
"deliveryDestinationConfiguration": {
"destinationResourceArn": "arn:aws:logs:{{your-region}}:{{your-account-id}}:log-group:{{your-log-group-name}}:*"
},
"name": "string",
"outputFormat": "json",
"tags": {
"key": "value"
}
}
```
1. Chamada [ CreateDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html): use essa CloudWatch API para vincular a fonte de entrega ao destino de entrega que você criou nas etapas anteriores. Essa operação de API associa a fonte de entrega ao destino final.
```
{
"deliveryDestinationArn": "string",
"deliverySourceName": "string",
"tags": {
"string": "string"
}
}
```
O exemplo a seguir mostra como executar as etapas anteriores como uma sequência de comandos da AWS CLI. Este exemplo habilita o registro de eventos para um assistente e envia os registros para um grupo de CloudWatch registros do Amazon Logs. Execute os comandos em ordem e substitua cada um {{value}} por seus próprios nomes de recursos e ARNs.
1. Crie uma fonte de entrega para o assistente. Use o ARN assistente como o ARN do recurso e especifique `EVENT_LOGS` como o tipo de registro.
```
aws logs put-delivery-source \
--name {{your-assistant-delivery-source}} \
--resource-arn arn:aws:wisdom:{{your-region}}:{{your-account-id}}:assistant/{{assistant-id}} \
--log-type EVENT_LOGS
```
1. Crie um destino de entrega que aponte para seu grupo de registros. Em vez disso, para enviar logs para o Amazon S3 ou o Amazon Data Firehose, especifique o ARN desse recurso.
```
aws logs put-delivery-destination \
--name {{your-delivery-destination}} \
--delivery-destination-configuration "destinationResourceArn=arn:aws:logs:{{your-region}}:{{your-account-id}}:log-group:{{your-log-group-name}}" \
--output-format json
```
1. Vincule a origem da entrega ao destino da entrega. Use o ARN de destino que o comando anterior retorna.
```
aws logs create-delivery \
--delivery-source-name {{your-assistant-delivery-source}} \
--delivery-destination-arn arn:aws:logs:{{your-region}}:{{your-account-id}}:delivery-destination:{{your-delivery-destination}}
```
Depois de criar a entrega, você pode visualizar os eventos registrados no seu grupo de registros. Para confirmar se o registro funciona, gere a atividade do assistente e, em seguida, consulte o grupo de registros conforme descrito em[Exemplos de consultas comuns para depurar logs do assistente](#example2-assistant-log).
## Tipos de log compatíveis
Os agentes de IA oferecem suporte ao seguinte tipo de registro:
+ `EVENT_LOGS`: registros que rastreiam eventos de um assistente do Connect durante chamadas, bate-papos, tarefas e e-mails.
## Verifique as cotas CloudWatch de registros
Recomendamos verificar CloudWatch os endpoints e cotas do [ Amazon Logs ](https://docs.aws.amazon.com/general/latest/gr/cwl_region.html) para ver se há alguma cota para fazer CloudWatch chamadas de API relacionadas à entrega do Logs. As cotas definem um número máximo de vezes que você pode chamar uma API ou criar um recurso. Exceder o limite resulta em um erro `ServiceQuotaExceededException`.
## Documentando CloudWatch eventos usando o Interactive Handler
### Definições dos tipos de evento
A tabela a seguir descreve cada tipo de evento. Observe que diferentes tipos de evento contêm campos diferentes. Consulte a seção [Definições dos campos](#field-definitions) para obter informações detalhadas sobre cada campo.
| EventType | Definição |
| --- | --- |
| TRANSCRIPT\_CREATE\_SESSION | Registrado quando uma nova sessão de agentes de IA é criada. Isso marca o início de uma conversa. |
| TRANSCRIPT\_INTENT\_TRIGGERING\_REFERENCE | Registrado quando uma intenção específica do cliente é detectada na conversa, o que pode acionar respostas ou fluxos de trabalho automatizados. |
| TRANSCRIPT\_LARGE\_LANGUAGE\_MODEL\_INVOCATION | Registrado em log quando um grande modelo de linguagem (LLM) é invocado para gerar respostas ou processar conteúdo de conversa. Registra as entradas e saídas do LLM. |
| TRANSCRIPT\_QUERY\_ASSISTANT | Registrado quando um dos seguintes agentes de IA é invocado: AnswerRecommendation, CaseSummarization,, EmailGenerativeAnswer, EmailOverview EmailResponse, ManualSearch. NoteTaking |
| TRANSCRIPT\_RECOMMENDATION | Registrado quando o sistema fornece uma recomendação a um agente ou cliente, que pode incluir artigos de conhecimento, respostas geradas ou ações sugeridas. |
| TRANSCRIPT\_RESULT\_FEEDBACK | Registrado em log quando é fornecido feedback sobre a utilidade ou relevância de um resultado de pesquisa ou consulta. |
| TRANSCRIPT\_SELF\_SERVICE\_MESSAGE | Registrado quando um cliente interage com um agente de IA SelfService |
| TRANSCRIPT\_SESSION\_POLLED | Registrado quando o sistema detecta que um agente está conectado a uma sessão (uma sessão é pesquisada quando uma chamada de GetRecommendations API é feita) |
| TRANSCRIPT\_TRIGGER\_DETECTION\_MODEL\_INVOCATION | Registrado em log quando o modelo de detecção de gatilho é invocado para determinar se uma conversa tem intenções. |
| TRANSCRIPT\_UTTERANCE | Registrado em log quando uma mensagem é enviada por qualquer participante da conversa, registrando o conteúdo real da conversa. |
| MENSAGEM\_DE\_ORQUESTRAÇÃO\_DE\_TRANSCRIÇÃO | Registrado para cada etapa de um ciclo de orquestração, incluindo a mensagem inicial do cliente, as respostas de texto do bot, o raciocínio, as solicitações de uso da ferramenta e os resultados da ferramenta. Captura todos os detalhes do raciocínio agente de várias voltas realizado por um agente de IA de orquestração. |
| ERRO\_DE\_ORQUESTRAÇÃO DE TRANSCRIÇÃO | Registrado quando ocorre um erro durante a orquestração, como exceder o número máximo de iterações de orquestração, restrições de capacidade do sistema ou uma falha geral na orquestração. |
| TRANSCRIPT\_AI\_AGENT\_TRACE | Registrado para cada período de execução durante a orquestração do agente de IA, capturando rastreamentos detalhados, incluindo configuração do LLM, uso de tokens, mensagens e resultados da avaliação do guardrail. |
### Definições dos campos
A tabela a seguir descreve cada campo.
| Campo | Definição |
| --- | --- |
| ai\_agent\_id | Identificador exclusivo para o recurso do agente de IA. |
| assistant\_id | Identificador exclusivo para o recurso Connect Assistant. |
| completion | O texto de conclusão bruto retornado pelo LLM ou gerado para a mensagem. |
| connect\_user\_arn | O nome do recurso da Amazon (ARN) do usuário do Connect que está acessando a sessão. |
| event\_timestamp | Carimbo de data/hora do Unix (em milissegundos) de quando o evento ocorreu. |
| event\_type | Tipo do evento, indicando qual ação ou processo ocorreu no sistema. |
| generation\_id | Identificador exclusivo para uma AI-generated resposta específica. |
| intent | O texto ou a descrição da intenção. |
| intent\_clicked | Booleano indicando se a recomendação foi acionada por uma intenção clicada. |
| intent\_id | Identificador exclusivo da intenção detectada. |
| issue\_probability | Probabilidade numérica (de 0,0 a 1,0) de que um problema tenha sido detectado na conversa (uma probabilidade maior que 0,5 invocará a geração de intenção). |
| is\_recommendation\_useful | Booleano indicando se o usuário achou o resultado útil. |
| is\_valid\_trigger | Booleano indicando se a análise do modelo de detecção resultou em um gatilho válido. |
| model\_id | Identificador do modelo de IA usado para invocar o LLM. |
| parsed\_response | A processed/parsed versão da resposta do modelo de linguagem, geralmente em formato estruturado. |
| prompt | O prompt de entrada usado para invocar o LLM. |
| prompt\_type | Tipo de prompt de IA usado para processar a mensagem ou consulta. |
| recomendação | O conteúdo real do texto da recomendação fornecida ao usuário. |
| recommendation\_id | Identificador exclusivo da recomendação. |
| resposta | O texto final da resposta gerada para o usuário após o processamento. |
| session\_event\_id | Identificador exclusivo para um evento específico na sessão. |
| session\_event\_ids | Lista de identificadores de eventos da sessão. |
| session\_id | Identificador exclusivo para a sessão dos agentes de IA. |
| session\_message\_id | Identificador exclusivo para uma mensagem de autoatendimento em uma sessão. |
| session\_name | O nome da sessão. |
| enunciado | O texto real da mensagem trocada na conversa. |
| id\_do\_orquestração | Identificador exclusivo para a execução da orquestração. Corresponde ao ID inicial da mensagem do cliente que acionou a orquestração. |
| orquestração\_iteração | O número da iteração dentro do loop de orquestração. |
| ai\_agent\_orchestration\_use\_case | O caso de uso do orquestrador, como CONNECT\_AGENT\_ASSISTANCE ou. CONNECT\_SELF\_SERVICE |
| participante | A função do participante na mensagem, como CUSTOMER ouBOT. |
| values | JSON-serialized lista de valores de mensagens. Cada entrada tem um tipo: text (com um valor de texto), tool\_use (com ferramentaUseId, ID de ferramenta, nome e argumentos), tool\_result (com ferramentaUseId, ID de ferramenta, nome, valores e erro) ou reasoning (com um valor de texto). |
| guardrail\_locked | Booleano que indica se a resposta foi bloqueada por uma barreira de inteligência artificial. |
| erro\_de\_orquestração | JSON-serialized detalhes do erro contendo errorMessage um errorDetails objeto opcional (com estimatedInputTokens eestimatedOutputTokens). |
| extensão | JSON-serialized mapa do objeto de extensão total. Cada chave é snake\_case. As chaves notáveis incluem input\_messages (histórico de conversas enviado ao modelo), output\_messages (mensagens de resposta do modelo), guardrail\_assessments (lista de resultados da avaliação de proteção comguardrailId,, guardrailName sourceaction, epolicies) e input\_messages\_truncated ("true"quando as mensagens de entrada foram truncadas para caber no limite de registro de 256 KB). Presente somente quando event\_type estáTRANSCRIPT\_AI\_AGENT\_TRACE. |
### Exemplos de logs do assistente
Abaixo estão exemplos de logs de eventos diferentes para cada tipo de evento. Consulte a seção [Definições dos tipos de evento](#event-type-definitions) para obter explicações detalhadas de cada tipo de evento.
#### CreateSession
```
{
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530173612,
"event_type": "TRANSCRIPT_CREATE_SESSION",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"session_name": "nabbccdd-9999-4b23-aaee-112233445566"
}
```
#### IntentTriggeringReference
```
{
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530173623,
"event_type": "TRANSCRIPT_INTENT_TRIGGERING_REFERENCE",
"intent": "To learn about how to autoscale DynamoDB.",
"intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```
#### LargeLanguageModelInvocation
Reformulação de consultas
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"completion": "The customer is asking for information on how to autoscale DynamoDB.",
"event_timestamp": 1729530173645,
"event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
"generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
"intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5"
"model_id": "us.amazon.nova-lite-v1:0",
"parsed_response": "The customer is asking for information on how to autoscale DynamoDB.",
"prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
"prompt_type": "BEDROCK_KB_QUERY_REFORMULATION",
"session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```
Detecção de intenções
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"completion": "no\n - Step 2. yes\n - Step 3. To learn how to autoscale DynamoDB.",
"event_timestamp": 1729530173645,
"event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
"generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
"intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5"
"model_id": "us.amazon.nova-lite-v1:0",
"parsed_response": "To learn how to autoscale DynamoDB.",
"prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
"prompt_type": "GENERATIVE_INTENT_DETECTION",
"session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```
Geração de respostas de intenção
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"completion": "{\"citations\":[{\"citation\":{\"generatedResponsePart\":{\"textResponsePart\":{\"span\":{\"end\":1065,\"start\":0},\"text\":\"\\nDynamoDB auto s\"}}}}]}",
"event_timestamp": 1729530173645,
"event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
"generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
"intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
"model_id": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
"parsed_response": "DynamoDB auto scaling works by creating CloudWatch alarms that monitor your table's activity. When the...",
"prompt": "{\"input\":{\"text\":\"The customer is seeking information on how to autoscale DynamoDB. Key utterance: \\\"How can \"}}",
"prompt_type": "BEDROCK_KB_GENERATIVE_ANSWER",
"session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```
Geração de pesquisa manual
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"completion": "no\n - Step 2. yes\n - Step 3. To learn how to autoscale DynamoDB.",
"event_timestamp": 1729530173645,
"event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
"generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
"intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
"model_id": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
"parsed_response": "DynamoDB auto scaling works by creating CloudWatch alarms that monitor...",
"prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
"prompt_type": "BEDROCK_KB_GENERATIVE_ANSWER",
"session_id": "******************-*****************"
}
```
#### QueryAssistant
```
{
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530173667,
"event_type": "TRANSCRIPT_QUERY_ASSISTANT",
"recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```
#### Recomendação
```
{
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530173656,
"event_type": "TRANSCRIPT_RECOMMENDATION",
"intent_clicked": 1,
"intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
"recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```
#### ResultFeedback
```
{
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530173667,
"event_type": "TRANSCRIPT_RESULT_FEEDBACK",
"generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
"is_recommendation_useful": 1,
"recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff"
}
```
#### SelfServiceMessage
```
{
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"completion": "{\"citations\":[{\"generatedResponsePart\":{\"textResponsePart\":{\"span\":{\"end\":276,\"start\":0},\"text\":\"To autoscale Amazon DynamoDB...\"}}]}",
"event_timestamp": 1729530173678,
"event_type": "TRANSCRIPT_SELF_SERVICE_MESSAGE",
"model_id": "us.amazon.nova-pro-v1:0",
"parsed_response": "To autoscale Amazon DynamoDB, follow these steps:...",
"prompt": "{\"input\":{\"text\":\"how to autoscale dynamodb\"},\"retrieveAndGenerateConfiguration\":...}",
"prompt_type": "SELF_SERVICE_ANSWER_GENERATION",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"session_message_id": "mdee1234-5678-4eab-9333-ffeebb998877",
"utterance": "[Customer] How can I autoscale DyanmoDB?"
}
```
#### TranscriptSessionPolled
```
{
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"connect_user_arn": "arn:aws:connect:us-east-1:204585150770:instance/seaa9988-2233-4f44-8899-abcabcabcabc/agent/agbbccdd-9999-4b23-aaee-112233445566",
"event_timestamp": 1729530173623,
"event_type": "TRANSCRIPT_SESSION_POLLED",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"session_name": "nabbccdd-9999-4b23-aaee-112233445566"
}
```
#### TriggerDetectionModelInvocation
```
{
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530173634,
"event_type": "TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION",
"is_valid_trigger": 1,
"issue_probability": "0.87",
"session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
"session_event_ids": ["seaa9988-2233-4f44-8899-abcabcabcabc"],
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```
#### Enunciado
```
{
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530173623,
"event_type": "TRANSCRIPT_UTTERANCE",
"session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"utterance": "[Customer] My laptop won't connect to WiFi after the recent update"
}
```
#### OrchestrationMessage
Mensagem do cliente
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530173612,
"event_type": "TRANSCRIPT_ORCHESTRATION_MESSAGE",
"model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff",
"participant": "CUSTOMER",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"session_message_id": "m1234567-abcd-4ef0-9876-aabbccddeeff",
"values": "[{\"type\":\"text\",\"value\":\"How do I reset my password?\"}]"
}
```
Resposta de texto do bot
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530174234,
"event_type": "TRANSCRIPT_ORCHESTRATION_MESSAGE",
"guardrail_blocked": false,
"model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff",
"orchestration_iteration": 1,
"participant": "BOT",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"session_message_id": "mfff1234-5678-4eab-9333-112233445566",
"values": "[{\"type\":\"text\",\"value\":\"I can help you reset your password. Let me look up your account.\"}]"
}
```
Uso de ferramentas
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530174500,
"event_type": "TRANSCRIPT_ORCHESTRATION_MESSAGE",
"model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff",
"orchestration_iteration": 1,
"participant": "BOT",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"session_message_id": "maaa2222-3333-4bbb-cccc-ddddeeeeffff",
"values": "[{\"type\":\"tool_use\",\"toolUseId\":\"toolu_01ABC\",\"toolId\":\"ResetPassword\",\"name\":\"ResetPassword\",\"arguments\":{\"email\":\"customer@example.com\"}}]"
}
```
Resultado da ferramenta
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530175100,
"event_type": "TRANSCRIPT_ORCHESTRATION_MESSAGE",
"model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff",
"orchestration_iteration": 1,
"participant": "BOT",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"session_message_id": "mbbb3333-4444-5ccc-dddd-eeeeffff0000",
"values": "[{\"type\":\"tool_result\",\"toolUseId\":\"toolu_01ABC\",\"toolId\":\"ResetPassword\",\"name\":\"ResetPassword\",\"values\":[{\"type\":\"text\",\"value\":\"Password reset email sent successfully.\"}],\"error\":null}]"
}
```
Reasoning
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530175200,
"event_type": "TRANSCRIPT_ORCHESTRATION_MESSAGE",
"model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff",
"orchestration_iteration": 1,
"participant": "BOT",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"session_message_id": "mccc4444-5555-6ddd-eeee-ffff00001111",
"values": "[{\"type\":\"reasoning\",\"value\":\"The password reset was successful. I should inform the customer and ask if they need further help.\"}]"
}
```
#### OrchestrationError
O máximo de iterações de orquestração foi excedido
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530180000,
"event_type": "TRANSCRIPT_ORCHESTRATION_ERROR",
"model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"orchestration_error": "{\"errorMessage\":\"The orchestration exceeded the maximum number of iterations\"}",
"orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff",
"orchestration_iteration": 9,
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```
Restrições de capacidade do sistema
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530180000,
"event_type": "TRANSCRIPT_ORCHESTRATION_ERROR",
"model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"orchestration_error": "{\"errorMessage\":\"System capacity is constrained. We are actively working on scaling system to prevent such failures.\",\"errorDetails\":{\"estimatedInputTokens\":50000,\"estimatedOutputTokens\":2048}}",
"orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff",
"orchestration_iteration": 3,
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```
#### AIAgentTrace
Período de orquestração bem-sucedido (sem intervenção de guardrail)
```
{
"timestamp": 1729530173612,
"resource_arn": "arn:aws:wisdom:us-east-1:204585150770:assistant/a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530175612,
"event_type": "TRANSCRIPT_AI_AGENT_TRACE",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"span": {
"span_id": "7a3f2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"parent_span_id": "eb06e7cf-c3ba-4e75-86ef-ba761fd0ee30",
"span_name": "inference",
"span_type": "CLIENT",
"start_timestamp": "1729530173612",
"end_timestamp": "1729530175612",
"status": "OK",
"operation_name": "inference",
"provider_name": "aws.bedrock",
"session_name": "nabbccdd-9999-4b23-aaee-112233445566",
"ai_agent_arn": "arn:aws:wisdom:us-east-1:204585150770:ai-agent/ai112233-7a85-4b3c-8def-0123456789ab",
"ai_agent_type": "ANSWER_RECOMMENDATION",
"ai_agent_name": "MyAgent",
"ai_agent_version": "3",
"ai_agent_orchestrator_use_case": "Connect.AgentAssistance",
"request_model": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"request_max_tokens": "4096",
"temperature": "1.0",
"response_finish_reasons": "[\"end_turn\"]",
"usage_input_tokens": "5274",
"usage_output_tokens": "266",
"usage_total_tokens": "5540",
"cache_read_input_tokens": "4800",
"cache_write_input_tokens": "0",
"prompt_arn": "arn:aws:wisdom:us-east-1:204585150770:ai-prompt/prompt-abc:2",
"prompt_id": "prompt-abc",
"prompt_type": "ORCHESTRATION",
"prompt_name": "Agent Assistance Orchestration",
"prompt_version": "2",
"time_to_first_token_ms": "850",
"input_messages": "[{\"messageId\":\"msg-1\",\"participant\":\"CUSTOMER\",\"timestamp\":1729530173000,\"values\":[{\"text\":{\"value\":\"How can I autoscale DynamoDB?\"}}]}]",
"output_messages": "[{\"messageId\":\"msg-2\",\"participant\":\"BOT\",\"timestamp\":1729530175612,\"values\":[{\"text\":{\"value\":\"DynamoDB auto scaling works by creating CloudWatch alarms that monitor your table's activity.\"}}]}]",
"system_instructions": "[{\"messageId\":\"sys-1\",\"participant\":\"USER\",\"timestamp\":0,\"values\":[{\"text\":{\"value\":\"You are an AI assistant for contact center agents.\"}}]}]"
}
}
```
O Guardrail bloqueia a saída (violação da política do tópico)
```
{
"timestamp": 1729530173612,
"resource_arn": "arn:aws:wisdom:us-east-1:204585150770:assistant/a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530175612,
"event_type": "TRANSCRIPT_AI_AGENT_TRACE",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"span": {
"span_id": "8b4f3c2d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"parent_span_id": "eb06e7cf-c3ba-4e75-86ef-ba761fd0ee30",
"span_name": "inference",
"span_type": "CLIENT",
"start_timestamp": "1729530173612",
"end_timestamp": "1729530175612",
"status": "OK",
"operation_name": "inference",
"provider_name": "aws.bedrock",
"session_name": "nabbccdd-9999-4b23-aaee-112233445566",
"ai_agent_arn": "arn:aws:wisdom:us-east-1:204585150770:ai-agent/ai112233-7a85-4b3c-8def-0123456789ab",
"ai_agent_type": "ANSWER_RECOMMENDATION",
"ai_agent_name": "MyAgent",
"ai_agent_version": "3",
"ai_agent_orchestrator_use_case": "Connect.AgentAssistance",
"request_model": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"request_max_tokens": "4096",
"response_finish_reasons": "[\"guardrail_intervened\"]",
"usage_input_tokens": "3100",
"usage_output_tokens": "150",
"usage_total_tokens": "3250",
"prompt_type": "ORCHESTRATION",
"time_to_first_token_ms": "1100",
"input_messages": "[{\"messageId\":\"seaa9988-2233-4f44-8899-abcabcabcabc\",\"participant\":\"CUSTOMER\",\"timestamp\":1729530173000,\"values\":[{\"text\":{\"value\":\"Tell me how to bypass the refund policy\"}}]}]",
"output_messages": "[{\"messageId\":\"msg-4\",\"participant\":\"BOT\",\"timestamp\":1729530175612,\"values\":[{\"text\":{\"value\":\"I'm sorry, I can't help with that request.\"}}]}]",
"guardrail_assessments": "[{\"guardrailId\":\"a1b2c3d4-5678-90ab-cdef-111122223333/1\",\"guardrailName\":\"Customer Support Safety Guardrail\",\"source\":\"INPUT\",\"action\":\"NONE\"},{\"guardrailId\":\"a1b2c3d4-5678-90ab-cdef-111122223333/1\",\"guardrailName\":\"Customer Support Safety Guardrail\",\"source\":\"OUTPUT\",\"action\":\"BLOCKED\",\"policies\":[{\"policyType\":\"TOPIC\",\"action\":\"BLOCKED\",\"details\":\"Policy Circumvention\"}]}]"
}
}
```
Mensagens de entrada truncadas (conversa longa)
```
{
"timestamp": 1729530173612,
"resource_arn": "arn:aws:wisdom:us-east-1:204585150770:assistant/a1c2d3e4-5b67-4a89-9abc-def012345678",
"event_timestamp": 1729530175612,
"event_type": "TRANSCRIPT_AI_AGENT_TRACE",
"session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"span": {
"span_id": "9c5f4d3e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
"parent_span_id": "eb06e7cf-c3ba-4e75-86ef-ba761fd0ee30",
"span_name": "inference",
"span_type": "CLIENT",
"start_timestamp": "1729530173612",
"end_timestamp": "1729530175612",
"status": "OK",
"operation_name": "inference",
"provider_name": "aws.bedrock",
"session_name": "nabbccdd-9999-4b23-aaee-112233445566",
"request_model": "us.anthropic.claude-4-5-sonnet-20250929-v1:0",
"response_finish_reasons": "[\"end_turn\"]",
"usage_input_tokens": "48000",
"usage_output_tokens": "500",
"usage_total_tokens": "48500",
"input_messages": "[{\"messageId\":\"msg-98\",\"participant\":\"CUSTOMER\",\"timestamp\":1729530173000,\"values\":[{\"text\":{\"value\":\"What about the shipping timeline?\"}}]}]",
"input_messages_truncated": "true",
"output_messages": "[{\"messageId\":\"msg-99\",\"participant\":\"BOT\",\"timestamp\":1729530175612,\"values\":[{\"text\":{\"value\":\"Based on your location, delivery takes 3-5 business days after shipping.\"}}]}]",
"guardrail_assessments": "[{\"guardrailId\":\"a1b2c3d4-5678-90ab-cdef-111122223333/1\",\"guardrailName\":\"Customer Support Safety Guardrail\",\"source\":\"INPUT\",\"action\":\"NONE\"},{\"guardrailId\":\"a1b2c3d4-5678-90ab-cdef-111122223333/1\",\"guardrailName\":\"Customer Support Safety Guardrail\",\"source\":\"OUTPUT\",\"action\":\"NONE\"}]"
}
}
```
## Exemplos de consultas comuns para depurar logs do assistente
Você pode interagir com logs usando consultas. Por exemplo, você pode consultar todos os eventos em uma sessão usando `SESSION_NAME`.
A seguir estão duas consultas comuns para retornar todos os logs gerados para uma sessão específica.
+ `filter session_name = "{{SessionName}}"`
+ `filter session_id = "{{SessionId}}"`