Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Distribuisci AG-UI server in AgentCore Runtime

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

In questa sezione, imparerai:

Per ulteriori informazioni AG-UI, vedere il contratto di AG-UI protocollo.

In che modo Amazon Bedrock supporta AgentCore AG-UI

Il supporto AgentCore del AG-UI protocollo di Amazon Bedrock consente l'integrazione con i server di interfaccia utente degli agenti agendo come un livello proxy. Se configurato per AG-UI, Amazon Bedrock AgentCore si aspetta che i container eseguano i server sulla porta 8080 nel /invocations percorso per HTTP/SSE o /ws per le connessioni. WebSocket 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 contenitore. AG-UI Le richieste dall'InvokeAgentRuntimeAPI vengono inoltrate al contenitore senza modifiche. Amazon Bedrock AgentCore gestisce l'autenticazione (SigV4/OAuth 2.0), l'isolamento delle sessioni e il ridimensionamento.

Principali differenze rispetto ad altri protocolli:

Per ulteriori informazioni, consulta https://docs.ag-ui.com/introduction.

AG-UI AgentCore Utilizzo con Runtime

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

Per esempi completi e implementazioni specifiche del framework, consulta la documentazione Quickstart e Dojo. AG-UI AG-UI

Prerequisiti

Fase 1: Crea il tuo server AG-UI

AG-UI è supportato da più framework di agenti. Questo tutorial utilizza AWS Strands for Python.

Installazione dei pacchetti obbligatori

Installa i pacchetti per AWS Strands con AG-UI supporto:

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

Per altri framework, consulta le integrazioni del AG-UI framework.

Crea il tuo primo server AG-UI

Crea un file denominato my_agui_server.py. Questo esempio utilizza AWS Strands with AG-UI. Il server è in ascolto sulla porta8080, espone /invocations al AG-UI traffico ed espone ai controlli /ping di integrità. AgentCore Runtime richiede questo contratto per i contenitori. 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)

Per esempi completi e specifici del framework, vedi:

Comprensione del codice

Passaggio 2: testa il tuo AG-UI server localmente

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

Avvia il tuo AG-UI server

Esegui il AG-UI server localmente:

python my_agui_server.py

Dovresti vedere un output che indica che il server è in esecuzione sulla porta8080.

Testa l’endpoint

Testa l'endpoint SSE con una richiesta formattata AG-UI 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, inclusiRUN_STARTED, ed eventi. TEXT_MESSAGE_CONTENT RUN_FINISHED

Fase 3: Distribuisci il tuo AG-UI server su Bedrock Runtime AgentCore

Distribuisci il tuo AG-UI server AWS utilizzando la CLI. AgentCore

Installa gli strumenti di distribuzione

Installa la AgentCore CLI:

npm install -g @aws/agentcore

Inizia creando una cartella di progetto con la seguente struttura:

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

Configura il pool di utenti Cognito per l'autenticazione

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 per l'autenticazione. Ciò fornisce i token OAuth necessari per l'accesso sicuro al server distribuito.

Dopo aver completato la configurazione di Cognito, esporta i valori utilizzati dal comando di distribuzione:

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

Configura il tuo AG-UI server per la distribuzione

Crea un AgentCore progetto vuoto. Quindi registra il server che hai creato in Crea il tuo primo AG-UI server come agente BYO con la configurazione Cognito del passaggio precedente:

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

I comandi registrano l'implementazione esistente con il AG-UI protocollo e la configurazione OAuth di Cognito del passaggio precedente.

Distribuisci su AWS

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

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

Impostazione delle variabili di ambiente

Impostazione delle variabili di ambiente

Richiama il server AG-UI

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

Per creare applicazioni di interfaccia utente complete, consulta CopilotKit o l'SDK AG-UI TypeScript del client.

Appendice

Configura il pool di utenti Cognito per l'autenticazione

Per istruzioni dettagliate sulla configurazione di Cognito, vedi Configurare il pool di utenti Cognito per l'autenticazione nella documentazione MCP. Il processo di configurazione è identico per i server. AG-UI

Risoluzione dei problemi

AG-UI-specific Problemi comuni

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