Deploy AG-UI servers in AgentCore Runtime

Amazon Bedrock AgentCore Runtime lets you deploy and run Agent User Interface (AG-UI) servers in the AgentCore Runtime. This guide walks you through creating, testing, and deploying your first AG-UI server.

In this section, you learn:

For more information about AG-UI, see AG-UI protocol contract.

How Amazon Bedrock AgentCore supports AG-UI

Amazon Bedrock AgentCore’s AG-UI protocol support enables integration with agent user interface servers by acting as a proxy layer. When configured for AG-UI, Amazon Bedrock AgentCore expects containers to run servers on port 8080 at the /invocations path for HTTP/SSE or /ws for WebSocket connections. Although AG-UI uses the same port and paths as the HTTP protocol, the runtime distinguishes between them by the server protocol configured on the Runtime. With the AgentCore CLI, agentcore add runtime --protocol AGUI sets the Runtime’s protocol to AGUI in agentcore/agentcore.json.

Amazon Bedrock AgentCore acts as a proxy between clients and your AG-UI container. Requests from the InvokeAgentRuntime API are passed through to your container without modification. Amazon Bedrock AgentCore handles authentication (SigV4/OAuth 2.0), session isolation, and scaling.

Key differences from other protocols:

For more information, see https://docs.ag-ui.com/introduction.

Using AG-UI with AgentCore Runtime

In this tutorial you create, test, and deploy an AG-UI server.

For complete examples and framework-specific implementations, see AG-UI Quickstart Documentation and AG-UI Dojo.

Prerequisites

Step 1: Create your AG-UI server

AG-UI is supported by multiple agent frameworks. This tutorial uses AWS Strands for Python.

Scaffold the project

Create an empty project, register a Python AG-UI Runtime with Cognito authorization, and add the dependencies for this example:

agentcore create --name AguiProject --template empty
cd AguiProject
agentcore add runtime \
  --name AguiAgent \
  --language python \
  --protocol AGUI \
  --authorizer-type CUSTOM_JWT \
  --authorizer-configuration \
  "{\"customJwtAuthorizer\":{\"discoveryUrl\":\"https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration\",\"allowedClients\":[\"$CLIENT_ID\"]}}" \
  --request-header-allowlist Authorization
cd app/AguiAgent
uv init --bare
uv add \
  "ag-ui-protocol>=0.1.19,<0.2" \
  "ag-ui-strands>=0.3,<0.4" \
  "aws-opentelemetry-distro~=0.21.0" \
  "bedrock-agentcore[strands-agents]>=1.18.1,<2" \
  "botocore[crt]~=1.43.0" \
  "fastapi>=0.142,<1" \
  "strands-agents>=1.15,<2" \
  "uvicorn>=0.34.3,<1"
cd ../..

The CLI creates README.md and AGENTS.md with the AG-UI Runtime contract, but it does not generate application code. To use another model provider, configure the Strands Agent in your application code. For other frameworks, see the AG-UI framework integrations.

Create your first AG-UI server

Create app/AguiAgent/main.py with the following implementation. This example uses AWS Strands with AG-UI. The server listens on port 8080, exposes /invocations for AG-UI traffic, and exposes /ping for health checks. AgentCore Runtime requires this contract for AG-UI containers.

# app/AguiAgent/main.py
import os

import uvicorn
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse, JSONResponse
from ag_ui_strands import StrandsAgent
from ag_ui.core import RunAgentInput
from ag_ui.encoder import EventEncoder
from strands import Agent

# Create a simple Strands agent
strands_agent = Agent(
    system_prompt="You are a helpful assistant.",
)

# Wrap with AG-UI protocol support
agui_agent = StrandsAgent(
    agent=strands_agent,
    name="my_agent",
    description="A helpful assistant",
)

# FastAPI server
app = FastAPI(telemetry={"auto_configure": False})

@app.post("/invocations")
async def invocations(input_data: dict, request: Request):
    """Main AG-UI endpoint that returns event streams."""
    accept_header = request.headers.get("accept")
    encoder = EventEncoder(accept=accept_header)

    async def event_generator():
        run_input = RunAgentInput(**input_data)
        async for event in agui_agent.run(run_input):
            yield encoder.encode(event)

    return StreamingResponse(
        event_generator(),
        media_type=encoder.get_content_type()
    )

@app.get("/ping")
async def ping():
    return JSONResponse({"status": "Healthy"})

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8080")))

For complete, framework-specific examples, see:

Keep telemetry={"auto_configure": False} with the FastAPI version installed above. The OpenTelemetry distribution owns exporter configuration; this setting prevents FastAPI from also configuring an environment-driven exporter.

Understanding the code

Step 2: Test your AG-UI server locally

Run and test your AG-UI server in a local development environment.

Start your AG-UI server

Run your AG-UI server locally from the project directory:

agentcore dev

You should see output indicating the server is running on port 8080.

Test the endpoint

Test the SSE endpoint with a properly formatted AG-UI request:

curl -N -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{
  "threadId": "test-123",
  "runId": "run-456",
  "state": {},
  "messages": [{"role": "user", "content": "Hello, agent!", "id": "msg-1"}],
  "tools": [],
  "context": [],
  "forwardedProps": {}
}'

You should see AG-UI event streams returned in SSE format, including RUN_STARTED , TEXT_MESSAGE_CONTENT , and RUN_FINISHED events.

Step 3: Deploy your AG-UI server to Bedrock AgentCore Runtime

Deploy your AG-UI server to AWS using the AgentCore CLI. You configured Cognito authorization when you added the Runtime in Step 1, so no further setup is needed before deployment.

Deploy to AWS

Build and deploy your agent:

agentcore build
agentcore deploy

After deployment, get the Runtime ARN:

agentcore status --json

The Runtime resource’s arn field contains its ARN.

Step 4: Invoke your deployed AG-UI server

Invoke your deployed Amazon Bedrock AgentCore AG-UI server and interact with the event streams.

Set up environment variables

Set the following environment variables:

Invoke the AG-UI server

To invoke the AG-UI server programmatically, choose the language that matches your client:

For building full UI applications, see CopilotKit or the AG-UI TypeScript client SDK.

Appendix

Set up Cognito user pool for authentication

For detailed Cognito setup instructions, see Set up Cognito user pool for authentication. The setup process is identical for AG-UI servers.

Troubleshooting

Common AG-UI-specific issues

The following are common issues you might encounter: