Como o Amazon Bedrock oferece suporte AgentCore AG-UI Usando AG-UI com AgentCore Runtime Apêndice

Implemente AG-UI servidores em AgentCore tempo de execução

O Amazon Bedrock AgentCore Runtime permite que você implante e execute servidores Agent User Interface (AG-UI) no AgentCore Runtime. Este guia explica como criar, testar e implantar seu primeiro AG-UI servidor.

Nesta seção, você aprende:

Como o Amazon Bedrock oferece suporte AgentCore AG-UI
Como criar um AG-UI servidor
Como testar seu servidor localmente
Como implantar seu servidor no AWS
Como invocar seu servidor implantado

Para obter mais informações sobre AG-UI, consulte contrato de AG-UI protocolo.

Tópicos

Como o Amazon Bedrock oferece suporte AgentCore AG-UI
Usando AG-UI com AgentCore Runtime
Apêndice

Como o Amazon Bedrock oferece suporte AgentCore AG-UI

O suporte ao AG-UI protocolo Amazon Bedrock AgentCore permite a integração com servidores de interface de usuário do agente, atuando como uma camada proxy. Quando configurado para AG-UI, o Amazon Bedrock AgentCore espera que os contêineres executem servidores 8080 na porta no /invocations caminho para HTTP/SSE ou /ws para WebSocket as conexões. Embora AG-UI use a mesma porta e caminhos do protocolo HTTP, o tempo de execução os distingue com base no --protocol sinalizador especificado durante a configuração da implantação.

O Amazon Bedrock AgentCore atua como um proxy entre os clientes e seu AG-UI contêiner. As solicitações da InvokeAgentRuntime API são passadas para seu contêiner sem modificações. O Amazon Bedrock AgentCore lida com autenticação (SigV4/OAuth 2.0), isolamento de sessão e escalabilidade.

Principais diferenças em relação a outros protocolos:

Porta: AG-UI servidores executados na porta 8080 (o mesmo que HTTP, versus 8000 para MCP, 9000 para A2A)
Path: AG-UI servidores usados /invocations para HTTP/SSE e /ws para WebSocket (o mesmo que o protocolo HTTP)
Formato da mensagem: Usa fluxos de Server-Sent eventos via Eventos (SSE) para streaming ou WebSocket para comunicação bidirecional
Foco no protocolo: Agent-to-User interação (versus MCP para ferramentas, A2A para agente a agente)
Autenticação: Suporta esquemas de autenticação SigV4 e OAuth 2.0

Para obter mais informações, consulte https://docs.ag-ui.com/introduction.

Usando AG-UI com AgentCore Runtime

Neste tutorial, você cria, testa e implanta um AG-UI servidor.

Para exemplos completos e implementações específicas da estrutura, consulte a documentação do AG-UI Quickstart e o Dojo. AG-UI

Tópicos

Pré-requisitos
Etapa 1: Crie seu AG-UI servidor
Etapa 2: teste seu AG-UI servidor localmente
Etapa 3: implante seu AG-UI servidor no Bedrock AgentCore Runtime
Etapa 4: invocar seu servidor implantado AG-UI

Pré-requisitos

Python 3.12 ou superior instalado
Node.js 20 ou superior instalado para a AgentCore CLI
Uma AWS conta com permissões apropriadas e credenciais locais configuradas
Compreensão do AG-UI protocolo e dos conceitos de comunicação entre agentes e usuários baseados em eventos

Etapa 1: Crie seu AG-UI servidor

AG-UI é suportado por várias estruturas de agentes. Este tutorial usa AWS Strands para Python.

Instalar os pacotes obrigatórios

Instale pacotes para AWS Strands com AG-UI suporte:


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

Para outras estruturas, consulte as integrações da AG-UI estrutura.

Crie seu primeiro AG-UI servidor

Crie um arquivo chamado my_agui_server.py. Este exemplo usa AWS Strands with AG-UI. O servidor escuta na porta8080, expõe o AG-UI tráfego e expõe /invocations /ping para verificações de integridade. AgentCore O tempo de execução exige esse contrato para AG-UI contêineres.


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

Para obter exemplos completos e específicos da estrutura, consulte:

Entendendo o código

