Pipecat、AgentCore、Vonage を使ってリアルタイム AI 音声エージェントを構築する

はじめに

開発者は、AIエージェントを実際の通話に直接導入できるようになりました。静的なIVRメニューやスクリプト化されたボットではなく、標準的なVonageの通話を通じて、相手の話を聞き、自然な応答を行い、現実世界でのアクションを実行できるAIエージェントを構築できます。

このチュートリアルでは、Voice AIエージェントを音声通話でデプロイします。 Pipecat用Vonage Audio Serializer および AWS Nova Sonicを使用して、音声通話用のAIエージェントをデプロイします。 

このチュートリアルが終わる頃には、あなたはこうなっていることだろう：

• Vonageの電話番号を使って実際の電話に応答する、実用的なAI音声エージェント

• Amazon Nova Sonicを活用したPipecatパイプラインによる、リアルタイムの音声対音声会話

• AWS Bedrock AgentCore 内にデプロイされ、実行中の AI エージェントランタイム

• Vonageサーバーが、Vonage Voice通話とAgentCoreでホストされているエージェントとの間の認証済みブリッジとして機能する、完全にコンテナ化されたアプリ

先にスキップして このサンプルのコードはGitHubにあります。.

このチュートリアルでは、 Pipecat用Vonage Audio Serializer、Pipecatプラグイン（VonageFrameSerializer）を使用します。これは、Vonage Voice WebSocketに接続し、PCMオーディオフレームをVonageのWebSocket形式とPipecatの内部パイプライン形式の間で変換するものです。このプラグインは、Vonage Voice APIおよびVideo APIの両方における音声のみのAIユースケース向けに設計されており（動画処理は不要です）。 

このパスは、WebSocketを介してVonage VoiceおよびVideoセッションをPipecatパイプラインに接続します。完全なビデオフレーム処理やビデオアバターが必要な場合は、 Pipecat 向けの Vonage Video Transport をご参照ください。

これは、VonageとPipecatを活用したAI音声エージェントの構築に関する2回シリーズの第2回です：

• 第1部 では、 Pipecat向けVonage Video Transport、つまりVonage Videoセッションに参加するAIエージェント向けのWebRTCパスについて解説します。

• 第2部 （この記事）では、 Pipecat用Vonage Audio Serializer、つまりVoiceおよび電話通信のユースケース向けのWebSocketパスについて解説します。

前提条件

作業を始める前に、以下のことを確認してください：

• ある AWSアカウント で、Amazon Bedrockへのアクセス権とNova Sonic (amazon.nova-2-sonic-v1:0)が有効化された us-east-1

• Python 3.12 以降 — aws_sdk_bedrock_runtime パッケージ（Nova Sonic に必須）は、Python 3.12 以降でのみ提供されています。

• Docker Desktop — このアプリは Docker 上で実行され、隔離された再現性のある実行環境を実現します

• ngrok 安定したVonage Webhook URL用に予約されたドメインを使用したngrok

• AWS CLI の設定が完了しました (aws configure --profile vonage-dev)

• bedrock-agentcore-starter-toolkit CLI (pip install bedrock-agentcore-starter-toolkit) による実行時デプロイ

• A Vonage API Account Voice APIが有効化されており、Voiceアプリケーションに電話番号が紐付けられているもの

主要コンポーネント

注：AgentCoreは、Bedrock Agents自体が構築されている基盤となるフレームワークです。AgentCoreを直接使用することで、Bedrock Agentsによる高レベルの抽象化を経由することなく、エージェントのロジック、フレームワーク、モデルを完全に制御することができます。

アーキテクチャの概要

Vonage Voice API -> App Runner /answer -> AgentCore Runtime -> Vonage Audio Serializer for Pipecat -> Pipecat Pipeline -> AWS Nova Sonic

地域開発

Vonage Voice 音声通話
  ↓ GET /answer
ngrok → FastAPI /answer (app/main.py、ポート 8000)
  ↓ wss://your-reserved-domain.ngrok.app/ws を含む NCCO を返す
Vonage が FastAPI /ws に接続
  ↓
VonageFrameSerializer + FastAPIWebsocketTransport
  ↓
Pipecat パイプライン → Amazon Nova Sonic

製造

Vonage Voice 音声通話
  ↓ GET /answer
