Build chat experiences with AG-UI and CopilotKit¶

Community Contribution

This is a community-maintained package that is not owned or supported by the Strands team. Validate and review the package before using it in your project.

Have your own integration? We'd love to add it here too!

As an agent builder, you want users to interact with your agents through a rich and responsive interface. Building UIs from scratch requires a lot of effort, especially to support streaming events and client state. That's exactly what AG-UI was designed for - rich user experiences directly connected to an agent.

AG-UI provides a consistent interface to empower rich clients across technology stacks, from mobile to the web and even the command line. There are a number of different clients that support AG-UI:

CopilotKit provides tooling and components to tightly integrate your agent with web applications
Clients for Kotlin, Java, Go, and CLI implementations in TypeScript

This tutorial uses CopilotKit to create a sample app backed by a Strands agent that demonstrates some of the features supported by AG-UI.

Quickstart¶

To get started, let's create a sample application with a Strands agent and a simple web client:

npx copilotkit create -f aws-strands-py

Chat¶

Chat is a familiar interface for exposing your agent, and AG-UI handles streaming messages between your users and agents:

src/app/page.tsx

const labels = {
    title: "Popup Assistant",
    initial: "Hi, there! You\'re chatting with an agent. This agent comes with a few tools to get you started."
  }
<CopilotSidebar
  clickOutsideToClose={false}
  defaultOpen={true}
  labels={labels}
/>

Learn more about the chat UI in the CopilotKit docs.

Tool Based Generative UI (Rendering Tools)¶

AG-UI lets you share tool information with a Generative UI so that it can be displayed to users:

src/app/page.tsx

useCopilotAction({
  name: "get_weather",
  description: "Get the weather for a given location.",
  available: "disabled",
  parameters: [
    { name: "location", type: "string", required: true },
  ],
  render: ({ args }) => {
    return <WeatherCard location={args.location} themeColor={themeColor} />
  },
});

Learn more about the Tool-based Generative UI in the CopilotKit docs.

Shared State¶

Strands agents are stateful, and synchronizing that state between your agents and your UIs enables powerful and fluid user experiences. State can be synchronized both ways so agents are automatically aware of changes made by your user or other parts of your application:

const { state, setState } = useCoAgent<AgentState>({
  name: "my_agent",
  initialState: {
    proverbs: [
      "CopilotKit may be new, but its the best thing since sliced bread.",
    ],
  },
})

Learn more about shared state in the CopilotKit docs.

Try it out!¶

npm install && npm run dev

Deploy to AgentCore¶

Once you've built your agent with AG-UI, you can deploy it to AWS Bedrock AgentCore for production use. Install the bedrock-agentcore CLI tool to get started.

Note

This guide is adapted for AG-UI. For general AgentCore deployment documentation, see Deploy to Bedrock AgentCore.

Setup Authentication¶

First, configure Cognito for authentication:

agentcore identity setup-cognito

This creates a Cognito user pool and outputs:

Pool ID
Client ID
Discovery URL

Follow the instructions for loading the environment variables:

export $(grep -v '^#' .agentcore_identity_user.env | xargs)

Configure Your Agent¶

Navigate to your agent directory and run:

cd agent
agentcore configure -e main.py

Respond to the prompts:

Agent name: Press Enter to use the inferred name main, or provide your own
Dependency file: Enter pyproject.toml
Deployment type: Enter 2 for Container
Execution role: Press Enter to auto-create
ECR Repository: Press Enter to auto-create
OAuth authorizer: Enter yes
OAuth discovery URL: Paste the Discovery URL from the previous step
OAuth client IDs: Paste the Client ID from the previous step
OAuth audience/scopes/claims: Press Enter to skip
Request header allowlist: Enter no
Memory configuration: Enter s to skip

Launch Your Agent¶

Deploy your agent with the required environment variables. AgentCore Runtime requires:

POST /invocations - Agent interaction endpoint (configured via AGENT_PATH)
GET /ping - Health check endpoint (created automatically by AG-UI)

agentcore launch --env AGENT_PORT=8080 --env AGENT_PATH=/invocations --env OPENAI_API_KEY=<your-api-key>

Your agent is now deployed and accessible through AgentCore!

Connect Your Frontend¶

Return to the root directory and configure the environment variables to connect your UI to the deployed agent:

cd ..
export STRANDS_AGENT_URL="https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/{runtime-id}/invocations?accountId={account-id}&qualifier=DEFAULT"
export STRANDS_AGENT_BEARER_TOKEN=$(agentcore identity get-cognito-inbound-token)

Replace {runtime-id} and {account-id} with your actual values from the AgentCore deployment output.

Start the UI:

npm run dev:ui

Resources¶

To see what other features you can build into your UI with AG-UI, refer to the CopilotKit docs:

Or try them out in the AG-UI Dojo.