Agents vidéo IA avec Vonage, Pipecat et AgentCore

Introduction

Les développeurs peuvent désormais ajouter des participants IA conversationnels directement dans les sessions vidéo en direct. Au lieu d'appels vidéo passifs, vous pouvez construire des agents d'IA qui écoutent, répondent et interagissent naturellement pendant les conversations en direct.

Dans ce tutoriel, vous allez déployer un agent IA pour des sessions Video à l'aide de Vonage Video Transport pour Pipecat et AWS Nova Sonic. Le référentiel prend en charge deux approches : le développement local à l’aide de Docker pour des itérations rapides, et le déploiement en production avec l’agent s’exécutant entièrement au sein d’AWS Bedrock AgentCore Runtime. Ce tutoriel vous guide à travers ces deux approches : commencez en local pour valider votre pipeline, puis déployez en production à l’aide de la commande `agentcore deploy` et d’AWS App Runner.

Le protocole de transport vidéo Vonage pour Pipecat vous permet de développer des applications basées sur l'IA qui s'intègrent de manière transparente aux sessions de la Video API Vonage. Ce protocole de transport vous permet de recevoir le flux audio et vidéo des participants à la session et de renvoyer en temps réel le flux audio et vidéo traité vers la session.

Pipecat est un framework open source permettant de développer des applications d'IA conversationnelle vocale et multimodale. Le connecteur vidéo Vonage assure la liaison entre le pipeline de traitement multimédia de Pipecat et les sessions de la Video API Vonage, ce qui ouvre la voie à un large éventail de cas d'utilisation. AWS Nova Sonic est optimisé pour les interactions vocales conversationnelles à faible latence, ce qui le rend particulièrement adapté aux sessions Video en direct. AWS Bedrock AgentCore Runtime est une infrastructure sécurisée et sans serveur, conçue pour déployer et faire évoluer à grande échelle des agents vocaux et d’IA en temps réel et à faible latence, sans la complexité liée à la gestion des serveurs sous-jacents.

Vous utiliserez :

• Vonage Video Connector Transport WebRTC pour Pipecat pour l'orchestration de pipeline d'IA

• AWS Nova Sonic pour l'IA vocale

• AWS Bedrock AgentCore permet aux développeurs de déployer et de mettre à l'échelle des agents d'intelligence artificielle.

Passez à l'étape suivante et trouvez le code de travail de cet exemple sur GitHub. code de travail pour cet exemple sur GitHub.

Ce que vous allez construire

À la fin de ce tutoriel, vous aurez :

• Un agent IA déployé au sein d'AWS Bedrock AgentCore Runtime — un conteneur sans serveur entièrement géré qui exécute votre pipeline Pipecat

• Un point de terminaison public d'App Runner qui gère le webhook de déclenchement de l'agent et transmet le contexte de la session à AgentCore.

• Réponses vocales en temps réel de l'IA à l'aide de AWS Nova Sonic (speech-to-speech, pas de chaîne STT/TTS)

• Une architecture de production qui ne nécessite ni EC2, ni ECS, ni ALB - juste un agentcore deploy et un service App Runner.

• Un parcours de test validé à l'aide de Vonage Playground avant l'intégration de l'application de référence Vonage Video React.

Conditions préalables

Avant de commencer, assurez-vous que vous disposez des éléments suivants :

• A Compte API Vonage avec Video API activé

• Un compte Un Account AWS avec accès à Amazon Bedrock pour Nova Sonic (amazon.nova-2-sonic-v1:0)

• Python 3.13 requis par vonage-video-connector>=1.0.0

• uv (brew install uv sur macOS)

• Bureau Docker - nécessaire car le SDK du connecteur Video de Vonage ne fonctionne actuellement que sur Linux

• ngrok pour le développement local

• AWS CLI configuré (aws configure --profile profile-name)

Comment Bedrock et AgentCore travaillent ensemble

Ce projet utilise deux services AWS complémentaires :

Comment ils travaillent ensemble dans ce référentiel :

