Agentes de Video AI Con Vonage, Pipecat y AgentCore

Introducción

Ahora los desarrolladores pueden añadir participantes conversacionales de IA directamente en las sesiones de vídeo en directo. En lugar de videollamadas pasivas, puedes crear agentes de IA que escuchen, respondan e interactúen de forma natural durante las conversaciones en directo.

En este tutorial, implementarás un agente de IA para sesiones de Video utilizando el Vonage Video Transport para Pipecat y AWS Nova Sonic. El repositorio admite dos vías: el desarrollo local con Docker para una iteración rápida y la implementación en producción con el agente ejecutándose íntegramente dentro de AWS Bedrock AgentCore Runtime. Este tutorial te guía a través de ambas: empieza localmente para validar tu pipeline y, a continuación, implementa en producción con «agentcore deploy» y AWS App Runner.

El transporte de vídeo de Vonage para Pipecat te permite crear aplicaciones basadas en inteligencia artificial que se integran a la perfección en las sesiones de la Video API de Vonage. Este transporte te permite recibir audio y vídeo de los participantes en la sesión y enviar de vuelta a la sesión, en tiempo real, el audio y el vídeo procesados.

Pipecat es un marco de código abierto para desarrollar aplicaciones de IA conversacional de voz y multimodal. El conector de vídeo de Vonage sirve de puente entre el proceso de tratamiento de medios de Pipecat y las sesiones de la Video API de Vonage, lo que permite una amplia variedad de casos de uso. AWS Nova Sonic está optimizado para interacciones de voz conversacionales de baja latencia, lo que lo hace ideal para sesiones de Video en directo. AWS Bedrock AgentCore Runtime es una infraestructura segura y sin servidores diseñada para implementar y escalar agentes de Voice e IA en tiempo real y de baja latencia a gran escala, sin la complejidad que supone gestionar los servidores subyacentes.

Lo usarás:

• Transporte WebRTC de Vonage Video Connector para Pipecat para la orquestación de canalizaciones de IA

• AWS Nova Sonic para IA de voz

• AWS Bedrock AgentCore permite a los desarrolladores implementar y escalar agentes de IA.

Siga adelante y encuentre el código de trabajo para este ejemplo en GitHub.

Qué construirás

Al final de este tutorial, usted tendrá:

• Un agente de IA implementado en AWS Bedrock AgentCore Runtime, un contenedor sin servidor y totalmente gestionado que ejecuta tu pipeline de Pipecat

• Un punto de conexión público de App Runner que gestiona el webhook de activación del agente y transmite el contexto de la sesión a AgentCore

• Respuestas de voz en tiempo real generadas por IA mediante AWS Nova Sonic (de voz a voz, sin cadena STT/TTS)

• Una arquitectura de producción que no requiere EC2, ECS ni ALB: solo una implementación de Agentcore y un servicio App Runner

• Una ruta de prueba validada mediante Vonage Playground antes de integrar la aplicación de referencia Vonage Video React

Requisitos previos

Antes de empezar, asegúrate de tener lo siguiente:

• A Account API de Vonage con Video API habilitada

• Una cuenta de cuenta de AWS con acceso Amazon Bedrock a Nova Sonic (amazon.nova-2-sonic-v1:0)

• Se requiere Python 3.13 para vonage-video-connector >= 1.0.0

• uv gestor de paquetes (brew install uv en macOS)

• Escritorio Docker - necesario porque el SDK de Vonage Video Connector actualmente sólo se ejecuta en Linux

• ngrok para el desarrollo local

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

Cómo colaboran Bedrock y AgentCore

Este proyecto utiliza dos servicios complementarios de AWS:

Cómo trabajan juntos en este repositorio:

1. Bedrock + Núcleo del agente (producto final) - juntos para un agente listo para producción con herramientas de gestión

2. Bedrock solo - una opción más ligera para experimentos rápidos y agentes conversacionales sencillos

