Bagaimana Amazon Bedrock mendukung AgentCore AG-UI Menggunakan AG-UI dengan AgentCore Runtime Lampiran

Menyebarkan AG-UI server di AgentCore Runtime

Amazon Bedrock AgentCore Runtime memungkinkan Anda menyebarkan dan menjalankan server Agent User Interface (AG-UI) di AgentCore Runtime. Panduan ini memandu Anda melalui pembuatan, pengujian, dan penerapan AG-UI server pertama Anda.

Di bagian ini, Anda belajar:

Bagaimana Amazon Bedrock mendukung AgentCore AG-UI
Cara membuat AG-UI server
Cara menguji server Anda secara lokal
Cara menyebarkan server Anda ke AWS
Cara memanggil server yang Anda gunakan

Untuk informasi selengkapnya AG-UI, lihat kontrak AG-UI protokol.

Topik

Bagaimana Amazon Bedrock mendukung AgentCore AG-UI
Menggunakan AG-UI dengan AgentCore Runtime
Lampiran

Bagaimana Amazon Bedrock mendukung AgentCore AG-UI

Dukungan AG-UI protokol Amazon Bedrock AgentCore memungkinkan integrasi dengan server antarmuka pengguna agen dengan bertindak sebagai lapisan proxy. Saat dikonfigurasi untuk AG-UI, Amazon Bedrock AgentCore mengharapkan kontainer menjalankan server pada port 8080 di /invocations jalur untuk HTTP/SSE atau /ws untuk WebSocket koneksi. Meskipun AG-UI menggunakan port dan jalur yang sama dengan protokol HTTP, runtime membedakan antara mereka berdasarkan --protocol flag yang ditentukan selama konfigurasi penerapan.

Amazon Bedrock AgentCore bertindak sebagai proxy antara klien dan AG-UI wadah Anda. Permintaan dari InvokeAgentRuntime API diteruskan ke wadah Anda tanpa modifikasi. Amazon Bedrock AgentCore menangani otentikasi (SigV4/OAuth 2.0), isolasi sesi, dan penskalaan.

Perbedaan utama dari protokol lain:

Port: AG-UI server berjalan pada port 8080 (sama dengan HTTP, vs 8000 untuk MCP, 9000 untuk A2A)
Jalur: AG-UI server digunakan /invocations untuk HTTP/SSE dan /ws untuk WebSocket (sama dengan protokol HTTP)
Format Pesan: Menggunakan aliran acara melalui Ev Server-Sent ents (SSE) untuk streaming, atau WebSocket untuk komunikasi dua arah
Fokus Protokol: Agent-to-User interaksi (vs MCP untuk alat, A2A untuk agen-ke-agen)
Autentikasi: Mendukung skema otentikasi SigV4 dan OAuth 2.0

Untuk informasi selengkapnya, lihat https://docs.ag-ui.com/introduction.

Menggunakan AG-UI dengan AgentCore Runtime

Dalam tutorial ini Anda membuat, menguji, dan menyebarkan AG-UI server.

Untuk contoh lengkap dan implementasi khusus kerangka kerja, lihat Dokumentasi AG-UI Quickstart dan Dojo. AG-UI

Topik

Prasyarat
Langkah 1: Buat AG-UI server Anda
Langkah 2: Uji AG-UI server Anda secara lokal
Langkah 3: Terapkan AG-UI server Anda ke Bedrock Runtime AgentCore
Langkah 4: Panggil server yang Anda gunakan AG-UI

Prasyarat

Python 3.12 atau lebih tinggi diinstal
Node.js 20 atau lebih tinggi diinstal untuk AgentCore CLI
AWS Akun dengan izin yang sesuai dan kredenSIAL lokal dikonfigurasi
Pemahaman tentang AG-UI protokol dan konsep komunikasi agen-ke-pengguna berbasis peristiwa

Langkah 1: Buat AG-UI server Anda

AG-UI didukung oleh beberapa kerangka kerja agen. Tutorial ini menggunakan AWS Strands untuk Python.

Menginstal paket yang diperlukan

Instal paket untuk AWS Strands dengan AG-UI dukungan:


pip install fastapi
pip install uvicorn
pip install ag-ui-strands

Untuk kerangka kerja lainnya, lihat integrasi AG-UI kerangka kerja.

