React to AG-UI Agent

Nx Plugin for AWS provides a generator to connect a React website to a Strands Agent that exposes the AG-UI protocol. It wires up CopilotKit with an @ag-ui/client HttpAgent on your website, with AWS IAM and Cognito authentication support.

TypeScript Strands Agents

AG-UI is not yet supported for TypeScript Strands Agents. See strands-agents/sdk-typescript#347 for the latest status. For now, use the py#strands-agent generator with protocol=AG-UI.

Prerequisites

Before using this generator, ensure you have:

1. A React website (generated using the ts#react-website generator)
2. A Python Strands Agent with protocol=AG-UI (generated using the py#strands-agent generator)
3. For deployed agents, Cognito Auth added via the ts#react-website-auth generator

Usage

Run the Generator

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - connection
5. Fill in the required parameters
6. Click 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

You can also perform a dry-run to see what files would be changed

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

You will be prompted to select your React website as the source project and the project containing your AG-UI Strands Agent as the target project. If your target project contains multiple components (such as multiple agents or other component types), you will be prompted to specify a targetComponent to disambiguate.

Options

Parameter	Type	Default	Description
sourceProject Required	string	-	The source project
targetProject Required	string	-	The target project to connect to
sourceComponent	string	-	The source component to connect from (component name, path relative to source project root, or generator id). Use '.' to explicitly select the project as the source.
targetComponent	string	-	The target component to connect to (component name, path relative to target project root, or generator id). Use '.' to explicitly select the project as the target.

Generator Output

The generator creates a single shared AguiProvider component, one hook per connected agent, and a themed wrapper for the CopilotKit chat components:

• Directorysrc

  • Directorycomponents

    • AguiProvider.tsx Single CopilotKitProvider for every AG-UI agent. Created on the first connection run and updated on subsequent runs to register each new agent.
    • Directorycopilot

      • index.tsx Re-exports CopilotChat, CopilotSidebar and CopilotPopup with slot defaults that match your website’s uxProvider (Cloudscape, Shadcn, or no theme at all).
      • ThemeComponents .tsx Per-slot theme components (e.g. CloudscapeAssistantMessage.tsx, ShadcnChatInput.tsx). Only vended when uxProvider is Cloudscape or Shadcn.
  • Directoryhooks

    • useAgui<AgentName>.tsx Registers one AG-UI agent. One file per connection run.
    • useSigV4.tsx SigV4 signing (IAM only)

Running connection a second time for a different agent adds a new useAgui<AgentName>.tsx hook and updates AguiProvider.tsx to register both hooks — any custom edits you’ve made to the provider are preserved. main.tsx keeps its single <AguiProvider> wrapper — you never end up with nested providers.

The following dependencies are added to the root package.json:

• @copilotkit/react-core — ships CopilotKitProvider and chat components (CopilotChat, CopilotSidebar, CopilotPopup)
• @ag-ui/client — HttpAgent used by the generated hooks
• aws4fetch, oidc-client-ts, react-oidc-context, @aws-sdk/credential-providers — IAM auth only
• react-oidc-context — Cognito auth

How It Works

AG-UI Connection

Each useAgui<AgentName> hook reads its agent’s runtime value from Runtime Configuration and instantiates an @ag-ui/client HttpAgent:

• Deployed: the runtime value is a Bedrock AgentCore Runtime ARN, which is converted to the AgentCore HTTPS endpoint: https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/invocations?qualifier=DEFAULT
• Local development: serve-local overrides the value to the agent’s local URL (e.g. http://localhost:8081)

The shared AguiProvider calls every generated hook and spreads each one into selfManagedAgents on a single CopilotKitProvider, which exposes them all to CopilotKit components.

CopilotKit Integration

CopilotKit is the 1st-party reference React client for the AG-UI protocol and ships ready-made chat components:

• <CopilotChat /> — full chat interface
• <CopilotSidebar /> — fixed side panel chat
• <CopilotPopup /> — floating chat popup

Place any of these anywhere inside the <AguiProvider> wrapper (already wired into main.tsx for you).

Authentication

The generated code handles authentication depending on your agent’s configuration:

• IAM (default): uses AWS SigV4-signed HTTP requests. Credentials are obtained from the Cognito Identity Pool configured with your website’s auth.
• Cognito: embeds the JWT access token in the Authorization header as a Bearer token.

Infrastructure

If your agent uses IAM auth, the Cognito Identity Pool’s authenticated role must be granted permission to invoke the agent.

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 wires up all AgentCore invoke actions (InvokeAgentRuntime, InvokeAgentRuntimeWithWebSocketStream) on the agent’s runtime ARN.

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"

  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
}

If your agent uses Cognito auth, you do not need to define any additional infrastructure to connect your website to your agent.

Using the Generated Code

Adding a Chat Interface

Instantiate CopilotKit components with agentId to select which agent to use. The id is the agent’s name — the same one you chose when you ran the py#strands-agent generator — and you can also find it in the generated hook file (e.g. the key returned from packages/web/src/hooks/useAgui<AgentName>.tsx).

Import the chat components from the generated ./components/copilot module so the theme that matches your website’s uxProvider is applied automatically:

import { CopilotChat } from './components/copilot';

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

Connecting Multiple AG-UI Agents

Run the connection generator once per agent. Every agent registered via the shared AguiProvider is visible from anywhere in the app — instantiate a CopilotKit component with a different agentId to route each chat to the agent you want:

import { CopilotChat } from './components/copilot';

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

Customising the Look and Feel

<CopilotChat /> (and <CopilotSidebar />, <CopilotPopup />) use a recursive slot system — you can override any sub-component with either a Tailwind class string, a prop object, or a custom React component. See the CopilotKit slots guide for the full slot tree.

Built-in Themes

The generator reads metadata.uxProvider from your React website project and vends a themed wrapper module at src/components/copilot/index.tsx so the chat components match the rest of your UI without any extra configuration:

uxProvider	Styling applied to CopilotChat / CopilotSidebar / CopilotPopup
Cloudscape	Messages render inside Cloudscape ChatBubbles with gen-AI Avatars (matching the Cloudscape generative AI chat pattern); the typing indicator becomes a LoadingBar and the input is a PromptInput. Built from @cloudscape-design/components and @cloudscape-design/chat-components.
Shadcn	Assistant messages render in a bg-muted bubble with a Sparkles avatar; user messages render right-aligned in a bg-primary bubble with a User avatar. The input is a rounded Textarea + pill-shaped send/stop Button (Enter submits, Shift+Enter newlines). Uses shadcn primitives from the shared common-shadcn package.
None (or anything else)	No theme — the module just re-exports the default CopilotKit components.

Import the themed components from the local theme module (not @copilotkit/react-core/v2 directly) so the theme is applied automatically:

import { CopilotChat } from './components/copilot';

<CopilotChat agentId="agent" />

The theme is applied as slot defaults, so any slot you explicitly pass still wins — you keep full control whenever you need a one-off override.

Customising the Theme

The generated theme lives entirely inside your project:

• src/components/copilot/index.tsx — exports the themed CopilotChat / CopilotSidebar / CopilotPopup and the cloudscapeCopilotTheme / shadcnCopilotTheme objects. Edit this file to change the default slot wiring for every chat in your app.
• src/components/copilot/<ThemeComponent>.tsx — per-slot theme components (e.g. CloudscapeAssistantMessage, ShadcnChatInput). Edit these to tweak the look of a single slot without re-wiring the theme.

For example, to drop in your own user-message renderer while keeping the rest of the theme, edit the relevant file in src/components/copilot/ and re-export it from index.tsx.

Tailwind styling via slots

Per-chat overrides still work alongside the theme — anything you pass as a slot prop overrides the themed default:

<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',
  }}
/>

Replacing a slot with a custom component

Any slot can take a React component instead of a className, so you can replace the default entirely:

import { CopilotChat } from './components/copilot';

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

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

Deeper overrides follow the same shape — e.g. replace just the copy button on assistant messages:

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

Local Development

The connection generator automatically configures serve-local integration:

1. Running nx serve-local <website> will also start the agent’s local server
2. The runtime config is overridden to point to the local AG-UI URL (e.g. http://localhost:8081)
3. Both the website and the agent hot-reload together

pnpm

pnpm nx serve-local <WebsiteProject>

yarn

yarn nx serve-local <WebsiteProject>

npm

npx nx serve-local <WebsiteProject>

bun

bunx nx serve-local <WebsiteProject>

Hot Reloading

The website and connected agent hot-reload together, enabling you to quickly iterate on both sides without deploying to AWS.

More Information

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