1. Bedrock + Agent Core (produit final) - ensemble pour un agent prêt à la production avec des outils de gestion

2. Le socle rocheux seul - une option plus légère pour des expériences rapides et des agents conversationnels simples

3. Étendues - ajouter des fonctionnalités du monde réel telles que RAG, les appels API et les consultations CRM en plus de la voix à faible latence.

Version courte : Bedrock répond ; AgentCore exécute la logique de l'application de l'agent déployable.

Aperçu de l'architecture

L'intégration suit un flux basé sur WebRTC : l'agent d'IA rejoint la session Vonage Video en tant que participant à l'aide du SDK Vonage Video Connector. Pipecat orchestre ensuite le pipeline d'IA, en acheminant l'audio via AWS Nova Sonic pour le traitement de la parole. S'il est configuré, AgentCore prépare l'agent au début de la session avec un contexte personnalisé ou un accès aux outils.Architecture overview: Vonage Video session → Pipecat pipeline → AWS Nova Sonic → AgentCore.

Développement local

1. Navigateur (Vonage Playground) se connecte à la session Video WebRTC de Vonage.

2. POST /join {vonage_session_id, vonage_token} est envoyé à l'interface FastAPI (app/main.py, port 8000).

3. FastAPI initie VonageVideoConnectorTransport (WebRTC), rejoignant la session en tant que participant natif.

4. Le Pipecat Pipeline traite les médias.

5. AWS Nova Sonic gère le traitement de l'IA.

6. Les flux audio sont renvoyés aux participants de la session Video.

Production

1. Navigateur (In-App Video React Reference App) envoie POST /answer {vonage_session_id, vonage_token}.

2. App Runner (answer/server.py - public HTTPS endpoint) invoque AgentCoreRuntimeClient.generate_presigned_url().

3. Cela passe vonage_session_id + vonage_token à l'agent AgentCore invoquer le contexte.

4. AgentCore Runtime (runtime/agent.py, port 8080, ARM64, Python 3.13) initialise le fichier BedrockAgentCoreApp.

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

6. VonageVideoConnectorTransport rejoint la session Vonage Video en tant que participant natif.

7. Le Pipecat Pipeline achemine l'audio vers AWS Nova Sonic.

8. Les flux audio sont renvoyés aux participants de la session Video.

Composants clés

Avant de commencer : créer une application et une session Vonage Video

Avant de configurer votre environnement, vous devez disposer de l'application Vonage Video et d'un identifiant de session.

Créer une application Video Vonage

1. Connectez-vous au tableau de bord Vonage

2. Aller à Applications → Créer une nouvelle application

3. Activer Video vidéo

4. Cliquez sur « Générer une clé publique et une clé privée » : cela permet de télécharger private.key

5. Enregistrez l'application — copiez l' ID de l'application

Créer une session Video Vonage

1. Dans le tableau de bord Vonage, accédez à Video → Outils → Playground

2. Sélectionnez votre application

3. Cliquez sur Créer une session — copiez l’ ID de session

Utilisez le mode « Routed Media » lorsque vous utilisez le connecteur Video. Utilisez un rôle de jeton d'éditeur pour le participant à la session d’IA.

Vous disposez désormais de :

• VONAGE_APPLICATION_ID — votre identifiant d'application Vonage

• VONAGE_SESSION_ID — votre identifiant de session Video Vonage

• private.key — téléchargé sur votre ordinateur

Étape 1 : Cloner le référentiel

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

La présentation du référentiel :

vonage-pipecat-aws-agentcore/
├── app/ # LOCAL DEV - FastAPI app (main.py, agent.py), port 8000
├── runtime/ # PRODUCTION - BedrockAgentCoreApp (agent.py), agentcore deploy, Python 3.13 ARM64
├── answer/ # PRODUCTION - /answer handler (App Runner)
├── tests/ # étapes de validation C1-C6
├── docker-compose.yml
├── .env.example
└── README.md

Étape 2 : Mise en place de l'environnement

Utilisez toujours des rôles IAM ou des identifiants temporaires en production. Ne jamais coder en dur les secrets AWS dans votre code ou les livrer au contrôle de version.

