Agentes de vídeo com IA: Vonage, Pipecat e AgentCore

Introdução

Os desenvolvedores agora podem adicionar participantes de IA conversacional diretamente em sessões de vídeo ao vivo. Em vez de videochamadas passivas, é possível criar agentes de IA que ouvem, respondem e interagem naturalmente durante conversas ao vivo.

Neste tutorial, você implantará um agente de IA para sessões de Video usando o Vonage Video Transport para Pipecat e o AWS Nova Sonic. O repositório oferece duas opções: desenvolvimento local usando o Docker para iterações rápidas e implantação em produção com o agente rodando inteiramente no AWS Bedrock AgentCore Runtime. Este tutorial orienta você em ambas as etapas — comece localmente para validar seu pipeline e, em seguida, implante em produção com o `agentcore deploy` e o AWS App Runner.

O Vonage Video Transport para Pipecat permite que você desenvolva aplicativos baseados em IA que participam de forma integrada das sessões da Video API da Vonage. Esse protocolo de transporte permite que você receba áudio e vídeo dos participantes da sessão e envie de volta à sessão, em tempo real, o áudio e o vídeo processados.

O Pipecat é uma estrutura de código aberto para a criação de aplicativos de IA conversacional de voz e multimodal. O Vonage Video Connector faz a ponte entre o pipeline de processamento de mídia do Pipecat e as sessões da Video API do Vonage, possibilitando uma ampla gama de casos de uso. O AWS Nova Sonic é otimizado para interações de voz conversacionais de baixa latência, tornando-o ideal para sessões de vídeo ao vivo. AWS Bedrock AgentCore Runtime é uma infraestrutura segura e sem servidor, projetada para implantar e escalar agentes de Voice e IA em tempo real e com baixa latência em grande escala, sem a complexidade de gerenciar servidores subjacentes.

Você vai usar:

• Transportador WebRTC do Vonage Video Connector para o Pipecat para orquestração de pipelines de IA

• AWS Nova Sonic para IA de voz

• AWS Bedrock AgentCore permite que os desenvolvedores implantem e dimensionem agentes de IA.

Pule esta parte e encontre o código funcional para este exemplo no GitHub.

O que você vai desenvolver

Ao final deste tutorial, você terá:

• Um agente de IA implantado no AWS Bedrock AgentCore Runtime — um contêiner sem servidor totalmente gerenciado que executa seu pipeline do Pipecat

• Um endpoint público do App Runner que processa o webhook de acionamento do agente e transmite o contexto da sessão ao AgentCore

• Respostas faladas em tempo real da IA usando o AWS Nova Sonic (de voz para voz, sem cadeia de STT/TTS)

• Uma arquitetura de produção que não requer EC2, ECS nem ALB — basta a implantação do agentcore e um serviço App Runner

• Um fluxo de teste validado utilizando o Vonage Playground antes da integração com o aplicativo de referência Vonage Video React

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

• A Account da API da Vonage com a Video API ativada

• Uma account da AWS com acesso ao Amazon Bedrock para o Nova Sonic (amazon.nova-2-sonic-v1:0)

• Python 3.13 necessário para o vonage-video-connector >= 1.0.0

• uv gerenciador de pacotes (brew install uv no macOS)

• Docker Desktop - necessário porque o SDK do Vonage Video Connector, no momento, roda apenas no Linux

• ngrok para desenvolvimento local

• AWS CLI configurada (aws configure --profile profile-name)

Como o Bedrock e o AgentCore funcionam em conjunto

Este projeto utiliza dois serviços complementares da AWS:

Como eles funcionam juntos neste repositório:

1. Bedrock + Agent Core (produto final) — juntos, formam um agente pronto para produção com ferramentas de gerenciamento

2. Leito rochoso por si só - uma opção mais leve para experimentos rápidos e agentes conversacionais simples

3. Ampliado - adicionar recursos do mundo real, como RAG, chamadas de API e consultas ao CRM, juntamente com voz de baixa latência

Versão resumida: o Bedrock fornece as respostas; o AgentCore executa a lógica do aplicativo do agente implantável.

Visão geral da arquitetura

A integração segue um fluxo baseado em WebRTC: o agente de IA entra na sessão do Vonage Video como participante, utilizando o SDK do Vonage Video Connector. Em seguida, o Pipecat orquestra o pipeline de IA, encaminhando o áudio pelo AWS Nova Sonic para o processamento de voz para voz. Se configurado, o AgentCore prepara o agente no início da sessão com contexto personalizado ou acesso a ferramentas.Architecture overview: Vonage Video session → Pipecat pipeline → AWS Nova Sonic → AgentCore.

