React から AG-UI エージェントへ

Nx Plugin for AWSは、AG-UIプロトコルを公開するStrands AgentにReactウェブサイトを接続するためのジェネレーターを提供します。このジェネレーターは、AWS IAMとCognito認証をサポートし、ウェブサイト上でCopilotKitと@ag-ui/client HttpAgentを配線します。

TypeScript Strands Agents

AG-UIはまだTypeScript Strands Agentsではサポートされていません。最新の状況についてはstrands-agents/sdk-typescript#347を参照してください。現時点では、protocol=AG-UIを指定してpy#strands-agentジェネレーターを使用してください。

前提条件

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

1. Reactウェブサイト(ts#react-websiteジェネレーターを使用して生成)
2. protocol=AG-UIを指定したPython Strands Agent(py#strands-agentジェネレーターを使用して生成)
3. デプロイされたエージェントの場合、ts#react-website-authジェネレーターを介して追加されたCognito Auth

使用方法

ジェネレーターの実行

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

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

yarn

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

npm

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

bun

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

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

オプション

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

ジェネレーターの出力

ジェネレーターは、単一の共有AguiProviderコンポーネントと、接続されたエージェントごとに1つのフックを作成します:

• Directorysrc

  • Directorycomponents

    • AguiProvider.tsx すべてのAG-UIエージェント用の単一のCopilotKitProvider。最初のconnection実行時に作成され、その後の実行で各新しいエージェントを登録するために更新されます。
  • Directoryhooks

    • useAgui<AgentName>.tsx 1つのAG-UIエージェントを登録します。connectionの実行ごとに1つのファイル。
    • useSigV4.tsx SigV4署名(IAMのみ)

別のエージェントに対してconnectionを2回目に実行すると、新しいuseAgui<AgentName>.tsxフックが追加され、AguiProvider.tsxが両方のフックを登録するように更新されます — プロバイダーに加えたカスタム編集は保持されます。main.tsxは単一の<AguiProvider>ラッパーを保持します — ネストされたプロバイダーになることはありません。

以下の依存関係がルートのpackage.jsonに追加されます:

• @copilotkit/react-core — CopilotKitProviderとチャットコンポーネント(CopilotChat、CopilotSidebar、CopilotPopup)を提供
• @ag-ui/client — 生成されたフックで使用されるHttpAgent
• aws4fetch、oidc-client-ts、react-oidc-context、@aws-sdk/credential-providers — IAM認証のみ
• react-oidc-context — Cognito認証

仕組み

AG-UI接続

各useAgui<AgentName>フックは、ランタイム設定からエージェントのランタイム値を読み取り、@ag-ui/client HttpAgentをインスタンス化します:

• デプロイ済み: ランタイム値はBedrock AgentCore Runtime ARNであり、AgentCore HTTPSエンドポイントに変換されます: https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/invocations?qualifier=DEFAULT
• ローカル開発: serve-localは値をエージェントのローカルURL(例: http://localhost:8081)にオーバーライドします

共有AguiProviderは、生成されたすべてのフックを呼び出し、それぞれを単一のCopilotKitProvider上のselfManagedAgentsにスプレッドし、それらすべてをCopilotKitコンポーネントに公開します。

CopilotKit統合

CopilotKitは、AG-UIプロトコルのファーストパーティリファレンスReactクライアントであり、すぐに使えるチャットコンポーネントを提供します:

• <CopilotChat /> — フルチャットインターフェース
• <CopilotSidebar /> — 固定サイドパネルチャット
• <CopilotPopup /> — フローティングチャットポップアップ

これらのいずれかを<AguiProvider>ラッパー内の任意の場所に配置してください(すでにmain.tsxに配線されています)。

認証

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

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

インフラストラクチャ

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

CDK

packages/infra/src/stacks/application-stack.ts

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）を設定します。

Terraform

packages/infra/src/main.tf

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

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

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

生成されたコードの使用

チャットインターフェースの追加

agentIdを指定してCopilotKitコンポーネントをインスタンス化し、使用するエージェントを選択します。idはエージェントの名前です — py#strands-agentジェネレーターを実行したときに選択したものと同じです — また、生成されたフックファイル(例: packages/web/src/hooks/useAgui<AgentName>.tsxから返されるキー)でも確認できます:

import { CopilotChat } from '@copilotkit/react-core/v2';

function ChatPage() {
  return (
    <CopilotChat
      agentId="agent"
      labels={{
        welcomeMessageText: 'How can I help you today?',
        chatInputPlaceholder: 'Ask me anything...',
      }}
    />
  );
}

複数のAG-UIエージェントの接続

エージェントごとにconnectionジェネレーターを1回実行します。共有AguiProviderを介して登録されたすべてのエージェントは、アプリ内のどこからでも見えます — 異なるagentIdでCopilotKitコンポーネントをインスタンス化して、各チャットを目的のエージェントにルーティングします:

<CopilotChat agentId="story" />    {/* talks to StoryAgent */}
<CopilotChat agentId="research" /> {/* talks to ResearchAgent */}

ルック&フィールのカスタマイズ

<CopilotChat />(および<CopilotSidebar />、<CopilotPopup />)は再帰的なスロットシステムを使用しています — Tailwindクラス文字列、propオブジェクト、またはカスタムReactコンポーネントのいずれかで任意のサブコンポーネントをオーバーライドできます。完全なスロットツリーについては、CopilotKitスロットガイドを参照してください。

スロットによるTailwindスタイリング

<CopilotChat
  agentId="agent"
  // style the input and its children
  input={{
    textArea: 'text-blue-600',
    sendButton: 'bg-blue-600 hover:bg-blue-700',
  }}
  // style nested message slots
  messageView={{
    assistantMessage: 'bg-blue-50 rounded-xl p-2',
    userMessage: 'bg-blue-100 rounded-xl',
  }}
/>

カスタムコンポーネントでスロットを置き換える

任意のスロットはclassNameの代わりにReactコンポーネントを受け取ることができるため、デフォルトを完全に置き換えることができます:

import { CopilotChat } from '@copilotkit/react-core/v2';

const MySendButton: React.FC<{ onClick: () => void }> = ({ onClick }) => (
  <button onClick={onClick} className="my-send-btn">
    ✨ Send
  </button>
);

<CopilotChat
  agentId="agent"
  input={{ sendButton: MySendButton }}
/>;

より深いオーバーライドも同じ形式に従います — 例えば、アシスタントメッセージのコピーボタンだけを置き換える:

<CopilotChat
  agentId="agent"
  messageView={{
    assistantMessage: {
      copyButton: ({ onClick }) => <button onClick={onClick}>Copy</button>,
    },
  }}
/>

ローカル開発

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

1. nx serve-local <website>を実行すると、エージェントのローカルサーバーも起動します
2. ランタイム設定がローカルAG-UI URL(例: http://localhost:8081)を指すようにオーバーライドされます
3. ウェブサイトとエージェントの両方が一緒にホットリロードされます

pnpm

pnpm nx serve-local <WebsiteProject>

yarn

yarn nx serve-local <WebsiteProject>

npm

npx nx serve-local <WebsiteProject>

bun

bunx nx serve-local <WebsiteProject>

ホットリロード

ウェブサイトと接続されたエージェントが一緒にホットリロードされるため、AWSにデプロイすることなく両側を素早く反復できます。

詳細情報

• Python Strands Agentガイド
• React to Python Strands Agent (HTTP)ガイド
• AG-UI Protocol Documentation
• CopilotKit + AWS Strands Documentation
• CopilotKit Custom Look & Feel
• Bedrock AgentCore Runtime