How to Add an AI Voice Agent to Amazon Connect: Step-by-Step Setup Guide

Amazon Connect handles the phone side: numbers, routing, queues and recording. An AI voice agent answers the call, works out what the caller wants, uses tools to do something about it, and either finishes the job or hands the caller to a person. This guide shows how to wire that together using the console, in the order that avoids rework.

AWS has changed this area quickly. The product is now documented as Amazon Connect Customer, the self-service approach that returns control to the flow at every custom tool is labelled legacy, and the current approach is called agentic self-service, in which one orchestrator AI agent reasons across several steps and calls tools without handing control back between them. Everything below follows the current documentation, which we checked on 10 November 2026. Console labels move, so treat the screen names as a map rather than a script.

Paths A and B are both configured on the bot and in the flow, so most of the steps are shared, and where they differ we say so in Step 8. AWS documents Nova Sonic as a speech model setting on the bot locale, so check the current documentation for how it behaves alongside an orchestrator AI agent in your region before you rely on combining them. If you are unsure, start with path A.

• An AWS account and a user who can create a Connect instance. AWS documents the AmazonConnect_FullAccess policy as the permission set for creating one.
• A region where Amazon Connect Customer is available to you. AWS notes that it is not available to customers in India who use AWS through Amazon Web Services India Private Limited, and instance creation returns an error in that case.
• One call type with a written definition of success, such as after-hours intake or appointment changes. Starting with the whole phone line is a common reason pilots stall.
• The systems the agent will act on, and a person who can describe the rules for them. Each action becomes a tool.
• A decision about recording and consent for your jurisdiction, made with your own counsel. The flow plays the disclosure and the instance stores the recording, but neither decides what you are required to say.

Open the AWS console, search for Connect Customer and choose Get started (or Add an instance if you already have one). Every new instance is a Connect Customer instance. If you have an older instance, open it, choose Connect Customer in the navigation pane and enable it. The AI agent features used here are not part of Connect Customer Basic.

• Identity management: choose between storing users in Connect, linking a directory, or SAML 2.0. You cannot change this after creating the instance, so involve whoever owns identity at your company.
• Access URL: this label must be unique across all Connect instances in all regions and cannot be changed later.
• Telephony: choose Receive inbound calls. Enable outbound calling only if you need it.
• Data storage: by default Connect creates a bucket for recordings, transcripts and exports, encrypted with AWS KMS. Recording is switched on per flow later.

The full AWS walkthrough is Create a Connect Customer instance.

In the Connect admin website choose Channels, then Phone numbers, then Claim a number. Pick a DID (local) or toll-free number, add a description, and save. You can attach a flow now or after you publish one in Step 10. In the US you can ask for a specific area code.

If no numbers appear for your country, or you see a message that the number could not be claimed, AWS says the fix is a support case rather than a retry. Numbers claimed for a contact center also carry a daily charge whether or not a call arrives, so claim one for testing rather than several. Our cost breakdown for an AI voice agent shows where the pennies per minute go.

Reference: Get a local toll-free or DID phone number.

There are two separate permission questions, and mixing them up causes confusing failures later.

AWS reuses the security profile model for AI agents, so the same least-privilege thinking you apply to human agents applies here. An AI agent can only invoke tools its profile allows. Start narrow and widen deliberately. See Assign security profile permissions to AI agents.

1. In the admin website open AI agent designer, then AI agents, then Create AI agent.
2. Choose Orchestration as the AI agent type.
3. Under Copy from existing, choose SelfServiceOrchestrator. This is the system self-service agent, and starting from it gives you working defaults instead of a blank page.
4. In the Security Profiles section, select the profile you created in Step 3.

Do not publish yet. The agent needs tools and a prompt first. If you are unsure whether a Connect AI agent is the right choice compared with fixed Lex intents or a Bedrock agent, read Amazon Lex vs AI Agent in Amazon Connect first.

Tools are how the agent acts. The orchestrator supports three kinds, and knowing the difference saves a lot of confusion.

Build in this order. First add Constant tools that return realistic sample data, such as a booking record, and get the conversation right. Then replace each one with a real MCP tool. Prompt problems and integration problems look identical when they happen together, and separating them early is the cheapest debugging you will do.

Two limits are worth knowing now. MCP tool calls time out after 30 seconds, so slow back ends need a different design. And you will probably want to replace the default Escalate tool with one that carries context, so the person who picks up the call does not start from zero. An illustrative input schema:

{
  "type": "object",
  "required": ["reason", "summary", "callerIntent"],
  "properties": {
    "reason": {
      "type": "string",
      "enum": ["caller_requested_person", "tool_failure", "out_of_scope", "policy_exception", "caller_distressed"]
    },
    "summary": {
      "type": "string",
      "maxLength": 500,
      "description": "What the caller wanted, what was tried, and why a person is needed"
    },
    "callerIntent": { "type": "string" }
  }
}

Reference: Use agentic self-service and AI agent MCP tools.

The SelfServiceOrchestrator comes with a default orchestration prompt you can use as is or replace. For a voice line, two requirements matter more than tone.

• Replies must be wrapped in message tags. Orchestrator AI agents only show or speak text inside those tags, so a prompt that omits the instruction produces a caller who hears silence and a log full of replies nobody received.
• Everything inside the tags is read aloud, so write for the ear: full sentences, no markdown, lists, emoji or brackets, and codes read out through the spell tag. AWS documents the tags for speed, pauses, spelling and emotion, and recommends plain punctuation first.