Desenvolvimento local

1. Navegador (Vonage Playground) se conecta à sessão de vídeo WebRTC da Vonage.

2. POST /join {vonage_session_id, vonage_token} é enviada para FastAPI (app/main.py, porta 8000).

3. FastAPI inicia VonageVideoConnectorTransport (WebRTC), ingressando na sessão como um participante nativo.

4. O Pipecat Pipeline processa a mídia.

5. AWS Nova Sonic é responsável pelo processamento de IA.

6. O áudio é transmitido de volta aos participantes da sessão de Video.

Produção

1. Navegador (Aplicativo de referência do Vonage Video React) envia POST /answer {vonage_session_id, vonage_token}.

2. App Runner (answer/server.py — ponto de extremidade HTTPS público) chama AgentCoreRuntimeClient.generate_presigned_url().

3. Isso é aprovado vonage_session_id + vonage_token para AgentCore .

4. AgentCore Runtime (runtime/agent.py, porta 8080, ARM64, Python 3.13) inicializa o BedrockAgentCoreApp.

5. @app.websocket /ws aguarda websocket.accept().

6. VonageVideoConnectorTransport participa da sessão do Vonage Video como participante nativo.

7. O Pipecat Pipeline encaminha o áudio para o AWS Nova Sonic.

8. O áudio é transmitido de volta aos participantes da sessão de Video.

Componentes principais

Antes de começar: crie uma aplicação e uma sessão do Vonage Video

Antes de configurar seu ambiente, você precisa do aplicativo Vonage Video e de um ID de sessão.

Criar um aplicativo de vídeo da Vonage

1. Faça login no Painel da Vonage

2. Acesse Applications → Criar um novo aplicativo

3. Ativar Video de vídeo

4. Clique Gerar chave pública e privada — isso faz o download private.key

5. Salve o aplicativo — copie o ID do aplicativo

Criar uma sessão de vídeo do Vonage

1. No Painel da Vonage, acesse Video → Ferramentas → Playground

2. Selecione seu aplicativo

3. Clique em “Criar sessão” — copie o ID da sessão

Use o modo de mídia roteada ao utilizar o Video Connector. Use um função de token de editor para o participante da sessão de IA.

Agora você tem:

• VONAGE_APPLICATION_ID — seu ID de aplicativo da Vonage

• VONAGE_SESSION_ID — seu ID de sessão de Video da Vonage

• private.key — baixado para o seu computador

Passo 1: Clonar o repositório

git clone https://github.com/Vonage-Community/vonage-pipecat-aws-agentcore.git
cd vonage-pipecat-aws-agentcore

A estrutura do repositório:

vonage-pipecat-aws-agentcore/
├── app/ # DESENVOLVIMENTO LOCAL — Aplicativo FastAPI (main.py, agent.py), porta 8000
├── runtime/ # PRODUÇÃO — BedrockAgentCoreApp (agent.py), implantação do agentcore, Python 3.13 ARM64
├── answer/ # PRODUÇÃO — manipulador /answer (App Runner)
├── tests/ # Etapas de validação C1–C6
├── docker-compose.yml
├── .env.example
└── README.md

Etapa 2: Configure seu ambiente

Sempre utilize funções do IAM ou credenciais temporárias em ambiente de produção. Nunca insira segredos da AWS diretamente no código nem os envie para o controle de versão.

cp .env.example .env

Abrir .env e preencha suas credenciais:

# Vonage Video API
VONAGE_APPLICATION_ID=your-vonage-application-id
VONAGE_PRIVATE_KEY=private.key
VONAGE_SESSION_ID=your-vonage-session-id

# AWS
AWS_PROFILE=your-aws-profile
AWS_DEFAULT_REGION=us-east-1
BEDROCK_MODEL_ID=amazon.nova-2-sonic-v1:0

O repositório completo .env.example no repositório contém configurações adicionais para tempos limite, limites de sessão e configurações de produção. As três variáveis acima são tudo o que você precisa para executar a demonstração local.

Configure seu perfil da AWS

aws configure --profile vonage-dev
export AWS_PROFILE=vonage-dev
aws sts get-caller-identity --profile vonage-dev

Criar uma sessão de vídeo do Vonage