App Runner (answer/server.py — 公開 HTTPS エンドポイント)
  ↓ AgentCoreRuntimeClient.generate_presigned_url()
  ↓ wss://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/{arn}/ws を含む NCCO を返す
Vonage は AgentCore Runtime の /ws に直接接続する
  ↓
AgentCore Runtime (runtime/agent.py、ポート 8080)
  ↓ BedrockAgentCoreApp @app.websocket /ws
  ↓ await websocket.accept()
VonageFrameSerializer + FastAPIWebsocketTransport
  ↓
Pipecat パイプライン → Amazon Nova Sonic

ステップ1：リポジトリのクローン

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

このリポジトリには、2つのデプロイ先があります：

├── app/ ← ローカル開発環境：FastAPI アプリ全体（ポート 8000）
├── runtime/ ← 本番環境：AgentCore Runtime コンテナ（ポート 8080）
└── answer/ ← 本番環境：App Runner /answer ハンドラー

ステップ 2: 環境の設定

本番環境では常にIAMロールまたは一時的な認証情報を使用する。AWSシークレットをコードにハードコードしたり、バージョンコントロールにコミットしたりしないこと。

まず、提供された .env.example ファイルを .env：

cp .env.example .env

以下の .env ファイルを開き、認証情報を入力してください：

# Vonage Voice API
VONAGE_APPLICATION_ID=your-vonage-application-id
VONAGE_PRIVATE_KEY=private.key
VONAGE_NUMBER=+14155551234
VONAGE_CALL_ID=your-vonage-call-id          # local/tests only

# AWS
AWS_PROFILE=vonage-dev
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=amazon.nova-2-sonic-v1:0
BEDROCK_CONNECT_TIMEOUT_SECONDS=10
BEDROCK_READ_TIMEOUT_SECONDS=60
BEDROCK_MAX_ATTEMPTS=4
BEDROCK_VALIDATE_MODEL_ID=true

# AgentCore
AGENTCORE_AGENT_ARN=arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/your-runtime-id   # local bootstrap (optional)
AGENTCORE_RUNTIME_ARN=arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/your-runtime-id  # production /answer webhook

# Nova Sonic session guard
NOVA_SESSION_WARN_SECONDS=410
NOVA_SESSION_LIMIT_SECONDS=470
NOVA_SESSION_STOP_ON_LIMIT=false

# Agent behavior (local dev via .env; production via runtime/agent.py defaults)
BEDROCK_SYSTEM_INSTRUCTION=You are a helpful voice assistant. Respond warmly and briefly.
BEDROCK_INITIAL_USER_MESSAGE=Hello! How can I help you today?
AGENTCORE_BOOTSTRAP_PROMPT=Provide one short greeting plus one helpful follow-up question for a live voice assistant session.

# App
PORT=8000

AWSプロファイルの設定：

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

注： 本番環境のアプリのWebhookフローでは、 VONAGE_CALL_ID 。Vonageは /answerを呼び出し、NCCOを受信した後、メディアを /ws に自動的に接続します。

ステップ 3：Pipecat パイプライン用の Vonage オーディオ・シリアライザーを構築する

app/agent.py (ローカル開発) および runtime/agent.py (本番環境) は、Voice パイプラインを実装しています。これは、着信する Vonage WebSocket 接続ごとに 1 インスタンスが割り当てられます。Pipecat 用の Vonage Audio Serializer は、Vonage の WebSocket フォーマットと Pipecat の内部パイプラインフォーマット間のすべての PCM オーディオフレームの変換を処理します。

from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.serializers.vonage import VonageFrameSerializer
from pipecat.services.aws.nova_sonic.llm import AWSNovaSonicLLMService, Params
from pipecat.transports.websocket.fastapi import (
    FastAPIWebsocketParams,
    FastAPIWebsocketTransport,
)

# Vonage telephony-grade audio framing: 640 bytes = 20ms @ 16kHz PCM16 mono
# 16kHz is the standard sample rate used in this tutorial. The Vonage Voice WebSocket
# also supports 8kHz and up to 24kHz, but 16kHz is the recommended default for Nova Sonic.

serializer = VonageFrameSerializer(
    params=VonageFrameSerializer.InputParams(
        vonage_sample_rate=16000,
    )
)

transport = FastAPIWebsocketTransport(
    websocket=websocket,
    params=FastAPIWebsocketParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        add_wav_header=False,
        fixed_audio_packet_size=640,  # 20ms PCM frame at 16kHz
        serializer=serializer,
        vad_analyzer=SileroVADAnalyzer(),
    ),
)

