Testar e avaliar

Teste o agente em relação às respostas esperadas e casos de falha antes de alterar o público para EVERYONE.

Comece com configurações restritas

Mantenha a implantação, a transferência e o acompanhamento desativados enquanto estabelece a linha de base de teste. Restrinja o público antes de adicionar destinatários de teste. Referência da API: GET Get Settings · PUT Replace Settings

curl --request PUT \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/settings" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "rollout": {"enabled": false},
    "handoff": {"enabled": false},
    "followup": {"enabled": false},
    "ai_audience": "ALLOWLISTED_ONLY"
  }'

GET Get Settings retorna um array, mesmo quando existe apenas um objeto de configurações. PUT Replace Settings retorna o objeto de configurações atualizado. A YCloud omite campos nulos antes de chamar a Meta, portanto, as configurações não fornecidas permanecem inalteradas.

Campo	Linha de base de teste
`rollout.enabled`	Mantenha `false` até que o agente esteja pronto para testes ao vivo no WhatsApp.
`handoff.enabled`	Mantenha `false` durante o teste de resposta da linha de base. Ative-o separadamente ao testar cenários de transferência.
`followup.enabled`	Mantenha `false` durante o teste de resposta da linha de base. Ative-o separadamente ao testar cenários de acompanhamento.
`ai_audience`	Use `ALLOWLISTED_ONLY` até que o teste de aceitação restrito seja aprovado.

Leia as configurações efetivas novamente após a atualização. Altere um comportamento por vez ao testar a transferência ou o acompanhamento e, em seguida, restaure a linha de base restrita antes de passar para outro cenário.

Adicionar destinatários de teste

Mantenha ai_audience definido como ALLOWLISTED_ONLY e, em seguida, adicione cada testador como um número de telefone E.164. Armazene a entrada da lista de permissões retornada id para que você possa remover a entrada posteriormente. Referência da API: GET List Allowlist · POST Create Allowlist Entry · DELETE Delete Allowlist Entry

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/allowListEntries" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"consumer_phone_number":"+14155550123"}'

Use GET List Allowlist para revisar o público de teste atual. Use DELETE Delete Allowlist Entry para remover um testador pelo ID de entrada retornado.

Não use um número de usuário final com o código de chamada do país +86. O Meta Business Agent atualmente não responde a mensagens de usuários finais +86, mesmo quando o número está formatado como E.164 válido e adicionado à lista de permissões.

Executar um teste de turno único

Referência da API: POST Test Agent

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/tests" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"user_msg":"What is your return policy?"}'

Uma resposta bem-sucedida pode conter:

{
  "message_id": "MESSAGE_ID",
  "agent_response": "Unused items can be returned within 30 days.",
  "conversation_id": "CONVERSATION_ID",
  "timestamp": 1787630155,
  "quick_replies": [],
  "product_variant_ids": []
}

Campo de resposta	Significado
`message_id`	Identificador de mensagem para a resposta gerada.
`agent_response`	Texto da resposta gerada. Pode estar vazio quando `no_response_reason` estiver presente.
`conversation_id`	Identificador de contexto para turnos de teste subsequentes.
`timestamp`	Carimbo de data/hora Unix em segundos.
`handoff_reason`	Por que o agente decidiu que um humano deveria assumir, quando presente.
`no_response_reason`	Por que o agente não produziu resposta, quando presente.
`quick_replies`	Rótulos de resposta rápida sugeridos, quando presentes.
`product_variant_ids`	Variantes de produto referenciadas pela resposta, quando presentes.

A resposta REST atual não inclui estimated_token_usage.

Preservar o contexto para testes de múltiplos turnos

Envie o conversation_id retornado com a próxima mensagem do cliente. Referência da API: POST Test Agent

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/tests" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_msg": "What information do you need from me?",
    "conversation_id": "CONVERSATION_ID"
  }'

Use uma nova conversa para cenários que não devem herdar o contexto anterior.

Testar conhecimento, habilidades, conectores e ferramentas

Cubra os recursos configurados em vez de testar apenas perguntas do caminho feliz. Referência da API: POST Run Connector Tool · GET List Connector Logs

Faça perguntas respondidas por informações comerciais, FAQs, sites e arquivos.
Verifique fatos ausentes, fontes contraditórias, conteúdo desatualizado e solicitações não suportadas.
Verifique quando cada habilidade deve e não deve ser executada.
Exercite cada ferramenta de conector com entradas válidas, inválidas e incompletas.
Confirme se valores secretos nunca aparecem em respostas ou logs.
Inclua casos que devem acionar a transferência humana ou não produzir resposta.