Para criar uma sessão do Vonage Video, faça login no Painel do Vonage, acesse Video → Ferramentas → Playgrounde crie uma sessão roteada. Copie o ID da sessão para o seu .env arquivo.

Use routed o modo de mídia ao utilizar o Video Connector. Use uma publisher função de token para o participante da sessão de IA.

Etapa 3: Executar localmente com o Docker

O SDK do Vonage Video Connector requer o Linux. No macOS ou no Windows, o Docker cuida disso automaticamente.

Execute o aplicativo completo a partir da raiz do repositório:

docker compose --profile app up --build

Verifique se ele está em execução:

curl http://localhost:8000/
# {"status": "ok"}

curl http://localhost:8000/status
# {"running": true, "connected": false, "last_error": null}

O aplicativo se conecta automaticamente VONAGE_SESSION_ID ao ser iniciado. Abra o Vonage Playground, entre na mesma sessão e fale. O agente responde com respostas faladas em tempo real usando o AWS Nova Sonic.

Gerenciamento de sessões:

# Force the agent to leave the session
curl -X POST http://localhost:8000/leave

# Rejoin with a new or existing session
curl -X POST http://localhost:8000/join \
  -H "Content-Type: application/json" \
  -d '{"session_id": "your-session-id"}'

O AWS Nova Sonic tem uma janela de conexão de aproximadamente 8 minutos por sessão. O aplicativo emite um session_renewal_recommended evento antes que o limite seja atingido. Use /leave , então, /join para atualizar a sessão sem reiniciar o contêiner.

Assim que o agente estiver funcionando localmente, siga as etapas 5 a 7 para fazer a implantação em produção.

Etapa 4: Criar o pipeline de IA do Pipecat

O núcleo do aplicativo é a VonagePipecatAgent classe em agent.py. A integração do Vonage Video Connector com o Pipecat atua como camada de transporte, recebendo quadros de áudio da sessão de Video e enviando respostas de IA de volta.

from pipecat.transports.vonage.video_connector import (
    VonageVideoConnectorTransport,
    VonageVideoConnectorTransportParams,
)
from pipecat.services.aws.nova_sonic.llm import AWSNovaSonicLLMService, Params
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair

# Vonage Video Connector transport — joins session as WebRTC participant
transport = VonageVideoConnectorTransport(
    application_id=application_id,
    session_id=session_id,
    token=token,
    params=VonageVideoConnectorTransportParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        video_in_enabled=False,
        video_out_enabled=False,
        publisher_name="Vonage AI Assistant",
        audio_in_sample_rate=16000,
        audio_in_channels=1,
        # Nova Sonic returns 24kHz audio — output sample rate must match
        audio_out_sample_rate=24000,
        audio_out_channels=1,
        vad_analyzer=SileroVADAnalyzer(),
        audio_in_auto_subscribe=True,
        video_in_auto_subscribe=False,
    ),
)

# AWS Nova Sonic — speech-to-speech AI
nova_sonic = AWSNovaSonicLLMService(
    access_key_id=frozen_credentials.access_key,
    secret_access_key=frozen_credentials.secret_key,
    session_token=frozen_credentials.token,
    region=aws_region,
    model=bedrock_model_id,
    params=Params(
        input_sample_rate=16000,
        input_channel_count=1,
        # Must match audio_out_sample_rate above
        output_sample_rate=24000,
        output_channel_count=1,
    ),
    system_instruction="You are a helpful voice assistant for a Vonage video session. Keep responses brief and conversational.",
)

# LLMContextAggregatorPair maintains conversational memory across user and assistant turns
context_aggregator = LLMContextAggregatorPair(context)

# 5-stage pipeline with context aggregators for conversation memory
pipeline = Pipeline([
    transport.input(),              # Audio in from Vonage Video session
    context_aggregator.user(),      # Accumulate user speech turns
    nova_sonic,                     # Speech-to-speech AI processing
    context_aggregator.assistant(), # Accumulate assistant responses
    transport.output(),             # Audio out back to Vonage Video session
])

Etapa 5: Implemente seu agente com o AgentCore

O AgentCore é o ambiente de execução gerenciado do AWS Bedrock para implantar e dimensionar agentes de IA em produção, sem a necessidade de gerenciar servidores ou infraestrutura de contêineres por conta própria. Ele está disponível para uso geral (GA).

Neste projeto, o AgentCore é o host de tempo de execução, e, portanto, todo o agente Pipecat é executado dentro do AgentCore Runtime. O agente ingressa na sessão do Vonage Video como um participante WebRTC nativo a partir do AgentCore.

