React から Python Strands Agent への接続

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

前提条件

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

Reactウェブサイト(ts#react-website ジェネレーターを使用して生成)
Python Strands Agent(py#strands-agent ジェネレーターを使用して生成)
ts#react-website-auth ジェネレーター経由で追加されたCognito Auth

使用方法

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

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

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

オプション

パラメータ	型	デフォルト	説明
sourceProject 必須	string	-	ソースプロジェクト
targetProject 必須	string	-	接続先のターゲットプロジェクト
sourceComponent	string	-	接続元のソースコンポーネント (コンポーネント名、ソースプロジェクトルートからの相対パス、またはジェネレーター ID)。プロジェクトをソースとして明示的に選択するには '.' を使用します。
targetComponent	string	-	接続先のターゲットコンポーネント (コンポーネント名、ターゲットプロジェクトルートからの相対パス、またはジェネレーター ID)。プロジェクトをターゲットとして明示的に選択するには '.' を使用します。

ジェネレーターの出力

ジェネレーターは、Python Strands 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 Strands AgentのFastAPIアプリがイントロスペクションされ、OpenAPI仕様が生成されます。この仕様は、React to FastAPI接続と同じパターンに従って、TanStack Queryフックを備えた型安全なTypeScriptクライアントを生成するために使用されます。

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

認証

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

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

生成されたコードの使用

API Hookの使用

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 = (message: string) => {
    invoke.mutate({
      prompt: message,
      sessionId: 'my-session',
    });
  };

  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 (message: string) => {
    setChunks([]);
    for await (const chunk of client.invoke({
      prompt: message,
      sessionId: 'my-session',
    })) {
      setChunks((prev) => [...prev, chunk]);
    }
  };

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

ローカル開発

接続ジェネレーターは自動的にserve-local統合を設定します:

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

pnpm nx serve-local <WebsiteProject>

yarn nx serve-local <WebsiteProject>

npx nx serve-local <WebsiteProject>

bunx nx serve-local <WebsiteProject>

インフラストラクチャ

エージェントがIAM認証を使用する場合、Cognito Identity Poolの認証済みロールにエージェントを呼び出す権限を付与する必要があります。適切なgrantInvokeAccessメソッドについては、エージェントのインフラストラクチャコンストラクトを参照してください。

詳細情報

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