Streams de eventos: AG-UI usa Server-Sent Eventos (SSE) para transmitir eventos digitados para o cliente
/invocations Endpoint: Endpoint primário para HTTP/SSE comunicação (igual ao protocolo HTTP)
Porta 8080: AG-UI os servidores são executados na porta 8080 por padrão no AgentCore Runtime

Etapa 2: teste seu AG-UI servidor localmente

Execute e teste seu AG-UI servidor em um ambiente de desenvolvimento local.

Inicie seu AG-UI servidor

Execute seu AG-UI servidor localmente:


python my_agui_server.py

Você deve ver uma saída indicando que o servidor está sendo executado na porta8080.

Testar o endpoint

Teste o endpoint SSE com uma solicitação formatada AG-UI corretamente:


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

Você deve ver os fluxos de AG-UI eventos retornados no formato SSE, incluindo RUN_STARTEDTEXT_MESSAGE_CONTENT, e RUN_FINISHED eventos.

Etapa 3: implante seu AG-UI servidor no Bedrock AgentCore Runtime

Implante seu AG-UI servidor AWS usando a AgentCore CLI.

Instale ferramentas de implantação

Instale a AgentCore CLI:


npm install -g @aws/agentcore

Comece criando uma pasta de projeto com a seguinte estrutura:


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

Crie um novo arquivo chamado requirements.txt com suas dependências:


fastapi
uvicorn
ag-ui-strands

Configurar o grupo de usuários do Cognito para autenticação

Configure a autenticação para acesso seguro ao seu servidor implantado. Para obter instruções detalhadas de configuração do Cognito, consulte Configurar o grupo de usuários do Cognito para autenticação. Isso fornece os tokens OAuth necessários para acesso seguro ao servidor implantado.

Depois de concluir a configuração do Cognito, exporte os valores que o comando de implantação usa:


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

Configure seu AG-UI servidor para implantação

Crie um AgentCore projeto vazio. Em seguida, registre o servidor que você criou em Crie seu primeiro AG-UI servidor como um agente BYO com a configuração do Cognito da etapa anterior:


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

Os comandos registram a implementação existente com o AG-UI protocolo e a configuração do Cognito OAuth da etapa anterior.

Implantar em AWS

Implante seu agente:


agentcore deploy

Após a implantação, você receberá um ARN de tempo de execução do agente que se parece com:


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

Etapa 4: invocar seu servidor implantado AG-UI

Invoque seu AgentCore AG-UI servidor Amazon Bedrock implantado e interaja com os streams de eventos.

Configurar variáveis de ambiente

Exporte o token do portador como uma variável de ambiente. Para a configuração do token portador, consulte Configurar o grupo de usuários do Cognito para autenticação.
```
export BEARER_TOKEN="<BEARER_TOKEN>"
```

Exporte o ARN do agente.


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

Invoque o servidor AG-UI

Para invocar o AG-UI servidor programaticamente, escolha o idioma que corresponde ao seu cliente:

exemplo

Python

Instale os pacotes obrigatórios:


pip install httpx httpx-sse

Em seguida, use o seguinte código de cliente:


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

Instale os pacotes obrigatórios:


npm install @ag-ui/client

Em seguida, use o seguinte código de cliente:


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

Para criar aplicativos de interface de usuário completos, consulte CopilotKit o SDK AG-UI TypeScript do cliente.

Apêndice

Tópicos

Configurar o grupo de usuários do Cognito para autenticação
Solução de problemas

Configurar o grupo de usuários do Cognito para autenticação

Para obter instruções detalhadas de configuração do Cognito, consulte Configurar o grupo de usuários do Cognito para autenticação na documentação do MCP. O processo de configuração é idêntico para AG-UI servidores.

Solução de problemas

AG-UI-specific Problemas comuns

A seguir estão os problemas comuns que você pode encontrar:

Conflitos portuários: AG-UI os servidores devem ser executados na porta 8080 no AgentCore ambiente Runtime
Incompatibilidade do método de autorização: Certifique-se de que sua solicitação use o mesmo método de autenticação (OAuth ou SigV4) com o qual o agente foi configurado
Erros no formato do evento: Garanta que seus eventos sigam a especificação do AG-UI protocolo. Veja a documentação de AG-UI eventos

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Implemente servidores A2A

Use sessões isoladas para agentes