Quando um usuário aciona o agente, o App Runner gera uma nova URL do WebSocket do AgentCore pré-assinada e a transmite vonage_session_id e vonage_token para o AgentCore por meio do contexto de invocação. O AgentCore encaminha a conexão para o /ws , onde VonageVideoConnectorTransport se junta à sessão de Video como um participante nativo do WebRTC.

# runtime/agent.py — runs inside AgentCore Runtime
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from pipecat.transports.vonage.video_connector import (
    VonageVideoConnectorTransport,
    VonageVideoConnectorTransportParams,
)
from pipecat.audio.vad.silero import SileroVADAnalyzer

app = BedrockAgentCoreApp()

@app.websocket("/ws")
async def ws_handler(websocket: WebSocket, context: dict) -> None:
    await websocket.accept()  # mandatory — BedrockAgentCoreApp does not auto-accept

    # Session context from AgentCore invoke payload — dynamic per call
    session_id = context.get("vonage_session_id")
    token = context.get("vonage_token")

    transport = VonageVideoConnectorTransport(
        application_id=application_id,
        session_id=session_id,
        token=token,
        params=VonageVideoConnectorTransportParams(
            audio_in_enabled=True,
            audio_out_enabled=True,
            video_in_enabled=False,
            video_out_enabled=False,
            vad_analyzer=SileroVADAnalyzer(),
            audio_in_auto_subscribe=True,
        ),
    )

await websocket.accept() deve ser chamado explicitamente. BedrockAgentCoreApp Ele não aceita automaticamente conexões WebSocket; omitir essa chamada faz com que o AgentCore feche a conexão com o erro 1008: “limite do buffer de gravação excedido”.

Implemente seu agente no AgentCore:

cd runtime/

agentcore configure \
  -e agent.py \
  -r us-east-1 \
  -n your_agent_name \
  --non-interactive \
  --deployment-type direct_code_deploy \
  --runtime PYTHON_3_13 \
  -rf requirements.txt

AWS_PROFILE=vonage-dev agentcore deploy -a your_agent_name
# → Copy Runtime ARN from output — you'll need it for Step 6

Este aplicativo requer o Python 3.13. vonage-video-connector>=1.0.0 requer >=3.13,<3.14. Use --runtime PYTHON_3_13 em agentcore configure.

Seu agente agora está em execução no AgentCore. A Vonage se conecta diretamente ao endpoint integrado do AgentCore /ws — sem necessidade de EC2, ECS ou EKS.

Etapa 6: Implantar o App Runner /answer Operador

O App Runner lida com o webhook de acionamento do agente. Ele gera uma nova URL do WebSocket do AgentCore pré-assinada para cada sessão e passa o contexto da sessão para o AgentCore:

# answer/answer.py
from bedrock_agentcore.runtime import AgentCoreRuntimeClient

client = AgentCoreRuntimeClient(region=region)

presigned_url = client.generate_presigned_url(
    runtime_arn,
    session_id=session_id
)
# Returns presigned_url in JSON response
# vonage_session_id and vonage_token passed to AgentCore invoke context

Compilar e enviar para o ECR:

TMPDIR=$(mktemp -d)
ECR="{account}.dkr.ecr.us-east-1.amazonaws.com/vonage-agentcore-video-answer"

docker build --platform linux/amd64 -t vonage-agentcore-video-answer ./answer
docker tag vonage-agentcore-video-answer:latest $ECR:latest

ECR_PASS=$(aws ecr get-login-password --region us-east-1)
echo "$ECR_PASS" | DOCKER_CONFIG="$TMPDIR" docker login \
  --username AWS --password-stdin {account}.dkr.ecr.us-east-1.amazonaws.com
DOCKER_CONFIG="$TMPDIR" docker push $ECR:latest

Crie o serviço App Runner:

Veja README.md para obter o aws apprunner create-service .

Atualizar as variáveis de ambiente do App Runner:

aws apprunner update-service --service-arn <arn> \
  --source-configuration '{
    "ImageRepository": {
      "ImageConfiguration": {
        "RuntimeEnvironmentVariables": {
          "AGENTCORE_RUNTIME_ARN": "<runtime-arn-from-step-5>",
          "VONAGE_APPLICATION_ID": "<your-vonage-application-id>",
          "AWS_DEFAULT_REGION": "us-east-1"
        }
      }
    }
  }'