cp .env.example .env

Ouvrez .env et remplissez vos données d'identification :

# 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

Le dépôt complet .env.example du dépôt contient des configurations supplémentaires concernant les délais d'expiration, les limites de session et les paramètres de production. Les trois variables ci-dessus suffisent pour exécuter la démo locale.

Configurez votre profil AWS

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

Créer une session Video Vonage

Pour créer une session Vonage Video, ouvrez une session dans le tableau de bord de Vonageet naviguez jusqu'à Video → Outils → Terrain de jeuet créez une session acheminée. Copiez l'identifiant de la session dans votre .env fichier.

Utiliser routed lors de l'utilisation du connecteur Video. Utilisez un rôle publisher pour le participant à la session AI.

Étape 3 : Exécuter localement avec Docker

Le kit de développement logiciel du connecteur Video de Vonage nécessite Linux. Sur macOS ou Windows, Docker s'en charge automatiquement.

Démarrer l'application complète à partir de la racine du répertoire :

docker compose --profile app up --build

Vérifiez qu'il fonctionne :

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

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

L'application se connecte automatiquement VONAGE_SESSION_ID au démarrage. Ouvrez Vonage Playground, rejoignez la même session et parlez. L’agent vous répondra par des réponses vocales en temps réel grâce à AWS Nova Sonic.

Gestion des sessions :

# 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 a une fenêtre de connexion d'environ 8 minutes par session. L'application émet un événement session_renewal_recommended avant que la limite ne soit atteinte. Utiliser /leave then /join pour rafraîchir la session sans redémarrer le conteneur.

Une fois que l'agent fonctionne en local, passez aux étapes 5 à 7 pour procéder au déploiement en production.

Étape 4 : Construire le pipeline d'IA de Pipecat

Le cœur de l'application est la classe VonagePipecatAgent dans agent.py. Le Vonage Video Connector Pipecat Integration agit en tant que couche de transport, recevant des trames audio de la session Video et envoyant des réponses AI en retour.

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

Étape 5 : Déployer votre agent avec AgentCore

AgentCore est l'environnement d'exécution géré d'AWS Bedrock qui permet de déployer et de faire évoluer des agents d'IA en production sans avoir à gérer soi-même les serveurs ou l'infrastructure de conteneurs. Il est désormais disponible en version générale (GA).

Dans ce projet, AgentCore est l'hôte d'exécution hôte d'exécution, et donc l'ensemble de l'agent Pipecat s'exécute à l'intérieur d'AgentCore Runtime. L'agent rejoint la session Video de Vonage en tant que participant WebRTC natif à partir d'AgentCore.

Lorsqu'un utilisateur déclenche l'agent, App Runner génère une nouvelle URL WebSocket AgentCore pré-signée et transmet les informations suivantes vonage_session_id et vonage_token à AgentCore via le contexte d'invocation. AgentCore achemine la connexion vers le gestionnaire de l'agent /ws de votre agent, où VonageVideoConnectorTransport rejoint la session Video en tant que participant WebRTC natif.

# 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() doit être appelé explicitement. BedrockAgentCoreApp n'accepte pas automatiquement les connexions WebSocket ; en l'omettant, AgentCore ferme la connexion avec l'erreur 1008 : "write buffer limit exceeded".

Déployez votre agent sur 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

Cette application nécessite Python 3.13 . vonage-video-connector>=1.0.0 nécessite >=3.13,<3.14. Utiliser --runtime PYTHON_3_13 dans agentcore configure.

Votre agent fonctionne maintenant dans AgentCore. Vonage se connecte directement au point final intégré d'AgentCore. /ws d'AgentCore - pas besoin d'EC2, d'ECS ou d'EKS.

Étape 6 :Déployer l'App Runner/answer Manipulateur

App Runner gère le webhook de déclenchement de l'agent. Il génère une nouvelle URL WebSocket AgentCore pré-signée pour chaque session et transmet le contexte de la session à 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

Compiler et pousser vers 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

Créer le service App Runner :