# 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,
        output_sample_rate=16000,
        output_channel_count=1,
    ),
    system_instruction=system_instruction,
)

# 3-stage speech-to-speech pipeline
pipeline = Pipeline([
    transport.input(),   # Audio in from Vonage phone call
    nova_sonic,          # Speech-to-speech AI processing
    transport.output(),  # Audio out back to caller
])

なお、このチュートリアルでは16kHzを標準のサンプリングレートとして使用しています。Vonage Voice WebSocketは8kHzおよび最大24kHzにも対応していますが、Nova Sonicでは16kHzを推奨のデフォルト設定としています。

ステップ 4: AgentCore を使用してエージェントをデプロイする

AgentCore は、AWS Bedrock が提供するマネージドランタイムであり、サーバーやコンテナインフラを自ら管理することなく、本番環境で AI エージェントをデプロイおよびスケーリングできます。これは 一般提供（GA）状態です。

このプロジェクトでは、AgentCore がランタイムホストの役割を果たしており、Pipecat エージェント全体が AgentCore ランタイム内で実行されます。

BedrockとAgentCoreの連携方法

要約：Bedrockが処理を行い、AgentCoreがエージェントを実行します。

このアプリの仕組み

Vonageからの着信があると、App Runnerが /answer Webhookを処理し、新たに事前署名済みのAgentCore WebSocket URLを生成して、NCCO内で返します。VonageはそのURLを使用してAgentCore Runtimeに直接接続します。AgentCoreは接続をエージェントの /ws ハンドラーにルーティングし、そこで VonageFrameSerializer Pipecatパイプラインが処理を引き継ぎます。

その runtime/agent.py ファイル は 本番環境のエージェント内にあり、 AgentCoreの AgentCoreの内部で実行され、その呼び出し元として動作するわけではありません。

との主な構造上の相違点はapp/agent.py (ローカル開発)

# runtime/agent.py — runs inside AgentCore Runtime
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from starlette.websockets import WebSocket

app = BedrockAgentCoreApp()

@app.websocket
async def ws_handler(websocket: WebSocket, context) -> None:
    await websocket.accept()  # mandatory — BedrockAgentCoreApp does not auto-accept
    # VonageFrameSerializer + FastAPIWebsocketTransport + Nova Sonic pipeline run here

await websocket.accept() 明示的に呼び出す必要があります。 BedrockAgentCoreApp WebSocket接続を自動的に受け入れません。これを省略すると、AgentCoreはエラー1008「書き込みバッファの制限を超えました」を返して接続を閉じます。

以下の手順で、挨拶文やキャラクター設定をカスタマイズできます runtime/agent.py を編集することで、 BEDROCK_SYSTEM_INSTRUCTION および BEDROCK_INITIAL_USER_MESSAGE defaults を編集することでカスタマイズできます。接続時のキュー LLMRunFrame() を有効にして、Nova Sonic 532のタイムアウトを防ぎます。

独自のエージェントコア・エージェントを展開する

pip install bedrock-agentcore-starter-toolkit

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_12 \
  -rf requirements.txt

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

AWS_PROFILE=vonage-dev agentcore deploy -a your_agent_name --auto-update-on-conflict  # redeploy after changes

エージェントは現在、AgentCore上で実行されています。Vonageは、事前署名済みURLを介してAgentCoreの /ws エンドポイントに直接接続します。EC2、ECS、EKSは一切必要ありません。

App Runnerをデプロイする/answerハンドラー

App Runner は、Vonage Answer URL ウェブフックを処理します。App Runner は、AWS Elastic Container Registry にプッシュされ、AWS apprunner コマンドを使用してデプロイされます。これは、各通話ごとに新しい事前署名済みの AgentCore WebSocket URL を生成し、NCCO: として返します。

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

client = AgentCoreRuntimeClient(region="us-east-1")

def get_presigned_url(runtime_arn: str) -> str:
    return client.generate_presigned_url(
        runtime_arn,
        session_id=str(uuid.uuid4()),  # unique session per call
    )

boto3をそのまま使用しないでください generate_presigned_url('invoke_agent_runtime', ...)。これを使用すると、WebSocketのアップグレード時にHTTP 405を返すHTTPS POST URLが生成されてしまいます。代わりに AgentCoreRuntimeClient from bedrock_agentcore.runtimeを使用してください。

