React から Python Agent への接続

Nx Plugin for AWS は、Python Agent を React ウェブサイトと迅速に統合するためのジェネレーターを提供します。これにより、AWS IAM および Cognito 認証のサポートを含む、型安全な OpenAPI 生成クライアントを介してエージェントに接続するために必要なすべての設定が行われます。

前提条件

このジェネレーターを使用する前に、以下を確認してください：

React ウェブサイト（ts#website ジェネレーターを使用して生成）
protocol=http を持つ Python Agent（py#agent ジェネレーターを使用して生成）
ts#website#auth ジェネレーターを介して追加された Cognito Auth

使用方法

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

変更されるファイルを確認するためにドライランを実行することもできます

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - connection
必須パラメータを入力
クリック Generate

React ウェブサイトをソースプロジェクトとして、Python Agent を含むプロジェクトをターゲットプロジェクトとして選択するよう求められます。ターゲットプロジェクトに複数のコンポーネント（複数のエージェントや他のコンポーネントタイプなど）が含まれている場合、曖昧さを解消するために targetComponent を指定するよう求められます。

オプション

パラメータ	型	デフォルト	説明
sourceProject 必須	string	-	ソースプロジェクト
targetProject 必須	string	-	接続先のターゲットプロジェクト
sourceComponent	string	-	接続元のソースコンポーネント (コンポーネント名、ソースプロジェクトルートからの相対パス、またはジェネレーター ID)。プロジェクトをソースとして明示的に選択するには '.' を使用します。
targetComponent	string	-	接続先のターゲットコンポーネント (コンポーネント名、ターゲットプロジェクトルートからの相対パス、またはジェネレーター ID)。プロジェクトをターゲットとして明示的に選択するには '.' を使用します。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

ジェネレーターは、Python Agent プロジェクトに以下を作成します：

Directoryscripts
- <agent_name>_openapi.py エージェントの FastAPI アプリから OpenAPI 仕様を生成するスクリプト
project.json 新しい <agent-name>-openapi ターゲットが追加されます

ジェネレーターは、React アプリケーションに以下の構造を作成します：

Directorysrc
- Directorycomponents
  - <AgentName>Provider.tsx OpenAPI クライアント用のプロバイダー
  - QueryClientProvider.tsx TanStack React Query クライアントプロバイダー
- Directoryhooks
  - useSigV4.tsx SigV4 でリクエストに署名するためのフック（IAM のみ）
  - use<AgentName>.tsx エージェントの API 用の TanStack Query オプションプロキシを返すフック
  - use<AgentName>Client.tsx バニラ API クライアントを返すフック
- Directorygenerated
  - Directory<agent-name>
    types.gen.ts エージェントの Pydantic モデルから生成された型
    client.gen.ts エージェントの API を呼び出すための型安全なクライアント
    options-proxy.gen.ts エージェントと対話するための TanStack Query フックオプション
project.json クライアント生成と変更の監視用のターゲットが追加されます
.gitignore 生成されたクライアントファイルはデフォルトで無視されます

仕組み

OpenAPI クライアント生成

ビルド時に、Python Agent の FastAPI アプリが内省され、OpenAPI 仕様が生成されます。この仕様は、React から FastAPI への接続と同じパターンに従って、TanStack Query フックを持つ型安全な TypeScript クライアントを生成するために使用されます。

各エージェントは独自のスコープ付き OpenAPI スクリプト（例：scripts/agent_openapi.py）を取得するため、複数のエージェントを持つプロジェクトは個別の仕様を生成できます。

ランタイム設定

この接続ジェネレーターを実行すると、エージェントの生成された CDK/Terraform コンストラクトにパッチが適用され、その AgentCore ランタイム ARN がウェブサイトの runtime-config.json（connection 名前空間の下）に公開されるため、明示的に接続したエージェントのみがフロントエンドに公開されます。詳細については、ランタイム設定を参照してください。

認証

生成されたコードは、エージェントの設定に応じて認証を処理します：

