AgentCore AG-UI Starter

A small, inspectable reference project for streaming a Python agent from Amazon Bedrock AgentCore into a Next.js chat UI—with live text, tool calls, and results carried over AG-UI.

This repository is intentionally focused on one end-to-end path. It is useful for learning the boundaries between an agent framework, managed runtime, event protocol, server bridge, and browser UI without hiding them behind a large application.

A Strands agent streaming model output and tool activity into the Next.js interface over AG-UI.

What it demonstrates

• A Strands Agents SDK agent backed by Amazon Bedrock
• An Amazon Bedrock AgentCore Runtime entrypoint
• AG-UI server-sent events for tokens, tool-call arguments, and tool results
• A server-side CopilotKit runtime inside a Next.js App Router route
• A CopilotKit chat client that renders the streamed conversation
• A deterministic add_numbers tool that makes the tool lifecycle easy to observe
• Local development first, with the same agent structured for AgentCore deployment

Architecture

flowchart LR
    Browser["Browser · CopilotKit chat"]
    Route["Next.js · /api/copilotkit"]
    Runtime["CopilotKit Runtime · HttpAgent"]
    AgentCore["AgentCore Runtime · /invocations"]
    Strands["Strands Agent · tools"]
    Bedrock["Amazon Bedrock · Claude"]

    Browser -->|"messages"| Route
    Route --> Runtime
    Runtime -->|"AG-UI request"| AgentCore
    AgentCore --> Strands
    Strands --> Bedrock
    Strands -.->|"tool call + result"| AgentCore
    AgentCore -->|"SSE · AG-UI events"| Runtime
    Runtime -->|"stream"| Browser

The browser never receives AWS credentials. It talks to the Next.js server route, which bridges the active AG-UI thread to the agent endpoint.

Stack

Layer	Technology	Responsibility
Agent	Python, Strands Agents SDK	Model loop and tools
Model	Amazon Bedrock	Claude inference
Runtime	Amazon Bedrock AgentCore	Agent process and invocation endpoint
Protocol	AG-UI over SSE	Typed streaming events
Server bridge	CopilotKit Runtime, HttpAgent	Connects Next.js to the AG-UI endpoint
Web UI	Next.js, React, CopilotKit	Chat and streamed event rendering

Prerequisites

• An AWS account with Bedrock model access
• AWS credentials available to the CLI (aws sts get-caller-identity should succeed)
• The AgentCore CLI
• uv and Python 3.12+
• Node.js 20.9+; Node.js 22 is recommended

The default model is global.anthropic.claude-sonnet-4-5-20250929-v1:0. Override it with BEDROCK_MODEL_ID if your account uses another Bedrock model or inference profile.

Run locally

1. Clone and configure the AWS target

git clone https://github.com/fahmidme/agentcore-agui-starter.git
cd agentcore-agui-starter
cp agentcore/aws-targets.example.json agentcore/aws-targets.json

Edit agentcore/aws-targets.json with your AWS account ID and preferred region. This file is intentionally ignored by Git.

2. Install the agent dependencies

cd app/StreamingAssistant
uv sync
cd ../..

3. Start AgentCore locally

agentcore dev \
  --runtime StreamingAssistant \
  --skip-deploy \
  --logs \
  --no-traces \
  --port 8081

The AG-UI endpoint is now available at http://127.0.0.1:8081/invocations.

4. Start the web app

In a second terminal:

cd web
cp .env.example .env.local
npm ci
npm run dev -- --port 3001

Open http://localhost:3001 and try:

What is 25 plus 17?

You should see the assistant stream its response while the AG-UI event sequence includes TOOL_CALL_START, argument deltas, the result, and text-message deltas.

Why the agent remembers the current conversation

This starter does not configure AgentCore Memory or a database. The apparent memory comes from the active AG-UI thread:

1. CopilotKit keeps the current thread's messages in client state.
2. Each run sends the accumulated messages array through the Next.js runtime.
3. The Strands agent receives that history as context for the next model call.

That is short-lived conversation context, not durable memory. A new thread, cleared browser state, or a client without the earlier messages starts fresh. AgentCore Memory is the next layer for durable cross-session recall and retrieval.

Project structure

.
├── agentcore/
│   ├── agentcore.json             # AgentCore project and runtime definition
│   └── aws-targets.example.json   # Safe deployment-target template
├── app/StreamingAssistant/
│   ├── main.py                    # Strands agent and AG-UI app
│   ├── model/load.py              # Bedrock model configuration
│   └── pyproject.toml
└── web/
    ├── app/api/copilotkit/        # Server-side CopilotKit bridge
    └── app/page.tsx               # Chat UI

Generated CDK output, CLI deployment state, dependencies, caches, AWS targets, and environment files are excluded from Git.

Deploying the runtime

After local testing:

agentcore deploy --runtime StreamingAssistant

Deployment creates or updates AWS resources and may incur charges. A production web connection also needs an intentional authentication and authorization design; do not expose a privileged runtime invocation path directly to an untrusted browser.

Roadmap

• AgentCore Memory for durable recall
• AgentCore Identity and authenticated application users
• Gateway-managed tools and external integrations
• CloudWatch traces and production observability
• Human approval flows and richer AG-UI tool rendering

These items are directions for the project, not capabilities claimed by the current starter.

Security

Never commit AWS credentials, .env.local, agentcore/aws-targets.json, or agentcore/.cli/deployed-state.json. See SECURITY.md for vulnerability reporting and deployment guidance.

Contributing

Small, focused improvements are welcome. Read CONTRIBUTING.md before opening a pull request.

License

Released under the MIT License.