Voir le fichier README.md pour le texte complet de la commande aws apprunner create-service complète.

Mettre à jour les variables d'environnement d'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"
        }
      }
    }
  }'

Configuration de l'IAM pour App Runner :

Votre point de terminaison App Runner est maintenant en ligne :

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

Étape 7 : Test avec Vonage Playground

Avec votre agent fonctionnant dans AgentCore et App Runner déployé, validez la pile de production complète en utilisant Vonage Playground-aucune application client personnalisée n'est nécessaire.

Étape 7.1 : Créer une session Vonage Video

Connectez-vous à votre tableau de bord Vonage → Video → Outils → Aire de jeu. Créez une session acheminée et copiez l'identifiant de la session.

Etape 7.2 : Générer un jeton d'éditeur pour l'agent

Dans Vonage Playground, générez un jeton d'éditeur pour la session de l'agent.

Étape 7.3 : Déclencher l'agent via 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": "..."}

Étape 7.4 : Rejoindre la session dans Vonage Playground

1. Aller à Terrain de jeu Vonage

2. Saisissez votre clé API et ID de session

3. Générer un jeton d'abonné pour vous-même

4. Cliquer Connecter-vous êtes maintenant dans la même session que l'agent

5. Speak - l'agent répond en temps réel via Nova Sonic

Vous devriez maintenant voir l'agent apparaître comme un second participant à la session. Lorsque vous parlez, Nova Sonic traite votre audio et l'agent répond. L'audio de l'agent est retransmis à tous les participants de la session.

Tail les logs pendant les tests :

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

Liste de contrôle de la production

• Exécution : Utiliser Python 3.13 pour le Runtime AgentCore - vonage-video-connector nécessite >=3.13,<3.14

• ARM64 : Construire le conteneur AgentCore avec --platform linux/arm64

• WebSocket : await websocket.accept() as first line in runtime/agent.py @app.websocket handler

• Contexte de session : Passer vonage_session_id et vonage_token dynamiquement via le contexte d'invocation d'AgentCore - jamais de vars env statiques

• IAM : Utiliser les rôles IAM - jamais de clés AWS statiques en production

• TURN : VonageVideoConnectorTransport gère TURN de manière native - aucun serveur TURN externe n'est nécessaire.

• Validez d'abord : Tester avec Vonage Playground avant d'intégrer l'application de référence React.

• Secrets : Stocker VONAGE_APPLICATION_ID et AGENTCORE_RUNTIME_ARN dans les variables d'environnement d'App Runner

• Comportement de la session : Ajustez NOVA_SESSION_WARN_SECONDS et NOVA_SESSION_LIMIT_SECONDS pour les sessions vidéo de longue durée.

• Verify : curl le point de terminaison /answer et confirmer la réponse avant de tester une session réelle.

Ressources complémentaires

• Terrain de jeu vidéo de Vonage

• Vonage Video Transport pour Pipecat

• AWS Nova Sonic docs

• AWS Bedrock AgentCore docs

• GitHub - vonage-pipecat-aws-agentcore

Conclusion

Vous avez déployé un agent vidéo d'IA en temps réel en utilisant le transport vidéo Vonage pour Pipecat et AWS Nova Sonic, fonctionnant entièrement dans AWS Bedrock AgentCore Runtime avec un point de terminaison webhook public d'In-App Video.

Le transport vidéo de Vonage pour Pipecat (VonageVideoConnectorTransport) se joint à la session Vonage Video en tant que participant WebRTC natif. Nova Sonic gère le traitement de la parole en temps réel. AgentCore fournit un runtime géré pour le déploiement et la mise à l'échelle sans avoir à gérer l'infrastructure EC2, ECS ou EKS.

Dans la deuxième partie, nous passerons de la vidéo à la téléphonie en utilisant le Vonage Audio Serializer pour Pipecat et l'API Voice de Vonage, un chemin basé sur WebSocket pour les agents d'IA qui répondent aux appels téléphoniques en direct - également déployé entièrement à l'intérieur d'AgentCore Runtime.