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

Amazon Bedrock AgentCore Runtime consente di distribuire ed eseguire server Agent User Interface (AG-UI) nel AgentCore Runtime. Questa guida ti guida nella creazione, nel test e nella distribuzione del tuo primo server. AG-UI 

In questa sezione, imparerai:
+ In che modo Amazon Bedrock supporta AgentCore AG-UI
+ Come creare un server AG-UI 
+ Come testare il server localmente
+ Come installare il server su AWS 
+ Come richiamare il server distribuito

Per ulteriori informazioni in merito AG-UI, consulta il contratto di [AG-UI protocollo](runtime-agui-protocol-contract.md).

**Topics**
+ [In che modo Amazon Bedrock supporta AgentCore AG-UI](#runtime-agui-how-agentcore-supports)
+ [AG-UI AgentCore Utilizzo con Runtime](#runtime-agui-steps)
+ [Appendice](#runtime-agui-appendix)

## In che modo Amazon Bedrock supporta AgentCore AG-UI
<a name="runtime-agui-how-agentcore-supports"></a>

Il supporto AgentCore del AG-UI protocollo di Amazon Bedrock consente l'integrazione con i server di interfaccia utente degli agenti fungendo da livello proxy. Una volta configurato per AG-UI, Amazon Bedrock AgentCore prevede che i container eseguano i server sulla porta `8080` `/invocations` lungo il percorso per HTTP/SSE o `/ws` per WebSocket le connessioni. Sebbene AG-UI utilizzi la stessa porta e gli stessi percorsi del protocollo HTTP, il runtime li distingue in base al `--protocol` flag specificato durante la configurazione della distribuzione.

Amazon Bedrock AgentCore funge da proxy tra i client e il AG-UI container. Le richieste provenienti dall'[InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)API vengono trasferite al contenitore senza modifiche. Amazon Bedrock AgentCore gestisce l'autenticazione (SigV4/OAuth 2.0), l'isolamento delle sessioni e la scalabilità.

Principali differenze rispetto ad altri protocolli:

 **Porta**   
AG-UI i server funzionano sulla porta 8080 (come HTTP, rispetto a 8000 per MCP, 9000 per A2A)

 **Path**   
AG-UI i server utilizzano `/invocations` for HTTP/SSE e `/ws` for WebSocket (come il protocollo HTTP)

 **Formato del messaggio**   
Utilizza i flussi di Server-Sent eventi tramite Events (SSE) per lo streaming o WebSocket per la comunicazione bidirezionale

 **Focus sul protocollo**   
Agent-to-User interazione (rispetto a MCP per gli strumenti, A2A per gli agenti)

 **Autenticazione**   
Supporta schemi di autenticazione SigV4 e OAuth 2.0

Per ulteriori informazioni, consulta [https://docs.ag-ui.com/introduction](https://docs.ag-ui.com/introduction).

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

In questo tutorial creerai, testerai e distribuirai un AG-UI server.

[[Per esempi completi e implementazioni specifiche del framework, consulta Quickstart Documentation e Dojo. AG-UI AG-UI ](https://dojo.ag-ui.com/)](https://docs.ag-ui.com/quickstart/introduction)

**Topics**
+ [Prerequisiti](#runtime-agui-prerequisites)
+ [Fase 1: Crea il tuo server AG-UI](#runtime-agui-create-server)
+ [Passaggio 2: verifica il AG-UI server localmente](#runtime-agui-test-locally)
+ [Fase 3: Implementa il AG-UI server su Bedrock Runtime AgentCore](#runtime-agui-deploy)
+ [Passaggio 4: richiama il server distribuito AG-UI](#runtime-agui-step-4)

### Prerequisiti
<a name="runtime-agui-prerequisites"></a>
+ Python 3.12 o versioni successive, o Node.js 18\+ per TypeScript, installato con una conoscenza di base della lingua scelta
+ Un AWS account con le autorizzazioni appropriate e le credenziali locali configurate
+ Comprensione del AG-UI protocollo e dei concetti di comunicazione tra agenti e utenti basati sugli eventi

### Fase 1: Crea il tuo server AG-UI
<a name="runtime-agui-create-server"></a>

AG-UI è supportato da più framework di agenti. Scegli il framework più adatto alle tue esigenze. AWS Strands fornisce AG-UI integrazioni di prime parti sia per Python che per. TypeScript

#### Installazione dei pacchetti obbligatori
<a name="runtime-agui-install-packages"></a>

Installa pacchetti per Strands con supporto AWS : AG-UI 

**Example**  

1. 

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

1. Crea un `package.json` primo:

   ```
   {
     "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"
     }
   }
   ```

   Quindi installa le dipendenze:

   ```
   npm install
   ```

[Per altri framework, consulta le integrazioni del AG-UI framework.](https://docs.ag-ui.com/introduction#supported-integrations)

#### Crea il tuo primo server AG-UI
<a name="runtime-agui-create-first-server"></a>

Crea il tuo file AG-UI server nella lingua che preferisci. Entrambi gli esempi seguenti producono un server che ascolta sulla porta`8080`, espone il AG-UI traffico e `/invocations` `/ping` i controlli di integrità, il contratto che AgentCore Runtime si aspetta dai container. AG-UI 

**Example**  

1. Crea un nuovo file chiamato. `my_agui_server.py` Questo esempio utilizza AWS Strands con 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. Crea un nuovo file chiamato`my-agui-server.ts`. Questo esempio utilizza AWS Strands con 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();
   ```

Per esempi completi e specifici del framework, vedi:
+  [LangGraph \+ AG-UI](https://docs.copilotkit.ai/langgraph/) 
+  [CrewAI \+ AG-UI](https://docs.copilotkit.ai/crewai-flows) 
+  [AWS Fili \+ AG-UI](https://docs.copilotkit.ai/aws-strands) 

#### Comprensione del codice
<a name="runtime-agui-understanding-code"></a>

 **Stream di eventi**   
AG-UI utilizza Server-Sent Events (SSE) per trasmettere eventi digitati al client

 **/invocations Endpoint**   
Endpoint primario per la HTTP/SSE comunicazione (uguale al protocollo HTTP)

 **Porta 8080**   
AG-UI i server vengono eseguiti sulla porta 8080 per impostazione predefinita in Runtime AgentCore 

### Passaggio 2: verifica il AG-UI server localmente
<a name="runtime-agui-test-locally"></a>

Esegui e testa il tuo AG-UI server in un ambiente di sviluppo locale.

#### Avvia il tuo AG-UI server
<a name="runtime-agui-start-server"></a>

Esegui il AG-UI server localmente:

**Example**  

1. 

   ```
   python my_agui_server.py
   ```

1. 

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

Dovresti vedere un output che indica che il server è in esecuzione sulla porta`8080`.

#### Testa l’endpoint
<a name="runtime-agui-test-endpoint"></a>

Testa l'endpoint SSE con una richiesta AG-UI formattata correttamente:

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

Dovresti vedere i flussi di AG-UI eventi restituiti in formato SSE, inclusi`RUN_STARTED`, ed eventi. `TEXT_MESSAGE_CONTENT` `RUN_FINISHED`

### Fase 3: Implementa il AG-UI server su Bedrock Runtime AgentCore
<a name="runtime-agui-deploy"></a>

Implementa il tuo AG-UI server AWS utilizzando lo AgentCore starter toolkit di Amazon Bedrock.

#### Installa gli strumenti di distribuzione
<a name="runtime-agui-install-deployment-tools"></a>

Installa il toolkit di AgentCore avvio di Amazon Bedrock:

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

Inizia creando una cartella di progetto con la seguente struttura:

**Example**  

1. 

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

   Crea un nuovo file chiamato `requirements.txt` con le tue dipendenze:

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

   Crea un`tsconfig.json`:

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

#### Configura il pool di utenti di Cognito per l'autenticazione
<a name="runtime-agui-setup-cognito"></a>

Configura l'autenticazione per un accesso sicuro al server distribuito. Per istruzioni dettagliate sulla configurazione di Cognito, consulta [Configurare il pool di utenti di Cognito](#runtime-agui-appendix-a) per l'autenticazione. Ciò fornisce i token OAuth necessari per un accesso sicuro al server distribuito.

#### Configura il tuo server per la distribuzione AG-UI
<a name="runtime-agui-configure-deployment"></a>

Dopo aver impostato l'autenticazione, crea la configurazione di distribuzione. Passa il punto di ingresso corrispondente alla lingua che hai usato:

**Example**  

1. 

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

1. 

   ```
   agentcore configure -e my-agui-server.ts --protocol AGUI
   ```
+ Seleziona il protocollo come AGUI
+ Configura con la configurazione OAuth come impostato nel passaggio precedente

#### Esegui la distribuzione su AWS
<a name="runtime-agui-deploy-aws"></a>

Implementa il tuo agente:

```
agentcore deploy
```

Dopo la distribuzione, riceverai un ARN di runtime dell'agente simile a:

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

### Passaggio 4: richiama il server distribuito AG-UI
<a name="runtime-agui-step-4"></a>

Richiama il AgentCore AG-UI server Amazon Bedrock distribuito e interagisci con i flussi di eventi.

#### Impostazione delle variabili di ambiente
<a name="runtime-agui-setup-environment-variables"></a>

Impostazione delle variabili di ambiente

1. Esporta il token bearer come variabile di ambiente. Per la configurazione del token bearer, consulta [Configurare il pool di utenti di Cognito](#runtime-agui-appendix-a) per l'autenticazione.

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

1. Esporta l'ARN dell'agente.

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

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

Per richiamare il AG-UI server a livello di codice, scegli la lingua che corrisponde al tuo client:

**Example**  

1. Installa i pacchetti richiesti:

   ```
   pip install httpx httpx-sse
   ```

   Quindi usa il seguente codice client:

   ```
   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. Installa i pacchetti richiesti:

   ```
   npm install @ag-ui/client
   ```

   Quindi usa il seguente codice client:

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

Per creare applicazioni UI complete, consulta [CopilotKit](https://docs.copilotkit.ai/)o l'[SDK AG-UI TypeScript del client](https://docs.ag-ui.com/sdk/js/client/overview).

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

**Topics**
+ [Configura il pool di utenti di Cognito per l'autenticazione](#runtime-agui-appendix-a)
+ [Risoluzione dei problemi](#runtime-agui-troubleshooting)

### Configura il pool di utenti di Cognito per l'autenticazione
<a name="runtime-agui-appendix-a"></a>

Per istruzioni dettagliate sulla configurazione di Cognito, consulta Configurare il [pool di utenti Cognito per l'autenticazione](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html#set-up-cognito-user-pool-for-authentication) nella documentazione MCP. Il processo di configurazione è identico per i server. AG-UI 

### Risoluzione dei problemi
<a name="runtime-agui-troubleshooting"></a>

 ** AG-UI-specific Problemi comuni** 

Di seguito sono riportati i problemi più comuni che potresti riscontrare:

Conflitti tra porte  
AG-UI i server devono essere eseguiti sulla porta 8080 nell'ambiente AgentCore Runtime

Mancata corrispondenza del metodo di autorizzazione  
Assicurati che la tua richiesta utilizzi lo stesso metodo di autenticazione (OAuth o SigV4) con cui è stato configurato l'agente

Errori di formato degli eventi  
Assicurati che i tuoi eventi seguano le specifiche del AG-UI protocollo. Vedi la [documentazione AG-UI sugli eventi](https://docs.ag-ui.com/concepts/events)