Se uma chamada de conector falhar, inspecione os logs do conector e verifique as credenciais, o estado do certificado, as vinculações de parâmetros e as definições de solicitação de ferramenta antes de alterar a habilidade. Execute cada ferramenta configurada diretamente através de /connectors/{connectorId}/tools/{toolId}/runs com input representativo antes de permitir que o agente a selecione em uma conversa:

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/connectors/CONNECTOR_ID/tools/TOOL_ID/runs" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"input":"Look up order ORD-1001"}'

Testar através do WhatsApp com destinatários na lista de permissões

Valide os mesmos cenários de cada número de telefone de teste na lista de permissões. Isso confirma o comportamento do canal ao vivo que o endpoint de teste não pode reproduzir completamente.

Durante o acesso antecipado, o endpoint de teste pode retornar uma resposta vazia ou ELIGIBILITY_CHECK_FAILED enquanto o público for ALLOWLISTED_ONLY. Verifique no_response_reason, elegibilidade, implantação, público e configurações da lista de permissões. Se o teste da API exigir EVERYONE, use-o apenas em um ambiente controlado e restaure a configuração restrita imediatamente após o teste.

Executar avaliações

A API de avaliação fornece estes recursos:

Método	Caminho	Propósito
`GET`	List Eval Cases	Listar casos de avaliação disponíveis.
`POST`	Submit Eval Run	Iniciar uma execução de avaliação.
`GET`	Get Eval Run Status	Consultar o progresso e o resultado da execução.
`GET`	Obter detalhes da avaliação	Recuperar resultados detalhados da avaliação.
`GET`	Obter resumo da avaliação	Recuperar resumos da avaliação.

Liste os casos disponíveis, envie uma execução usando o valor eval_case_ids obrigatório, retenha o job_id retornado e consulte o endpoint do trabalho.

curl "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/evalCases" \
  --header "X-API-Key: $YCLOUD_API_KEY"

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/evalRuns" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"eval_case_ids":"EVAL_CASE_IDS"}'

curl "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/evalRuns/JOB_ID" \
  --header "X-API-Key: $YCLOUD_API_KEY"

O campo de status é retornado como uma string e atualmente não está restrito a um enum documentado. Pare a consulta quando a resposta fornecer um resultado concluído ou erro, em vez de assumir nomes de status não documentados. Os casos de avaliação descrevem um scenario, categories, max_turns e success_criteria. Os resultados detalhados incluem pontuações, rótulos de turno, motivos, transcrições e carimbos de data/hora. Os resumos agregam pontuações, destaques e categorias de falha.

Lista de verificação para lançamento

Os fatos de negócios obrigatórios estão corretos e não são contraditórios.
As conversas de vários turnos preservam o contexto pretendido.
Informações ausentes produzem uma resposta segura em vez de uma resposta inventada.
As ferramentas de conector têm sucesso e falham com segurança com entradas representativas.
Os cenários de transferência se comportam conforme o esperado.
As falhas de avaliação são revisadas e corrigidas ou aceitas explicitamente.
Um proprietário de reversão sabe como desativar a implementação.

A seguir: Implementar com segurança

Ative o agente primeiro para destinatários na lista de permissões e, em seguida, expanda para todo o público.

Primeiros passos

Guias

Endpoints

Webhooks

Comece com configurações restritas

Adicionar destinatários de teste

Executar um teste de turno único

Preservar o contexto para testes de múltiplos turnos

Testar conhecimento, habilidades, conectores e ferramentas

Testar através do WhatsApp com destinatários na lista de permissões

Executar avaliações

Lista de verificação para lançamento

A seguir: Implementar com segurança

​Comece com configurações restritas

​Adicionar destinatários de teste

​Executar um teste de turno único

​Preservar o contexto para testes de múltiplos turnos

​Testar conhecimento, habilidades, conectores e ferramentas

​Testar através do WhatsApp com destinatários na lista de permissões

​Executar avaliações

​Lista de verificação para lançamento

A seguir: Implementar com segurança

Comece com configurações restritas

Adicionar destinatários de teste

Executar um teste de turno único

Preservar o contexto para testes de múltiplos turnos

Testar conhecimento, habilidades, conectores e ferramentas

Testar através do WhatsApp com destinatários na lista de permissões

Executar avaliações

Lista de verificação para lançamento