Buat AG-UI server pertama Anda

Buat file bernama my_agui_server.py. Contoh ini menggunakan Str AWS ands with AG-UI. Server mendengarkan port8080, mengek /invocations spos AG-UI lalu lintas, dan mengekspos /ping untuk pemeriksaan kesehatan. AgentCore Runtime membutuhkan kontrak ini untuk AG-UI kontainer.


# my_agui_server.py
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()

@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=8080)

Untuk contoh lengkap khusus kerangka kerja, lihat:

Memahami kode

Aliran Acara: AG-UI menggunakan Ev Server-Sent ents (SSE) untuk mengalirkan peristiwa yang diketik ke klien
/Titik akhir pemanggilan: Titik akhir utama untuk HTTP/SSE komunikasi (sama dengan protokol HTTP)
Pelabuhan 8080: AG-UI server berjalan pada port 8080 secara default di Runtime AgentCore

Langkah 2: Uji AG-UI server Anda secara lokal

Jalankan dan uji AG-UI server Anda di lingkungan pengembangan lokal.

Mulai AG-UI server Anda

Jalankan AG-UI server Anda secara lokal:


python my_agui_server.py

Anda akan melihat output yang menunjukkan server berjalan di port8080.

Menguji titik akhir

Uji titik akhir SSE dengan AG-UI permintaan yang diformat dengan benar:


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": {}
}'

Anda akan melihat aliran AG-UI acara dikembalikan dalam format SSE, termasukRUN_STARTED,TEXT_MESSAGE_CONTENT, dan RUN_FINISHED acara.

Langkah 3: Terapkan AG-UI server Anda ke Bedrock Runtime AgentCore

Terapkan AG-UI server Anda untuk AWS menggunakan AgentCore CLI.

Instal alat penyebaran

Instal AgentCore CLI:


npm install -g @aws/agentcore

Mulailah dengan membuat folder proyek dengan struktur berikut:


## Project Folder Structure
your_project_directory/
├── my_agui_server.py          # Your main agent code
├── requirements.txt           # Dependencies for your agent

Buat file baru yang disebut requirements.txt dengan dependensi Anda:


fastapi
uvicorn
ag-ui-strands

Siapkan kumpulan pengguna Cognito untuk otentikasi

Konfigurasikan otentikasi untuk akses aman ke server yang Anda gunakan. Untuk petunjuk penyiapan Cognito terperinci, lihat Menyi apkan kumpulan pengguna Cognito untuk otentikasi. Ini menyediakan token OAuth yang diperlukan untuk akses aman ke server yang Anda gunakan.

Setelah Anda menyelesaikan penyiapan Cognito, ekspor nilai yang digunakan perintah penerapan:


export REGION="<your-region>"
export POOL_ID="<your-user-pool-id>"
export CLIENT_ID="<your-app-client-id>"

Konfigurasikan AG-UI server Anda untuk penerapan

Buat AgentCore proyek kosong. Kemudian daftarkan server yang Anda buat di Buat AG-UI server pertama Anda sebagai agen BYO dengan konfigurasi Cognito dari langkah sebelumnya:


agentcore create --project-name AguiProject --no-agent
cd AguiProject
agentcore add agent \
  --name AguiAgent \
  --type byo \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --code-location .. \
  --entrypoint my_agui_server.py \
  --protocol AGUI \
  --authorizer-type CUSTOM_JWT \
  --discovery-url "https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration" \
  --allowed-clients "$CLIENT_ID" \
  --request-header-allowlist Authorization

Perintah mendaftarkan implementasi yang ada dengan AG-UI protokol dan konfigurasi Cognito OAuth dari langkah sebelumnya.

Menyebarkan ke AWS

Menyebarkan agen Anda:


agentcore deploy

Setelah penerapan, Anda akan menerima ARN runtime agen yang terlihat seperti:


arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/my_agui_server-xyz123

Langkah 4: Panggil server yang Anda gunakan AG-UI

Panggil AgentCore AG-UI server Amazon Bedrock yang Anda gunakan dan berinteraksi dengan aliran acara.

Menyiapkan variabel lingkungan