Configuração do IAM no App Runner:

Seu endpoint do App Runner já está ativo:

https://{service-id}.us-east-1.awsapprunner.com/answer

Etapa 7: Teste com o Vonage Playground

Com seu agente em execução no AgentCore e o App Runner implantado, valide toda a pilha de produção usando o Vonage Playground— sem necessidade de um aplicativo cliente personalizado.

Etapa 7.1: Criar uma sessão do Vonage Video

Faça login no seu Painel da Vonage → Video → Ferramentas → Playground. Crie uma sessão roteada e copie o ID da sessão.

Etapa 7.2: Gerar um token de editor para o agente

No Vonage Playground, gere um token de editor para a sessão do agente.

Etapa 7.3: Acionar o agente por meio do App Runner

curl -X POST https://{service-id}.us-east-1.awsapprunner.com/answer \
  -H "Content-Type: application/json" \
  -d '{
    "vonage_session_id": "<your-session-id>",
    "vonage_token": "<publisher-token>"
  }'
# Expected response:
# {"status": "started", "vonage_session_id": "..."}

Etapa 7.4: Participe da sessão no Vonage Playground

1. Acesse Vonage Playground

2. Insira sua chave de API e ID da sessão

3. Gerar um token de assinante para você mesmo

4. Clique Conectar—agora você está na mesma sessão que o agente

5. Fale — o agente responde em tempo real por meio do Nova Sonic

Agora você deve ver o agente aparecer como um segundo participante na sessão. Quando você fala, o Nova Sonic processa seu áudio, e o agente responde. O áudio do agente é transmitido de volta para todos os participantes da sessão.

Monitore os logs durante o teste:

AWS_PROFILE=vonage-dev aws logs tail \
/aws/bedrock-agentcore/runtimes/{runtime-id}-DEFAULT \
  --log-stream-name-prefix "$(date +%Y/%m/%d)/[runtime-logs]" \
  --follow \
  --region us-east-1

Lista de verificação da produção

• Tempo de execução: Use o Python 3.13 para o AgentCore Runtime — o vonage-video-connector requer versão >=3.13,<3.14

• ARM64: Compile o contêiner AgentCore com a opção --platform linux/arm64

• WebSocket: await websocket.accept() como primeira linha no arquivo runtime/agent.py no manipulador @app.websocket

• Contexto da sessão: Passe vonage_session_id e vonage_token dinamicamente por meio do contexto de invocação do AgentCore — nunca use variáveis de ambiente estáticas

• IAM: Use funções do IAM — nunca utilize chaves estáticas da AWS em produção

• TURN: O VonageVideoConnectorTransport lida com o TURN de forma nativa — não é necessário nenhum servidor TURN externo

• Valide primeiro: Teste com o Vonage Playground antes de integrar o aplicativo de referência do React

• Segredos: Armazene VONAGE_APPLICATION_ID e AGENTCORE_RUNTIME_ARN nas variáveis de ambiente do App Runner

• Comportamento da sessão: Ajuste os parâmetros NOVA_SESSION_WARN_SECONDS e NOVA_SESSION_LIMIT_SECONDS para sessões de Video de longa duração

• Verify: execute o comando `curl` no endpoint `/answer` e confirme a resposta antes de testar uma sessão real

Outros recursos

• Vonage Video Playground

• Vonage Video Transport para Pipecat

• Documentação do AWS Nova Sonic

• Documentação do AWS Bedrock AgentCore

• GitHub - vonage-pipecat-aws-agentcore

Conclusão

Você implantou um agente de vídeo com IA em tempo real utilizando o Vonage Video Transport para Pipecat e o AWS Nova Sonic, executado inteiramente no AWS Bedrock AgentCore Runtime com um endpoint de webhook público do App Runner.

O Vonage Video Transport para Pipecat (VonageVideoConnectorTransport) participa da sessão do Vonage Video como um participante WebRTC nativo. O Nova Sonic lida com o processamento de voz para voz em tempo real. O AgentCore oferece um ambiente de execução gerenciado para implantação e escalonamento, sem a necessidade de gerenciar infraestruturas EC2, ECS ou EKS.

Na Parte 2, vamos mudar do Video para a telefonia usando o Vonage Audio Serializer para Pipecat e a Voice API da Vonage, uma solução baseada em WebSocket para agentes de IA que atendem chamadas telefônicas ao vivo — também totalmente implantada no AgentCore Runtime.