3. Ampliado - añade funciones del mundo real, como RAG, llamadas API y búsquedas en CRM, junto con voz de baja latencia.

Versión corta: Bedrock responde; AgentCore ejecuta la lógica de la aplicación del agente desplegable.

Arquitectura

La integración sigue un flujo basado en WebRTC: el agente de IA se une a la sesión de Vonage Video como participante mediante el SDK de Vonage Video Connector. A continuación, Pipecat orquesta la canalización de IA, enrutando el audio a través de AWS Nova Sonic para el procesamiento de voz a voz. Si está configurado, AgentCore prepara al agente al inicio de la sesión con contexto personalizado o acceso a herramientas.Architecture overview: Vonage Video session → Pipecat pipeline → AWS Nova Sonic → AgentCore.

Desarrollo local

1. Navegador (Vonage Playground) se conecta a la sesión de Video RTC de Vonage.

2. POST /join {vonage_session_id, vonage_token} se envía a FastAPI (app/main.py, puerto 8000).

3. FastAPI inicia VonageVideoConnectorTransport (WebRTC), uniéndose a la sesión como participante nativo.

4. El Pipecat Pipeline se encarga de procesar los medios.

5. AWS Nova Sonic se encarga del procesamiento de IA.

6. El audio se transmite de vuelta a los participantes de la sesión de Video.

Producción

1. Navegador (Aplicación de referencia Vonage Video React) envía POST /answer {vonage_session_id, vonage_token}.

2. App Runner (answer/server.py — punto final HTTPS público) invoca AgentCoreRuntimeClient.generate_presigned_url().

3. Esto pasa vonage_session_id + vonage_token a AgentCore contexto de invocación.

4. Entorno de ejecución de AgentCore (runtime/agent.py, puerto 8080, ARM64, Python 3.13) inicializa el BedrockAgentCoreApp.

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

6. VonageVideoConnectorTransport se une a la sesión de Video de Vonage como participante nativo.

7. El Pipecat Pipeline envía el audio a AWS Nova Sonic.

8. El audio se transmite de vuelta a los participantes de la sesión de Video.

Componentes clave

Antes de empezar: Crea una aplicación y una sesión de Vonage Video

Antes de configurar tu entorno, necesitas la aplicación Vonage Video y un ID de sesión.

Crear una aplicación de Video de Vonage

1. Inicie sesión en el Panel de Vonage

2. Ir a Applications → Crear una nueva aplicación

3. Activar Video función de vídeo

4. Haz clic en «Generar clave pública y privada» : esto descargará private.key

5. Guarda la solicitud: copia el ID de la aplicación

Crear una sesión de Video de Vonage

1. En el panel de control de Vonage, ve a Video → Herramientas → Playground

2. Selecciona tu solicitud

3. Haz clic en «Crear sesión» — copia el ID de sesión

Utiliza el modo de medios enrutados al utilizar el conector de Video. Utiliza un rol de token de editor para el participante en la sesión de IA.

Ahora tienes:

• VONAGE_APPLICATION_ID — tu ID de solicitud de Vonage

• VONAGE_SESSION_ID — tu ID de sesión de Video de Vonage

• private.key — descargado en tu ordenador

Paso 1: Clonar el repositorio

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

El diseño del repositorio:

vonage-pipecat-aws-agentcore/
├── app/ # DESARROLLO LOCAL — Aplicación FastAPI (main.py, agent.py), puerto 8000
├── runtime/ # PRODUCCIÓN — BedrockAgentCoreApp (agent.py), implementación de agentcore, Python 3.13 ARM64
├── answer/ # PRODUCCIÓN — Gestor /answer (App Runner)
├── tests/ # Etapas de validación C1–C6
├── docker-compose.yml
├── .env.example
└── README.md

Paso 2: Configure su entorno

