Skip to main content
The Heartbeat Virtual Agent fails in three common ways: the Amazon ECS task is not running, the agent is not logged in to Amazon Connect, or the agent credentials cannot be authenticated manually. Start at the section that matches your symptom.

​
Before you start

  • Admin access to the AWS account hosting the Cloud Orchestrator and the Virtual Agent stack.
  • The Virtual Agent CloudFormation stack name and the Amazon Connect instance it is bound to.
  • The AgentUsername and AgentPassword you set when you deployed the Virtual Agent stack.

​
The Virtual Agent task is not running

​
1. Open the Virtual Agent CloudFormation stack

In the AWS console, open CloudFormation and select the Virtual Agent stack. Open the Resources tab and click the physical ID of the ECS service.

​
2. Check deployments and tasks

The ECS service detail page shows Deployments and tasks. A healthy service shows 1/1 — one task running out of one desired. If the count is 0/1, the task is stopped or failing to start. Continue to step 3.

​
3. Inspect the failing task

Open the Tasks tab on the service. Click into the most recent task. The Stopped reason and Containers sections explain why the task exited. The most common causes:
  • Image pull failure — the task can’t reach the Operata container registry. Confirm the VPC the stack deploys into has outbound internet access (NAT gateway or VPC endpoints).
  • Insufficient task CPU or memory — bump the task definition’s resource allocation and update the service.
  • Container exit on startup — the agent crashed before logging in. Continue to “The Virtual Agent is not logged in” below to read the logs.
You can stop and start the Virtual Agent from this view by updating the service’s desired task count.

​
The Virtual Agent is not logged in

The fastest check is the Amazon Connect console — the real-time agent metrics show the Virtual Agent as logged in once login succeeds. If the metrics show the agent offline, read the ECS logs.

​
1. Open the Virtual Agent ECS service

In the AWS console, open CloudFormation and select the Virtual Agent stack. Under Resources, expand the VirtualAgent resource and click through to the ECS cluster the stack created.

​
2. Open the logs

Click the service — named <stack-name>VirtualAgent — and select the Logs tab. The log lines describe the login flow: A long-running service may also show repeated logged in successfully entries from session refreshes — that is normal.

​
3. Match the failure to a cause

​
The Virtual Agent ID cannot be authenticated manually

The third step is to confirm the Virtual Agent’s credentials work outside ECS — this isolates Amazon Connect or IDP issues from ECS networking issues.

​
1. Non-SSO instances

Open the Amazon Connect CCP URL in a browser. Sign in with the AgentUsername and AgentPassword you set in the Virtual Agent CloudFormation stack. The agent should reach the Ready state. If sign-in fails, reset the password in Amazon Connect and redeploy the Virtual Agent stack with the new AgentPassword.

​
2. SSO instances

Open the LoginUrl you set in the Virtual Agent stack in a browser. Sign in with the AgentUsername and the IDP password for that user. The agent should redirect to Amazon Connect and reach Ready. If sign-in fails:
  • The IDP login is broken — fix it in the IDP first.
  • MFA is enforced on the Virtual Agent user — exclude the user from MFA enforcement (for example, in Azure Security Defaults).

​
Verify

Run a Heartbeat test from the Operata console. The test call dials the Heartbeat phone number, the Virtual Agent answers within seconds, and the run completes within the Heartbeat call duration (typically under 30 seconds). The run appears on the Operata console and on your EventBridge bus. If the Virtual Agent still does not answer after working through this page, contact Operata Support with the ECS service ARN, the most recent task ID, and the relevant log extract.