IAM（デフォルト）：AWS SigV4 を使用して HTTP リクエストに署名します。認証情報は、ウェブサイトの認証で設定された Cognito Identity Pool から取得されます
Cognito：JWT アクセストークンを Authorization ヘッダーに埋め込みます
None：認証なし

インフラストラクチャ

エージェントが IAM 認証を使用する場合、Cognito Identity Pool の認証済みロールにエージェントを呼び出す権限を付与する必要があります。

CDK
Terraform

const identity = new UserIdentity(this, 'Identity');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the authenticated Cognito role permission to invoke the agent
myAgent.grantInvokeAccess(identity.identityPool.authenticatedRole);

grantInvokeAccess は、エージェントのランタイム ARN 上のすべての AgentCore 呼び出しアクション（InvokeAgentRuntime、InvokeAgentRuntimeWithWebSocketStream）を接続します。

module "identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

# Grant the authenticated Cognito role permission to invoke the agent
resource "aws_iam_policy" "invoke_my_agent" {
  name = "InvokeMyAgentPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }]
  })
}

resource "aws_iam_role_policy_attachment" "invoke_my_agent" {
  role       = module.identity.authenticated_role_name
  policy_arn = aws_iam_policy.invoke_my_agent.arn
}

エージェントが Cognito 認証を使用する場合、ウェブサイトをエージェントに接続するための追加のインフラストラクチャを定義する必要はありません。

生成されたコードの使用

API フックの使用

use<AgentName> フックは、エージェントの API エンドポイントを呼び出すための TanStack Query オプションを提供します：

import { useState } from 'react';
import { useMutation } from '@tanstack/react-query';
import { useMyAgent } from '../hooks/useMyAgent';
import type { StreamChunk } from '../generated/my-agent/types.gen';

function ChatComponent() {
  const api = useMyAgent();
  const [chunks, setChunks] = useState<StreamChunk[]>([]);

  const invoke = useMutation(api.invoke.mutationOptions({
    onSuccess: async (stream) => {
      setChunks([]);
      for await (const chunk of stream) {
        setChunks((prev) => [...prev, chunk]);
      }
    },
  }));

  const handleSend = (prompt: string) => {
    invoke.mutate({ prompt });
  };

  return (
    <div>
      <button onClick={() => handleSend('Hello!')}>Send</button>
      {invoke.isPending && <p>Agent is thinking...</p>}
      {chunks.map((chunk, i) => (
        <span key={i}>{chunk.content}</span>
      ))}
    </div>
  );
}

バニラクライアントの使用

use<AgentName>Client フックは、API クライアントへの直接アクセスを提供します：

import { useState } from 'react';
import { useMyAgentClient } from '../hooks/useMyAgentClient';
import type { StreamChunk } from '../generated/my-agent/types.gen';

function ChatComponent() {
  const client = useMyAgentClient();
  const [chunks, setChunks] = useState<StreamChunk[]>([]);

  const handleSend = async (prompt: string) => {
    setChunks([]);
    for await (const chunk of client.invoke({ prompt })) {
      setChunks((prev) => [...prev, chunk]);
    }
  };

  return (
    <div>
      <button onClick={() => handleSend('Hello!')}>Send</button>
      {chunks.map((chunk, i) => (
        <span key={i}>{chunk.content}</span>
      ))}
    </div>
  );
}

ローカル開発

接続ジェネレーターは自動的に dev 統合を設定します：

nx dev <website> を実行すると、エージェントのローカル FastAPI サーバーも起動します
ランタイム設定は、ローカル HTTP URL（例：http://localhost:8081/）を指すようにオーバーライドされます
エージェントの API が変更されると、TypeScript クライアントが自動的に再生成されます

pnpm nx dev <WebsiteProject>

yarn nx dev <WebsiteProject>

npx nx dev <WebsiteProject>

bunx nx dev <WebsiteProject>

詳細情報

詳細については、以下を参照してください：