Build chat experiences with AG-UI and CopilotKit

{{ community_contribution_banner }}

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:

1. Agent name: Press Enter to use the inferred name main, or provide your own
2. Dependency file: Enter pyproject.toml
3. Deployment type: Enter 2 for Container
4. Execution role: Press Enter to auto-create
5. ECR Repository: Press Enter to auto-create
6. OAuth authorizer: Enter yes
7. OAuth discovery URL: Paste the Discovery URL from the previous step
8. OAuth client IDs: Paste the Client ID from the previous step
9. OAuth audience/scopes/claims: Press Enter to skip
10. Request header allowlist: Enter no
11. 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:

• Agentic Generative UI
• Frontend Actions

Or try them out in the AG-UI Dojo.