Utilice siempre roles IAM o credenciales temporales en producción. Nunca codifique los secretos de AWS en el código ni los envíe al control de versiones.

cp .env.example .env

Abra .env y rellena tus credenciales:

# 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

El repositorio completo .env.example del repositorio contiene configuración adicional sobre tiempos de espera, límites de sesión y ajustes de producción. Las tres variables anteriores son todo lo que necesitas para ejecutar la demo local.

Configure su perfil de AWS

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

Crear una sesión de Video de Vonage

Para crear una sesión de Vonage Video, inicia sesión en el Panel de Vonagey ve a Video → Herramientas → Playgroundy crea una sesión enrutada. Copia el ID de la sesión en tu .env archivo.

Utilice routed el modo multimedia cuando utilices el Conector de Video. Utilice un publisher para el participante en la sesión AI.

Paso 3: Ejecutar localmente con Docker

El SDK de Vonage Video Connector requiere Linux. En macOS o Windows, Docker lo gestiona automáticamente.

Inicie la aplicación completa desde la raíz del repositorio:

docker compose --profile app up --build

Verify que se esté ejecutando:

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

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

La aplicación se conecta automáticamente VONAGE_SESSION_ID al iniciarse. Abre Vonage Playground, únete a la misma sesión y habla. El agente responde con respuestas habladas en directo utilizando AWS Nova Sonic.

Gestión de sesiones:

# 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"}'

AWS Nova Sonic tiene una ventana de conexión de ~8 minutos por sesión. La aplicación emite un evento session_renewal_recommended antes de que se alcance el límite. Utilice /leave y luego /join para refrescar la sesión sin reiniciar el contenedor.

Una vez que el agente esté funcionando localmente, sigue los pasos 5 a 7 para implementarlo en el entorno de producción.

Paso 4: Construir el Pipecat AI Pipeline

El núcleo de la aplicación es la clase VonagePipecatAgent clase agent.py. Vonage Video Connector Pipecat Integration actúa como capa de transporte, recibiendo tramas de audio de la sesión de Video y enviando respuestas de AI de vuelta.

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
])

Paso 5: Despliegue de su Agente con AgentCore

AgentCore es el entorno de ejecución gestionado de AWS Bedrock que permite implementar y escalar agentes de IA en producción sin necesidad de gestionar tú mismo los servidores ni la infraestructura de contenedores. Ya está disponible de forma general (GA).

En este proyecto, AgentCore es el host de tiempo de ejecución, por lo que todo el agente Pipecat se ejecuta dentro de AgentCore Runtime. El agente se une a la sesión de Vonage Video como un participante nativo de WebRTC desde dentro de AgentCore.

Cuando un usuario activa el agente, App Runner genera una nueva URL de WebSocket de AgentCore pre-firmada y la transmite vonage_session_id y vonage_token a AgentCore a través del contexto de invocación. AgentCore redirige la conexión al /ws , donde VonageVideoConnectorTransport se une a la sesión de Video como participante nativo de 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() Debe invocarse explícitamente. BedrockAgentCoreApp no acepta automáticamente conexiones WebSocket; si se omite, AgentCore cerrará la conexión con el error 1008: «límite del búfer de escritura superado».

Implementa tu agente en 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

Esta aplicación requiere Python 3.13. vonage-video-connector>=1.0.0 requiere >=3.13,<3.14. Utiliza --runtime PYTHON_3_13 en agentcore configure.

Tu agente ya se está ejecutando en AgentCore. Vonage se conecta directamente al punto final integrado de AgentCore /ws , sin necesidad de EC2, ECS ni EKS.

Paso 6: Implementar App Runner /answer Operador

App Runner gestiona el webhook de activación del agente. Genera una nueva URL de WebSocket de AgentCore pre-firmada para cada sesión y transmite el contexto de la sesión a 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 y enviar a 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

Crea el servicio App Runner:

Ver README.md para ver el aws apprunner create-service comando.