Ekspor token pembawa sebagai variabel lingkungan. Untuk pengaturan token pembawa, lihat Menyiapkan kum pulan pengguna Cognito untuk otentikasi.
```
export BEARER_TOKEN="<BEARER_TOKEN>"
```

Ekspor agen ARN.


export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/my_agui_server-xyz123"

Memanggil server AG-UI

Untuk memanggil AG-UI server secara terprogram, pilih bahasa yang cocok dengan klien Anda:

contoh

Python

Instal paket yang diperlukan:


pip install httpx httpx-sse

Kemudian gunakan kode klien berikut:


import asyncio
import json
import os
from urllib.parse import quote
from uuid import uuid4

import httpx
from httpx_sse import aconnect_sse

async def invoke_agui_agent(message: str):
    agent_arn = os.environ.get('AGENT_ARN')
    bearer_token = os.environ.get('BEARER_TOKEN')
    escaped_arn = quote(agent_arn, safe='')

    url = f"https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/{escaped_arn}/invocations?qualifier=DEFAULT"
    headers = {
        "Authorization": f"Bearer {bearer_token}",
        "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": str(uuid4()),
    }
    payload = {
        "threadId": str(uuid4()),
        "runId": str(uuid4()),
        "messages": [{"id": str(uuid4()), "role": "user", "content": message}],
        "state": {},
        "tools": [],
        "context": [],
        "forwardedProps": {},
    }

    async with httpx.AsyncClient(timeout=300) as client:
        async with aconnect_sse(client, "POST", url, headers=headers, json=payload) as sse:
            async for event in sse.aiter_sse():
                data = json.loads(event.data)
                event_type = data.get("type")
                if event_type == "TEXT_MESSAGE_CONTENT":
                    print(data.get("delta", ""), end="", flush=True)
                elif event_type == "RUN_ERROR":
                    print(f"Error: {data.get('code')} - {data.get('message')}")

asyncio.run(invoke_agui_agent("Hello!"))

TypeScript

Instal paket yang diperlukan:


npm install @ag-ui/client

Kemudian gunakan kode klien berikut:


import { HttpAgent, AgentSubscriber } from "@ag-ui/client";
import { randomUUID } from "crypto";

async function invokeAguiAgent(message: string): Promise<void> {
  const agentArn = process.env.AGENT_ARN!;
  const bearerToken = process.env.BEARER_TOKEN!;
  const escapedArn = encodeURIComponent(agentArn);

  const agent = new HttpAgent({
    url: `https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/${escapedArn}/invocations?qualifier=DEFAULT`,
    headers: {
      Authorization: `Bearer ${bearerToken}`,
      "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": randomUUID(),
    },
  });

  agent.messages = [{ id: randomUUID(), role: "user", content: message }];

  const subscriber: AgentSubscriber = {
    onTextMessageContentEvent: ({ event }) => {
      process.stdout.write(event.delta);
    },
    onRunErrorEvent: ({ event }) => {
      console.error(`Error: ${event.code ?? "RUN_ERROR"} - ${event.message}`);
    },
  };

  await agent.runAgent({}, subscriber);
}

void invokeAguiAgent("Hello!");

Untuk membangun aplikasi UI lengkap, lihat CopilotKit atau SDK AG-UI TypeScript klien.

Lampiran

Topik

Siapkan kumpulan pengguna Cognito untuk otentikasi
Pemecahan masalah

Siapkan kumpulan pengguna Cognito untuk otentikasi

Untuk petunjuk penyiapan Cognito terperinci, lihat Menyiapkan kumpulan pengguna Cognito untuk otentikasi dalam dokumentasi MCP. Proses penyiapannya identik untuk AG-UI server.

Pemecahan masalah

AG-UI-specific Masalah umum

Berikut ini adalah masalah umum yang mungkin Anda temui:

Konflik pelabuhan: AG-UI server harus berjalan pada port 8080 di lingkungan AgentCore Runtime
Ketidakcocokan metode otorisasi: Pastikan permintaan Anda menggunakan metode otentikasi yang sama (OAuth atau SigV4) yang dikonfigurasi dengan agen
Kesalahan format acara: Pastikan acara Anda mengikuti spesifikasi AG-UI protokol. Lihat Dokument AG-UI asi Acara

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Menyebarkan server A2A

Gunakan sesi terisolasi untuk agen