# Build and push to ECR
docker build --platform linux/amd64 -t vonage-agentcore-answer ./answer
docker push {account}.dkr.ecr.us-east-1.amazonaws.com/vonage-agentcore-answer:latest

# App Runner environment variables:
# AGENTCORE_RUNTIME_ARN = <runtime-arn-from-agentcore-deploy>
# VONAGE_NUMBER = <your-vonage-number>
# AWS_DEFAULT_REGION = us-east-1

Vonage Voice アプリケーションの「Answer URL」を、App Runner のエンドポイントに設定してください：

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

どこにs {​service-id} どこから来るのでしょうか？この一意のIDは、App Runnerサービスを作成する際にAWSによって自動生成されます。完全なサービスURLは、App Runnerコンソールで確認するか、以下のコマンドを実行することで確認できます：

aws apprunner describe-service \ --service-arn <your-service-arn> \ --query 'Service.ServiceUrl'

また、初めてデプロイを行う際、`aws apprunner create-service` の出力にもこの URL が表示されます。

App Runnerの完全なデプロイ手順（Docker → ECR → App Runner）については、 README.md App Runnerのデプロイ手順の詳細については、こちらを参照してください（Docker → ECR → aws apprunner create-service）については、ルートをご覧ください。

ステップ5：テスト通話を行う

Vonageの番号に電話をかけてください。Vonageから GET /answer リクエストを送信すると、App Runnerは新たに事前署名済みのAgentCore WebSocket URLを生成し、それをNCCO:で返します。

[
  {
    "action": "connect",
    "from": "VONAGE_NUMBER",
    "endpoint": [
      {
        "type": "websocket",
        "uri": "wss://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/{arn}/ws?X-Amz-Algorithm=...",
        "content-type": "audio/l16;rate=16000"
      }
    ]
  }
]

なぜNCCOはAgentCoreを直接参照しているのでしょうか？

App Runnerは応答時に新しいSigV4事前署名済みURLを生成し、VonageはそのURLを使用して即座に接続します。事前署名済みURLの有効期限は300秒ですが、WebSocket接続は一度確立されると、通話終了まで維持されます。AWSの認証処理はApp Runnerが行い、Vonageは単にそのURLを使用するだけです。

ローカル開発の場合、NCCOは代わりにngrokを介してお使いのローカルサーバーを指定します：

[
  {
    "action": "connect",
    "from": "VONAGE_NUMBER",
    "endpoint": [
      {
        "type": "websocket",
        "uri": "wss://your-reserved-domain.ngrok.app/ws",
        "content-type": "audio/l16;rate=16000"
      }
    ]
  }
]

コールフローの全容

1. 発信者があなたのVonage番号に電話をかける

2. Vonageは GET /answer App Runnerへ送信します

3. App Runnerは AgentCoreRuntimeClient.generate_presigned_url()を呼び出し、事前に署名済みの新しいAgentCore WSS URLを生成します

4. App Runnerは、事前に署名済みのURLをNCCOに返します

5. VonageはAgentCore Runtimeに直接接続します /ws 事前署名済みURLを使用して

6. runtime/agent.py 呼び出し await websocket.accept()、 VonageFrameSerializer 初期化します

7. Pipecatのパイプラインが稼働開始、Nova Sonicがリアルタイムで音声から音声への変換処理を行う

8. 音声応答が発信者側へ戻ってくる

ローカル開発を行うには、ngrok を使ってサーバーを公開してください：

ngrok http --domain=your-reserved-domain.ngrok.app 8000

Vonageの「Answer URL」を https://your-reserved-domain.ngrok.app/answer に設定してください。

本番環境では、Vonageの「Answer URL」をApp Runnerのドメインに設定してください（ このページ を参照してください）：

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

プログラムで電話を切る方法（ローカル開発環境）：

curl -X POST http://localhost:8000/hangup

本番環境へのデプロイ

このアプリは本番環境で2つのマネージドAWSサービスを利用しており、EC2、ECS、EKS、ALB、nginxは一切必要ありません。

生産アーキテクチャ

Vonage Voice 音声通話
  ↓ GET /answer
App Runner (answer/ — 公開 HTTPS エンドポイント、自動生成された URL)
  ↓ AgentCoreRuntimeClient.generate_presigned_url()
  ↓ 事前署名済みの AgentCore WSS URL を含む NCCO を返す
