Building Real-Time AI Agent Interfaces with AG-UI and Amazon Bedrock AgentCore
Building Real-Time AI Agent Interfaces with AG-UI and Amazon Bedrock AgentCore while streaming every reasoning step, tool call, and state change from your AI agent to the user's browser.
Chinmayi Narasimhadevara and Sunita Koppar
AWS
AWS
The Black Box Problem
Alex, a support engineer, asks an AI agent: "Check the warehouse for low stock items, calculate restock costs, and send me a Slack alert." A spinner appears. Fifteen seconds pass. Then a wall of text drops into the chat. Alex has no idea what happened — did the agent check the right warehouse? Did it actually calculate costs or estimate them? Was it stuck for ten seconds or working the whole time?
This is the reality of most agent-powered applications today. Agents do complex, multi-step work — reasoning, calling tools, processing results, reasoning again — but users see none of it. They get a loading spinner and a final answer. When something goes wrong, there's no visibility into where it failed.
AG-UI (Agent-User Interaction Protocol) solves this by defining a standardized protocol for streaming every step of agent execution to the frontend in real time. Combined with Amazon Bedrock AgentCore Runtime for managed agent infrastructure, you get full transparency into agent behavior
Why This Matters
Alex used to submit requests and wait, never knowing if the agent was stuck or working. Now she watches it think — "Analyzing request... Calling get_inventory... Found 2 low stock items... Calling calculator... Restock cost: $4,418... Sending Slack alert... Alert sent" — all streaming in real time. When a tool returns unexpected results, she sees it immediately.
Her manager David used to get escalations when agents produced incorrect answers. Now his team can see exactly which tool was called, with what arguments, and what it returned. Debugging dropped from hours to seconds.
The deepest value comes from shifting agents from "black boxes that produce answers" to "transparent systems you can watch, debug, and trust."
Architecture
Alex's question flows through a chain of managed AWS services. The numbered steps below match the numbered arrows in the diagram:
- User loads the web app via Amazon CloudFront — The user’s browser requests GET / from Amazon CloudFront, the CDN that acts as the single public entry point and edge cache for both static content and API traffic.
- CloudFront serves static assets from Amazon S3 (OAC / SigV4) — CloudFront fetches the single-page HTML frontend from a private Amazon S3 bucket using Origin Access Control (OAC), which signs the origin request with SigV4 so the bucket stays private and is never exposed publicly.
- User opens the AG-UI WebSocket connection via Amazon API Gateway — The frontend opens a WebSocket (WSS) connection through an Amazon API Gateway WebSocket API so AG-UI events can stream back to the browser in real time — all on the same CloudFront domain, so there are no CORS issues.
- API Gateway invokes the AWS Lambda handler — API Gateway routes each incoming message and invokes an AWS Lambda function, a serverless proxy with no servers to manage.
- Lambda calls AgentCore Runtime (InvokeAgentRuntime) — The browser can’t call AgentCore directly because it requires IAM SigV4 signing, so the Lambda proxy signs the request and calls Amazon Bedrock AgentCore Runtime via InvokeAgentRuntime, passing through the AG-UI event stream. This is about 40 lines of Python, deployed inline.
- FastAPI routes the request to the Strands Agent on AgentCore Runtime — Amazon Bedrock AgentCore Runtime runs the agent container (built by AWS CodeBuild and stored in Amazon ECR — no local Docker needed). Inside it, a FastAPI server hands the request to a Strands agent with seven tools (search, calculator, inventory, trends, customer lookup, report generation, alerts), emitting AG-UI events at each step — TOOL_CALL_START when a tool is invoked, TOOL_CALL_ARGS with streaming arguments, TOOL_CALL_RESULT with what came back.
- Agent streams responses from Amazon Bedrock (ConverseStream) — The agent calls Amazon Bedrock (Claude) through the ConverseStream API, and the streamed response flows back along the same path to the browser token by token.
The AG-UI Protocol
AG-UI defines 16 event types organized into three streaming patterns.
Start-Content-End — Text messages stream token by token: TEXT_MESSAGE_START → TEXT_MESSAGE_CONTENT (repeated) → TEXT_MESSAGE_END. Tool calls follow the same pattern: TOOL_CALL_START → TOOL_CALL_ARGS → TOOL_CALL_END → TOOL_CALL_RESULT. The frontend accumulates deltas to build content progressively.
Snapshot-Delta — STATE_SNAPSHOT sends complete agent state initially. STATE_DELTA sends incremental updates. The frontend replaces on snapshot and merges on delta.
Lifecycle — RUN_STARTED and RUN_FINISHED (or RUN_ERROR) mark execution boundaries.
When Alex asks about low stock items, the event stream looks like
Snapshot-Delta — STATE_SNAPSHOT sends complete agent state initially. STATE_DELTA sends incremental updates. The frontend replaces on snapshot and merges on delta.
Lifecycle — RUN_STARTED and RUN_FINISHED (or RUN_ERROR) mark execution boundaries.
When Alex asks about low stock items, the event stream looks like
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
RUN_STARTED
REASONING_MESSAGE "Analyzing request and planning tool usage..."
TOOL_CALL_START get_inventory
TOOL_CALL_ARGS {"source":"warehouse-east","status_filter":"low_stock"}
TOOL_CALL_RESULT {items: [{name:"Mechanical Keyboard",qty:23}, {name:"Laptop Stand",qty:12}]}
TOOL_CALL_START calculator
TOOL_CALL_ARGS {"expression":"(50-23)*129.99 + (40-12)*34.99"}
TOOL_CALL_RESULT {result: 4489.45}
TOOL_CALL_START send_alert
TOOL_CALL_ARGS {"channel":"slack","message":"Low stock alert...","severity":"warning"}
TOOL_CALL_RESULT {alert_id:"ALERT-42391",status:"sent"}
STATE_DELTA {tools_invoked:["get_inventory","calculator","send_alert"]}
TEXT_MESSAGE_START
TEXT_MESSAGE_CONTENT (streaming response token by token)
TEXT_MESSAGE_END
RUN_FINISHED
The Agent: Strands SDK on AgentCore
The agent is defined using the Strands Agents SDK with @tool decorators. For AgentCore, the invocation function uses BedrockAgentCoreApp with @app.entrypoint. Our implementation wraps this in a FastAPI server that emits AG-UI events by inspecting the agent's message history after each invocation.
The AgentCore CLI handles everything from here. `agentcore create` scaffolds the project (generating a Dockerfile and `agentcore/agentcore.json`), and `agentcore deploy` builds the container image via CodeBuild (ARM64 — no local Docker needed), pushes it to ECR, and creates the AgentCore Runtime and endpoint. All from the CLI:
Extracting AG-UI Events from Strands
Strands stores tool calls in its message history using a specific format: block['toolUse'] for tool invocations and block['toolResult'] for results. The FastAPI server inspects this history after each agent call and emits the corresponding AG-UI events:
This bridges the gap between Strands' internal message format and the AG-UI protocol the frontend expects.
The Frontend: Watching the Agent Think
The frontend is a single HTML file with three panels. The chat panel shows streaming text, tool call displays with arguments and results, and reasoning blocks. The events panel logs key AG-UI events — tool calls, reasoning, state changes — color-coded by category. The state panel shows the agent's internal state updating in real time.
The frontend calls /invocations on the same CloudFront domain. CloudFront routes this to the API Gateway, which invokes the Lambda proxy. No CORS configuration needed.
What the User Sees
Instead of a loading spinner:
1. "Analyzing request and planning tool usage..." — Reasoning event
2. "Tool: get_inventory" with {"source":"warehouse-east","status_filter":"low_stock"} — Tool call with arguments
3. Tool result showing 2 low stock items with quantities — Tool result
4. "Tool: calculator" with restock cost expression — Second tool call
5. "Tool: send_alert" with Slack notification — Third tool call
6. Response streams word by word — Final text with analysis and recommendations
7. State panel shows tools_invoked: ["get_inventory", "calculator", "send_alert"]
Full transparency into a multi-step agent workflow.
When to Use This Pattern
Ideal for:
· Agent applications where users need visibility into multi-step reasoning and tool use
· Debugging and development of agent workflows
· Regulated environments requiring audit trails of agent decisions
· Customer-facing agents where transparency builds trust
· Internal tools where non-technical users interact with data through natural language
Consider alternatives for:
· Simple chatbots with no tool use
· Batch processing agents with no user-facing interface
· Agents that should not expose their reasoning to end users
Deployment:
You can clone the code using the command below into Sagemaker AI notebook or local IDE
1
git clone https://github.com/aws-samples/sample-agui-bedrock-agentcore.git’The notebook has five steps:
2. Test locally — Run the agent in the notebook to verify tools work
3. Create and deploy — `agentcore create` scaffolds the project, then `agentcore deploy --target default -y` handles CodeBuild, ECR, and AgentCore Runtime deployment automatically.
4. Test on AgentCore — Invoke via toolkit and boto3, see AG-UI events in the notebook
5. Update Lambda proxy — Point the proxy at the new agent ARN, open the CloudFront URL
The supporting infrastructure (Lambda proxy, API Gateway, S3, CloudFront) is deployed once and reused across agent iterations. The notebook focuses purely on agent development and deployment.
Try these queries in the frontend:
· "Check warehouse-east for low stock items, calculate restock cost, and send a Slack alert"
· "Look up customer CUST-001 and CUST-003, compare their spend"
· "Analyze error trends for 7 days and sales trends for 30 days, generate a report"
Extending with MCP State
The natural next step is integrating MCP (Model Context Protocol) state management. With MCP state, the agent's workflow state is maintained by an MCP server and reported through AG-UI's STATE_SNAPSHOT and STATE_DELTA events — enabling stateful, multi-step workflows where the frontend shows real-time progress through a complex process.
Conclusion
AgentCore handles agent execution and infrastructure. AG-UI provides the standardized event protocol. A Lambda proxy bridges the browser to AgentCore. The result: users see every reasoning step, tool invocation, and state change as it happens.
· Agent logic: Strands SDK with @tool decorators
· Container builds: CodeBuild (no local Docker)
· Frontend: Single HTML file on S3/CloudFront
· Servers to manage: Zero
Get the complete source code and deployment notebook: https://github.com/aws-samples/sample-agui-bedrock-agentcore
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article