Actualizar las variables de entorno de 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"
        }
      }
    }
  }'

Configuración de IAM en App Runner:

Tu punto de conexión de App Runner ya está activo:

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

Paso 7: Prueba con Vonage Playground

Una vez que el agente se esté ejecutando en AgentCore y se haya implementado App Runner, comprueba el funcionamiento de toda la pila de producción utilizando Vonage Playground, sin necesidad de una aplicación de cliente personalizada.

Paso 7.1: Crear una sesión de Vonage Video

Inicia sesión en tu panel de control de Vonage → Video → Herramientas → Playground. Crea una sesión enrutada y copia el ID de la sesión.

Paso 7.2: Generar un token de editor para el agente

En Vonage Playground, genera un token de editor para la sesión del agente.

Paso 7.3: Activar el agente mediante 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": "..."}

Paso 7.4: Únete a la sesión en Vonage Playground

1. Ir a Vonage Playground

2. Introduce tu clave API y ID de sesión

3. Generar un token de suscriptor para ti mismo

4. Haz clic Conectar: ahora estás en la misma sesión que el agente

5. Habla: el agente te responde en tiempo real a través de Nova Sonic

Ahora deberías ver que el agente aparece como segundo participante en la sesión. Cuando hablas, Nova Sonic procesa tu audio y el agente responde. El audio del agente se transmite a todos los participantes de la sesión.

Registra los archivos de log durante la prueba:

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 control de la producción

• Entorno de ejecución: Utilice Python 3.13 para el tiempo de ejecución de AgentCore: vonage-video-connector requiere una versión >=3.13,<3.14

• ARM64: Compila el contenedor AgentCore con --platform linux/arm64

• WebSocket: await websocket.accept() como primera línea en runtime/agent.py @app.websocket handler

• Contexto de sesión: Pasa vonage_session_id y vonage_token de forma dinámica a través del contexto de invocación de AgentCore; nunca utilices variables de entorno estáticas.

• IAM: Utiliza roles de IAM; nunca utilices claves estáticas de AWS en producción

• TURN: VonageVideoConnectorTransport gestiona TURN de forma nativa, sin necesidad de un servidor TURN externo

• Prueba primero: Prueba con Vonage Playground antes de integrar la aplicación de referencia de React

• Secretos: Guarda VONAGE_APPLICATION_ID y AGENTCORE_RUNTIME_ARN en las variables de entorno de App Runner

• Comportamiento de la sesión: Ajuste NOVA_SESSION_WARN_SECONDS y NOVA_SESSION_LIMIT_SECONDS para sesiones de Video de larga duración

• Verify: utilice curl con el punto final /answer y compruebe la respuesta antes de probar una sesión real

Otros recursos

• Video Playground de Vonage

• Transporte de Video de Vonage para Pipecat

• Documentación de AWS Nova Sonic

• Documentación de AWS Bedrock AgentCore

• GitHub - vonage-pipecat-aws-agentcore

Conclusión

Ha implementado un agente de vídeo con IA en tiempo real utilizando Vonage Video Transport para Pipecat y AWS Nova Sonic, que se ejecuta íntegramente en AWS Bedrock AgentCore Runtime con un punto final de webhook público de App Runner.

Vonage Video Transport para Pipecat (VonageVideoConnectorTransport) se une a la sesión de Vonage Video como participante nativo de WebRTC. Nova Sonic se encarga del procesamiento de voz a voz en tiempo real. AgentCore proporciona un entorno de ejecución gestionado para la implementación y el escalado sin necesidad de gestionar la infraestructura de EC2, ECS o EKS.

En la segunda parte, pasaremos del Video a la telefonía utilizando el Vonage Audio Serializer para Pipecat y la Voice API de Vonage, una solución basada en WebSocket para agentes de IA que responden a llamadas telefónicas en directo, también implementada íntegramente dentro de AgentCore Runtime.