> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Testar e avaliar

> Valide cenários de turno único, múltiplos turnos, transferência, ferramentas e negócios antes de ativar a implantação completa.

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](/api-reference/meta-business-agents/get-settings) · [PUT Replace Settings](/api-reference/meta-business-agents/replace-settings)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/api-reference/meta-business-agents/get-settings) retorna um array, mesmo quando existe apenas um objeto de configurações. [PUT Replace Settings](/api-reference/meta-business-agents/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](/api-reference/meta-business-agents/list-allowlist) · [POST Create Allowlist Entry](/api-reference/meta-business-agents/create-allowlist-entry) · [DELETE Delete Allowlist Entry](/api-reference/meta-business-agents/delete-allowlist-entry)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/api-reference/meta-business-agents/list-allowlist) para revisar o público de teste atual. Use [DELETE Delete Allowlist Entry](/api-reference/meta-business-agents/delete-allowlist-entry) para remover um testador pelo ID de entrada retornado.

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

## Executar um teste de turno único

**Referência da API:** [POST Test Agent](/api-reference/meta-business-agents/test-agent)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](/api-reference/meta-business-agents/test-agent)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/api-reference/meta-business-agents/run-connector-tool) · [GET List Connector Logs](/api-reference/meta-business-agents/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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

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

## Executar avaliações

A API de avaliação fornece estes recursos:

| Método | Caminho | Propósito |
| - | - | - |
| `GET` | [List Eval Cases](/api-reference/meta-business-agents/list-eval-cases) | Listar casos de avaliação disponíveis. |
| `POST` | [Submit Eval Run](/api-reference/meta-business-agents/submit-eval-run) | Iniciar uma execução de avaliação. |
| `GET` | [Get Eval Run Status](/api-reference/meta-business-agents/get-eval-run-status) | Consultar o progresso e o resultado da execução. |
| `GET` | [Obter detalhes da avaliação](/api-reference/meta-business-agents/get-eval-details) | Recuperar resultados detalhados da avaliação. |
| `GET` | [Obter resumo da avaliação](/api-reference/meta-business-agents/get-eval-summary) | 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/evalCases" \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"}'
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<Card title="A seguir: Implementar com segurança" icon="arrow-right" href="/pt/documentation/meta-business-agent/roll-out-safely">
  Ative o agente primeiro para destinatários na lista de permissões e, em seguida, expanda para todo o público.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.