You are the phone assistant for {{company}}. Callers hear everything you write, spoken aloud.

Format every reply like this:
<message>
What the caller should hear, in plain spoken sentences.
</message>

Rules:
- Begin every turn with a <message> block, even before calling a tool.
- Never use lists, markdown, emoji or brackets inside a message.
- Read codes and reference numbers with <spell>CODE</spell>.
- Read back names, phone numbers and dates and wait for confirmation.
- Use only the tools you have been given. If a tool fails twice, or the caller asks for a person, call Escalate.
- When the job is finished and the caller needs nothing else, call Complete.

Keep it short at first. Long prompts add latency to every turn and hide which instruction is doing the work. Add a rule only when a test call shows you need it. Reference: How to use orchestrator AI agents.

When the agent has tools, a prompt and a security profile, choose Publish. Then go to the AI Agents page, find Default AI Agent Configurations and select your agent in the Self Service row.

The flow does not talk to the AI agent directly. It talks to a conversational AI bot, which hands the conversation to the agent.

1. Go to Routing, then Flows, then Conversational AI, and create a bot. Create it inside the Connect admin website, because the toggle in the next step is only supported for bots created there.
2. Open the bot's Configuration tab and switch on the agent assist intent, which is the Amazon Lex built-in intent named AMAZON.QinConnectIntent. Choose Confirm in the dialog.
3. Choose Build language for the locale. Changes are not active until the build succeeds, and an Unbuilt changes label tells you something is pending.
4. Create a bot alias and make sure Use in flow and flow modules is enabled on it, otherwise the bot will not appear in the flow designer.

Reference: Create an agent assist intent.

Callers judge the agent by how it sounds and how well it hears, so make these choices on purpose. There are two places to configure, and they must agree.

For path B, AWS lists the launch voices as Matthew (en-US), Amy (en-GB), Olivia (en-AU) and Lupe (es-US). Choose a voice that matches the bot locale and check the current list before you commit, because it will change.

Two rules save an afternoon. The language in the Set voice block must match the locale of the bot, otherwise the Get customer input block returns an error. And if your callers switch languages, AWS offers multilingual voices (Katie, Blake, Brooke, Ronald and Gemma at the time of writing) that work from a single bot locale, with the agent following the caller's language when your prompt tells it to. Note that the first greeting is spoken in the language you wrote it in, because the agent has not heard the caller yet.

For every voice option side by side, including Polly, ElevenLabs and brand voices, see Amazon Connect Custom Voice: Every Voice Option. References: Agentic voice configuration guide and Configure Amazon Nova Sonic speech-to-speech.

Go to Routing, then Flows, choose Create flow and name it. A voice-agent flow is short on purpose. The intelligence lives in the agent; the flow decides what happens at the start, at the end and when something fails.

1. Set voice: your language and voice from Step 8.
2. Call recording, if you record calls: use the recording block in the flow designer. The instance creates the bucket, but AWS says recording itself is switched on in a flow.
3. Get customer input: on the Amazon Lex tab choose your bot and alias. Under Customer prompt or bot initialization choose Text-to-speech or chat text and write the opening line, including any AI and recording disclosure your counsel requires.
4. Check contact attributes after the Default output: set the namespace to Lex, the key to Session attributes, and the session attribute key to Tool. Add one condition per Return to Control tool you use, for example Complete and Escalate.
5. Complete goes to Disconnect. Escalate goes through Set working queue and Transfer to queue. Optionally copy the escalation context from the Lex session attributes into contact attributes first, so the human agent sees it.
6. No match, Timeout and Error outputs on every block go somewhere deliberate: a spoken apology and the human queue, never a dead end.

That last point is where first versions often fail in front of real callers. The Get customer input block has Timeout, Default and Error branches, and any branch you leave unconnected is a call that ends in silence. Reference: Create a flow and add your conversational AI bot and Get customer input.

1. Save and Publish the flow. Only published flows are available to attach to a number.
2. Go to Channels, Phone numbers, open your number, set Flow / IVR to the flow and save.
3. Call the number from a real phone, not a softphone on a fast office connection.

Test deliberately instead of chatting at it. A useful first set:

Once the conversation is right, swap each Constant tool for its MCP tool and run the same list again. Reference: Attach a claimed phone number to a flow.

Most complaints about voice agents are about timing: talking over people, or waiting too long. The agentic voice settings are Lex session attributes that you set in the Get customer input block or from a Lambda function.

AWS's advice is to scope these to the specific intent and slot that needs them rather than applying one aggressive default everywhere, because a global change alters the pacing of every turn. And if the caller waits through a long tool call, play a short holding phrase instead of letting the line go quiet. Reference: Agentic voice best practices.

A demo answers a call. A production line survives the thousandth one. What changes between them is mostly not configuration:

• Tool design: narrow, validated, idempotent tools, with business rules enforced in the tool and not only in the prompt.
• A regression set of real call scenarios that you re-run on every prompt, model or voice change.
• Call review: a scheduled sample scored by a person, alongside the AI agent metrics Connect Customer provides.
• A staged rollout, such as after-hours or overflow traffic first, with a tested way to switch back.
• A named owner for prompts, knowledge and escalation rules.

Our architecture and build guide covers these layers in depth, our guide to AI voice agent integration with Amazon Connect covers how each one attaches to the contact flow, and the cost breakdown shows what a month of calls costs on AWS list prices. If you would rather have the system built and operated for you, see our AI voice agent development service or read how we built an intake agent for a law firm.