Vonage が AgentCore Runtime の /ws に直接接続
  ↓
AgentCore Runtime (runtime/ — ポート 8080)
  ↓ VonageFrameSerializer + Pipecat パイプライン
  ↓
Nova Sonic (音声から音声への変換)

ローカル開発環境と本番環境では何が異なるのか

変わらないもの： VonageFrameSerializer、Pipecatパイプライン、そしてNova Sonicは、どちらの環境でも同一である。

ステップ 1: 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_12 -rf requirements.txt
AWS_PROFILE=vonage-dev agentcore deploy -a your_agent_name
# → Copy Runtime ARN from output

ステップ 2: App Runner イメージのビルドとプッシュ

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

docker build --platform linux/amd64 -t vonage-agentcore-answer ./answer
docker tag vonage-agentcore-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

初回デプロイ時にApp Runnerサービスを作成する：詳細については README.md を参照して aws apprunner create-service JSONについてはこちらを参照してください。変更後は answer/ 変更後に再デプロイしてください：

aws apprunner start-deployment \
  --service-arn "arn:aws:apprunner:us-east-1:{account-id}:service/vonage-agentcore-answer/{service-id}" \
  --region us-east-1

ステップ 3: App Runner の環境変数を更新する

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

ステップ 4：Vonage の応答 URL を設定する

[ Vonageダッシュボードで、Voiceアプリケーションの「Answer URL」をApp Runnerのエンドポイントに更新してください：

https://{your-app-runner-url}.us-east-1.awsapprunner.com/answer

有効なNCCOが返されることをVerifyしてください：

curl "https://{service-id}.{region}.awsapprunner.com/answer"

App Runner IAMセットアップ

Lambda関数のURLに関する注意事項

このパターンのAWSリファレンス実装では、 /answer ハンドラーとして使用できます。AWSアカウントで lambda:InvokeFunctionUrl、Lambda の方がよりシンプルな代替手段となります。事前署名済み URL の生成ロジックは同じです。ここでは App Runner を使用しています。これは、Lambda のパブリック呼び出しを制限する組織レベルの SCP が設定されている場合を含め、あらゆる AWS アカウント構成で動作するためです。

AWSリソースの合計： AgentCore Runtime 1つ + App Runner サービス 1つ + ECR リポジトリ 1つ。

制作チェックリスト

• 実行環境： AgentCoreランタイムにはPython 3.12を使用してください。Nova Sonicは3.11ではエラーを出さずに失敗します。

• WebSocket: await websocket.accept() の最初の行として runtime/agent.py @app.websocket ハンドラーの最初の行として

• 冒頭の挨拶： 設定 BEDROCK_INITIAL_USER_MESSAGE Nova Sonic 532のタイムアウトを防ぐために設定する

• 事前署名済みURL： use AgentCoreRuntimeClient.generate_presigned_url()を使用し、生のboto3は使用しない invoke_agent_runtime presign

• IAM： 本番環境では、IAMロールを使用し、静的なAWSキーは絶対に使用しないでください

• 秘密： 保存 VONAGE_NUMBER および AGENTCORE_RUNTIME_ARN App Runnerの環境変数

• Vonageの回答URL： App Runner を指す必要があります /answer 本番稼働前に

• Verify: curl 以下の /answer エンドポイントを確認し、NCCOに wss://bedrock-agentcore... URIが含まれていることを確認してから、実際の通話をテストしてください

• セッションの動作： tune NOVA_SESSION_WARN_SECONDS および NOVA_SESSION_LIMIT_SECONDS 長期にわたる呼び出しの場合

その他のリソース

• Vonage Voice API ドキュメント

• Pipecat用 Vonage オーディオ・シリアライザー

• Pipecat 用 Vonage Audio Serializer のドキュメント

• AWSノヴァソニックのドキュメント

• AWS Bedrock AgentCoreのドキュメント

• GitHub上のソースコード

結論

Pipecat 向けの Vonage Audio Serializer および AWS Nova Sonic を使用して、音声通話用のリアルタイム AI エージェントをデプロイしました。このエージェントは、パブリックな App Runner Webhook エンドポイントを備え、完全に AWS Bedrock AgentCore Runtime 内で実行されています。

とともに 第1部 （Pipecat向けVonage Video Transport）と合わせると、Vonage上でAIエージェントを展開するための2つの相互補完的な方法が用意されることになります。