# Menyebarkan AG-UI server di Runtime AgentCore
<a name="runtime-agui"></a>

Amazon Bedrock AgentCore Runtime memungkinkan Anda menerapkan dan menjalankan server Agent User Interface (AG-UI) di Runtime. AgentCore 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](runtime-agui-protocol-contract.md).

**Topics**
+ [Bagaimana Amazon Bedrock mendukung AgentCore AG-UI](#runtime-agui-how-agentcore-supports)
+ [Menggunakan AG-UI dengan AgentCore Runtime](#runtime-agui-steps)
+ [Lampiran](#runtime-agui-appendix)

## Bagaimana Amazon Bedrock mendukung AgentCore AG-UI
<a name="runtime-agui-how-agentcore-supports"></a>

Dukungan AG-UI protokol AgentCore Amazon Bedrock memungkinkan integrasi dengan server antarmuka pengguna agen dengan bertindak sebagai lapisan proxy. Saat dikonfigurasi untuk AG-UI, Amazon Bedrock AgentCore mengharapkan kontainer untuk 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 membedakannya berdasarkan `--protocol` flag yang ditentukan selama konfigurasi penerapan.

Amazon Bedrock AgentCore bertindak sebagai proxy antara klien dan AG-UI penampung Anda. Permintaan dari [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)API diteruskan ke container 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 seperti HTTP, vs 8000 untuk MCP, 9000 untuk A2A)

 **Jalan**   
AG-UI server digunakan `/invocations` untuk HTTP/SSE dan `/ws` untuk WebSocket (sama seperti protokol HTTP)

 **Format Pesan**   
Menggunakan aliran acara melalui Server-Sent Acara (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](https://docs.ag-ui.com/introduction).

## Menggunakan AG-UI dengan AgentCore Runtime
<a name="runtime-agui-steps"></a>

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

[Untuk contoh lengkap dan implementasi khusus kerangka kerja, lihat Dokumentasi Mulai [AG-UI Cepat](https://docs.ag-ui.com/quickstart/introduction) dan Dojo. AG-UI ](https://dojo.ag-ui.com/)

**Topics**
+ [Prasyarat](#runtime-agui-prerequisites)
+ [Langkah 1: Buat AG-UI server Anda](#runtime-agui-create-server)
+ [Langkah 2: Uji AG-UI server Anda secara lokal](#runtime-agui-test-locally)
+ [Langkah 3: Menyebarkan AG-UI server Anda ke Bedrock AgentCore Runtime](#runtime-agui-deploy)
+ [Langkah 4: Panggil server yang Anda gunakan AG-UI](#runtime-agui-step-4)

### Prasyarat
<a name="runtime-agui-prerequisites"></a>
+ Python 3.12 atau lebih tinggi, atau Node.js 18\+ untuk TypeScript, diinstal dengan pemahaman dasar bahasa pilihan Anda
+  AWS Akun dengan izin yang sesuai dan kredensi lokal yang dikonfigurasi
+ Memahami AG-UI protokol dan konsep komunikasi agen-ke-pengguna berbasis peristiwa

### Langkah 1: Buat AG-UI server Anda
<a name="runtime-agui-create-server"></a>

AG-UI didukung oleh beberapa kerangka kerja agen. Pilih kerangka kerja yang paling sesuai dengan kebutuhan Anda. AWS Strands menyediakan AG-UI integrasi pihak pertama untuk Python dan. TypeScript

#### Menginstal paket yang diperlukan
<a name="runtime-agui-install-packages"></a>

Instal paket untuk AWS Strands dengan AG-UI dukungan:

**Example**  

1. 

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

1. Buat yang `package.json` pertama:

   ```
   {
     "name": "my-agui-server",
     "type": "module",
     "scripts": {
       "build": "tsc"
     },
     "dependencies": {
       "@ag-ui/aws-strands": "^0.1.0",
       "@strands-agents/sdk": "^1.1.0"
     },
     "devDependencies": {
       "@types/express": "^5.0.0",
       "@types/node": "^22.0.0",
       "tsx": "^4.0.0",
       "typescript": "^5.0.0"
     }
   }
   ```

   Kemudian instal dependensi:

   ```
   npm install
   ```

Untuk kerangka kerja lainnya, lihat [integrasi AG-UI kerangka kerja](https://docs.ag-ui.com/introduction#supported-integrations).

#### Buat AG-UI server pertama Anda
<a name="runtime-agui-create-first-server"></a>

Buat file AG-UI server Anda dalam bahasa pilihan Anda. Kedua contoh di bawah ini menghasilkan server yang mendengarkan di port`8080`, mengekspos AG-UI lalu lintas, dan `/invocations` `/ping` untuk pemeriksaan kesehatan — kontrak yang diharapkan AgentCore Runtime dari kontainer. AG-UI 

**Example**  

1. Buat file baru bernama`my_agui_server.py`. Contoh ini menggunakan AWS Strands dengan AG-UI:

   ```
   # 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)
   ```

1. Buat file baru bernama`my-agui-server.ts`. Contoh ini menggunakan AWS Strands dengan AG-UI:

   ```
   // my-agui-server.ts
   import { Agent } from "@strands-agents/sdk";
   import { StrandsAgent } from "@ag-ui/aws-strands";
   import { createStrandsApp } from "@ag-ui/aws-strands/server";
   
   async function main(): Promise<void> {
     // Create a simple Strands agent
     const strandsAgent = new Agent({
       systemPrompt: "You are a helpful assistant.",
     });
   
     // Wrap with AG-UI protocol support
     const aguiAgent = new StrandsAgent({
       agent: strandsAgent,
       name: "my_agent",
       description: "A helpful assistant",
     });
   
     // Express app exposing the AgentCore-required paths on port 8080
     const app = await createStrandsApp(aguiAgent, {
       path: "/invocations",
       pingPath: "/ping",
     });
   
     app.listen(8080, () => {
       console.log("AG-UI server running on port 8080");
     });
   }
   
   void main();
   ```

Untuk contoh lengkap dan spesifik kerangka kerja, lihat:
+  [LangGraph \+ AG-UI](https://docs.copilotkit.ai/langgraph/) 
+  [CrewAI \+ AG-UI](https://docs.copilotkit.ai/crewai-flows) 
+  [AWS Helai \+ AG-UI](https://docs.copilotkit.ai/aws-strands) 

#### Memahami kode
<a name="runtime-agui-understanding-code"></a>

 **Aliran Acara**   
AG-UI menggunakan Server-Sent Events (SSE) untuk mengalirkan peristiwa yang diketik ke klien

 **/pemanggilan Titik Akhir**   
Titik akhir utama untuk HTTP/SSE komunikasi (sama seperti protokol HTTP)

 **Pelabuhan 8080**   
AG-UI server berjalan pada port 8080 secara default di AgentCore Runtime

### Langkah 2: Uji AG-UI server Anda secara lokal
<a name="runtime-agui-test-locally"></a>

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

#### Mulai AG-UI server Anda
<a name="runtime-agui-start-server"></a>

Jalankan AG-UI server Anda secara lokal:

**Example**  

1. 

   ```
   python my_agui_server.py
   ```

1. 

   ```
   npx tsx my-agui-server.ts
   ```

Anda akan melihat output yang menunjukkan server berjalan pada port`8080`.

#### Menguji titik akhir
<a name="runtime-agui-test-endpoint"></a>

Uji titik akhir SSE dengan permintaan yang diformat AG-UI 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, termasuk, `RUN_STARTED``TEXT_MESSAGE_CONTENT`, dan `RUN_FINISHED` acara.

### Langkah 3: Menyebarkan AG-UI server Anda ke Bedrock AgentCore Runtime
<a name="runtime-agui-deploy"></a>

Terapkan AG-UI server Anda untuk AWS menggunakan AgentCore toolkit starter Amazon Bedrock.

#### Instal alat penyebaran
<a name="runtime-agui-install-deployment-tools"></a>

Instal AgentCore toolkit starter Amazon Bedrock:

```
pip install bedrock-agentcore-starter-toolkit
```

Mulailah dengan membuat folder proyek dengan struktur berikut:

**Example**  

1. 

   ```
   ## 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
   ```

1. 

   ```
   ## Project Folder Structure
   your_project_directory/
   ├── my-agui-server.ts          # Your main agent code
   ├── package.json               # Dependencies for your agent
   └── tsconfig.json              # TypeScript compiler configuration
   ```

   Buat`tsconfig.json`:

   ```
   {
     "compilerOptions": {
       "target": "ES2022",
       "lib": ["ES2022", "DOM"],
       "module": "NodeNext",
       "moduleResolution": "NodeNext",
       "outDir": "./dist",
       "strict": true,
       "esModuleInterop": true
     },
     "include": ["*.ts"]
   }
   ```

#### Siapkan kumpulan pengguna Cognito untuk otentikasi
<a name="runtime-agui-setup-cognito"></a>

Konfigurasikan otentikasi untuk akses aman ke server yang Anda gunakan. Untuk petunjuk penyiapan Cognito yang mendetail, lihat [Mengatur kumpulan pengguna Cognito](#runtime-agui-appendix-a) untuk autentikasi. Ini menyediakan token OAuth yang diperlukan untuk akses aman ke server yang Anda gunakan.

#### Konfigurasikan AG-UI server Anda untuk penerapan
<a name="runtime-agui-configure-deployment"></a>

Setelah menyiapkan otentikasi, buat konfigurasi penerapan. Lewati entrypoint yang cocok dengan bahasa yang Anda gunakan:

**Example**  

1. 

   ```
   agentcore configure -e my_agui_server.py --protocol AGUI
   ```

1. 

   ```
   agentcore configure -e my-agui-server.ts --protocol AGUI
   ```
+ Pilih protokol sebagai AGUI
+ Konfigurasikan dengan konfigurasi OAuth sebagai pengaturan pada langkah sebelumnya

#### Menyebarkan ke AWS
<a name="runtime-agui-deploy-aws"></a>

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
<a name="runtime-agui-step-4"></a>

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

#### Mengatur variabel lingkungan
<a name="runtime-agui-setup-environment-variables"></a>

Mengatur variabel lingkungan

1. Ekspor token pembawa sebagai variabel lingkungan. Untuk penyiapan token pembawa, lihat [Mengatur kumpulan pengguna Cognito](#runtime-agui-appendix-a) untuk autentikasi.

   ```
   export BEARER_TOKEN="<BEARER_TOKEN>"
   ```

1. Ekspor agen ARN.

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

#### Memanggil server AG-UI
<a name="runtime-agui-invoke-example"></a>

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

**Example**  

1. 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!"))
   ```

1. 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](https://docs.copilotkit.ai/)atau [SDK AG-UI TypeScript klien](https://docs.ag-ui.com/sdk/js/client/overview).

## Lampiran
<a name="runtime-agui-appendix"></a>

**Topics**
+ [Siapkan kumpulan pengguna Cognito untuk otentikasi](#runtime-agui-appendix-a)
+ [Pemecahan masalah](#runtime-agui-troubleshooting)

### Siapkan kumpulan pengguna Cognito untuk otentikasi
<a name="runtime-agui-appendix-a"></a>

Untuk petunjuk penyiapan Cognito yang mendetail, lihat Mengatur [kumpulan pengguna Cognito untuk autentikasi](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html#set-up-cognito-user-pool-for-authentication) dalam dokumentasi MCP. Proses setup identik untuk AG-UI server.

### Pemecahan masalah
<a name="runtime-agui-troubleshooting"></a>

 ** 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 telah dikonfigurasi oleh agen

Kesalahan format acara  
Pastikan acara Anda mengikuti spesifikasi AG-UI protokol. Lihat [Dokumentasi AG-UI Acara](https://docs.ag-ui.com/concepts/events)