View a markdown version of this page

Obiettivi passthrough HTTP - Fondamento Amazon AgentCore
Configurazione del targetCreazione di un target HTTP passthroughRichiamo di un target HTTP passthroughMetodi HTTP supportatiAutorizzazione in uscita

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à.

Obiettivi passthrough HTTP

È possibile aggiungere un target HTTP passthrough per indirizzare il traffico attraverso il gateway verso qualsiasi endpoint HTTP. Il gateway inoltra le richieste all'endpoint di destinazione senza traduzione del protocollo, fungendo da livello proxy sicuro. Ciò rende le destinazioni passthrough ideali per fronteggiare gli URL degli agenti, le API esterne o qualsiasi servizio HTTP a cui desideri accedere tramite l'autenticazione centralizzata, l'applicazione delle policy e l'osservabilità del gateway.

L'aggiunta di un target HTTP passthrough al gateway è utile quando si desidera:

  • Servizi front agent (come agenti A2A, server MCP esterni o endpoint di inferenza personalizzati) dietro un singolo endpoint gateway con controllo degli accessi unificato.

  • Indirizza il traffico verso servizi esterni mentre il gateway gestisce l'autenticazione in entrata e l'iniezione delle credenziali in uscita.

  • Applica politiche del gateway come guardrail e controllo degli accessi alle richieste destinate agli endpoint esterni.

  • Usa il routing basato sul percorso (/{targetName}/{path}) per raggiungere più servizi esterni tramite un unico gateway.

Configurazione del target

Quando si crea un target HTTP passthrough, si fornisce l'URL dell'endpoint di destinazione e un tipo di protocollo che indica il protocollo applicativo implementato dalla destinazione. Il gateway utilizza il tipo di protocollo per l'osservabilità e la valutazione delle policy ma non esegue la traduzione del protocollo.

La configurazione di destinazione per una destinazione HTTP passthrough utilizza la seguente struttura:

{
    "http": {
        "passthrough": {
            "endpoint": "https://partner-agent.example.com",
            "protocolType": "A2A"
        }
    }
}

L'esempio seguente mostra un target passthrough con un protocollo personalizzato e uno schema API esplicito:

{
    "http": {
        "passthrough": {
            "endpoint": "https://my-service.example.com",
            "protocolType": "CUSTOM",
            "schema": {
                "source": {
                    "s3": {
                        "uri": "s3://DOC-EXAMPLE-BUCKET/service-schema.yaml"
                    }
                }
            }
        }
    }
}

  • endpoint (obbligatorio): l'URL HTTPS del servizio di destinazione. Il gateway inoltra le richieste a questo endpoint.

  • ProtocolType (obbligatorio): il protocollo applicativo implementato dalla destinazione. Valori validi:

    • MCP— La destinazione è un server MCP. Utilizzatelo quando effettuate il routing verso un singolo server MCP a cui desiderate accedere direttamente (non aggregato con altri target MCP).

    • A2A— Il target implementa il protocollo (A2A). Agent-to-Agent

    • INFERENCE— L'obiettivo è un endpoint di inferenza.

    • CUSTOM— Il target implementa un protocollo personalizzato o proprietario.

  • schema (opzionale) — Lo schema API che descrive la struttura di richiesta e risposta del target passthrough. Il gateway utilizza questo schema per abilitare le funzionalità del policy engine come i guardrail. Il formato dello schema viene rilevato automaticamente come OpenAPI o Smithy.

    I requisiti dello schema dipendono dal tipo di protocollo:

    • Per MCP tutti i tipi di A2A protocollo, viene applicato automaticamente uno schema predefinito. Non è necessario fornire uno schema a meno che non si desideri sovrascrivere quello predefinito.

    • Per i tipi di INFERENCE protocollo con provider noti (OpenAI, Anthropic o Amazon Bedrock), viene applicato uno schema predefinito basato sul dominio dell'endpoint.

    • Per i tipi di CUSTOM protocollo, è necessario fornire uno schema per utilizzare i guardrail.

      L'schemaoggetto contiene un file source che specifica dove si trova il contenuto dello schema:

    • s3 — Un URI S3 che punta al file dello schema (ad esempio,). s3://DOC-EXAMPLE-BUCKET/service-schema.yaml

    • inlinePayload — Il contenuto dello schema fornito direttamente come stringa.

Creazione di un target HTTP passthrough

Gli esempi seguenti creano un target passthrough che indirizza a diversi tipi di endpoint: un agente A2A, un server MCP esterno, un servizio IAM-authenticated interno e un'API esterna autenticata con una chiave API.

Esempio
AgentCore CLI

  1. Instradamento a un agente A2A utilizzando una credenziale OAuth:

    agentcore add gateway-target \
  --name partner-agent \
  --type passthrough \
  --passthrough-endpoint https://partner-agent.example.com \
  --passthrough-protocol A2A \
  --outbound-auth oauth \
  --credential-name partner-oauth \
  --gateway MyGateway
agentcore deploy

    Instradamento a un server MCP esterno utilizzando una credenziale OAuth:

    agentcore add gateway-target \
  --name slack-mcp \
  --type passthrough \
  --passthrough-endpoint https://mcp-slack.example.com \
  --passthrough-protocol MCP \
  --outbound-auth oauth \
  --credential-name slack-oauth \
  --gateway MyGateway
agentcore deploy

    Instradamento verso un servizio interno utilizzando l'autenticazione basata sui ruoli IAM (Sigv4), con un protocollo e uno schema S3: CUSTOM

    agentcore add gateway-target \
  --name internal-service \
  --type passthrough \
  --passthrough-endpoint https://internal-service.example.com \
  --passthrough-protocol CUSTOM \
  --schema s3://amzn-s3-demo-bucket/internal-service-schema.yaml \
  --signing-service execute-api \
  --signing-region us-west-2 \
  --gateway MyGateway
agentcore deploy

    Passa a un'API esterna e passa il JWT del chiamante:

    agentcore add gateway-target \
  --name external-api \
  --type passthrough \
  --passthrough-endpoint https://api.example.com \
  --passthrough-protocol CUSTOM \
  --outbound-auth jwt-passthrough \
  --gateway MyGateway
agentcore deploy
AWS CLI

  1. Inoltra verso un agente A2A utilizzando una credenziale OAuth:

    aws bedrock-agentcore-control create-gateway-target --cli-input-json '{
    "gatewayIdentifier": "GATEWAY_ID",
    "name": "partner-agent",
    "targetConfiguration": {
        "http": {
            "passthrough": {
                "endpoint": "https://partner-agent.example.com",
                "protocolType": "A2A"
            }
        }
    },
    "credentialProviderConfigurations": [
        {
            "credentialProviderType": "OAUTH",
            "credentialProvider": {
                "oauthCredentialProvider": {
                    "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/oauthcredentialprovider/partner-oauth"
                }
            }
        }
    ]
}'

    Instradamento a un server MCP esterno utilizzando una credenziale OAuth:

    aws bedrock-agentcore-control create-gateway-target --cli-input-json '{
    "gatewayIdentifier": "GATEWAY_ID",
    "name": "slack-mcp",
    "targetConfiguration": {
        "http": {
            "passthrough": {
                "endpoint": "https://mcp-slack.example.com",
                "protocolType": "MCP"
            }
        }
    },
    "credentialProviderConfigurations": [
        {
            "credentialProviderType": "OAUTH",
            "credentialProvider": {
                "oauthCredentialProvider": {
                    "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/oauthcredentialprovider/slack-oauth"
                }
            }
        }
    ]
}'

    Instradamento verso un servizio interno utilizzando l'autenticazione IAM basata sui ruoli, con un protocollo e uno CUSTOM schema S3:

    aws bedrock-agentcore-control create-gateway-target --cli-input-json '{
    "gatewayIdentifier": "GATEWAY_ID",
    "name": "internal-service",
    "targetConfiguration": {
        "http": {
            "passthrough": {
                "endpoint": "https://internal-service.example.com",
                "protocolType": "CUSTOM",
                "schema": {
                    "source": {
                        "s3": {
                            "uri": "s3://DOC-EXAMPLE-BUCKET/internal-service-schema.yaml"
                        }
                    }
                }
            }
        }
    },
    "credentialProviderConfigurations": [
        {"credentialProviderType": "GATEWAY_IAM_ROLE"}
    ]
}'

    Instradamento verso un'API esterna utilizzando una credenziale chiave API:

    aws bedrock-agentcore-control create-gateway-target --cli-input-json '{
    "gatewayIdentifier": "GATEWAY_ID",
    "name": "external-api",
    "targetConfiguration": {
        "http": {
            "passthrough": {
                "endpoint": "https://api.example.com",
                "protocolType": "CUSTOM"
            }
        }
    },
    "credentialProviderConfigurations": [
        {
            "credentialProviderType": "API_KEY",
            "credentialProvider": {
                "apiKeyCredentialProvider": {
                    "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/apikeycredentialprovider/my-api-key",
                    "credentialParameterName": "x-api-key"
                }
            }
        }
    ]
}'

Richiamo di un target HTTP passthrough

Per richiamare una destinazione passthrough HTTP tramite il gateway, inviate una richiesta alla destinazione utilizzando il routing basato sul percorso. Il formato dell'URL è:

https://{gatewayId}.gateway.bedrock-agentcore.{region}.amazonaws.com/{targetName}/{path}

Il gateway inoltra la richiesta {endpoint}/{path} alla destinazione. Sostituisci {gatewayId} con il tuo ID gateway, {region} con la AWS regione, {targetName} con il nome della destinazione e {path} con il percorso da inoltrare.

L'esempio seguente invia un messaggio A2A a un agente partner tramite il gateway:

curl -X POST https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/partner-agent/invocations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{
        "jsonrpc": "2.0",
        "id": "req-001",
        "method": "message/send",
        "params": {
            "message": {
                "role": "user",
                "parts": [{"kind": "text", "text": "What is the stock price of AMZN?"}],
                "messageId": "msg-001"
            }
        }
    }'

L'esempio seguente chiama un server MCP tramite il gateway:

curl -X POST https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/slack-mcp/mcp \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Metodi HTTP supportati

Il gateway supporta i metodi HTTP utilizzati dai protocolli implementati dai target passthrough: server MCP, agenti A2A ed endpoint di inferenza. Questi protocolli si basano su un sottoinsieme specifico di metodi per richiamare servizi e indirizzare il traffico.

Il gateway supporta i seguenti metodi HTTP:

  • POST— Utilizzato da tutti i protocolli di destinazione passthrough come metodo principale. MCP utilizza POST per JSON-RPC i messaggi, A2A utilizza POST per l'invio di messaggi e la gestione delle attività e gli endpoint di inferenza utilizzano POST per i completamenti e le richieste di chat.

  • GET— Utilizzato da MCP per gli abbonamenti allo stream SSE, da A2A per recuperare lo stato delle attività e elencare le attività e dagli endpoint di inferenza per i modelli di elenco.

  • DELETE— Utilizzato da A2A per rimuovere le configurazioni delle notifiche push e dagli endpoint di inferenza per eliminare le risorse.

Il gateway non supportaPATCH,, o metodi. PUT HEAD OPTIONS Le destinazioni Passthrough sono progettate per richiamare servizi e indirizzare il traffico e questi metodi non rientrano in tale ambito.

Se un client invia una richiesta con un metodo HTTP non supportato, il gateway restituisce un errore.

Autorizzazione in uscita

Le destinazioni HTTP passthrough supportano i seguenti tipi di autorizzazione in uscita:

  • IAM (Sigv4) (GATEWAY_IAM_ROLE): il gateway assume il ruolo di servizio gateway per firmare le richieste alla destinazione.

  • OAuth (OAUTH): il gateway recupera i token OAuth dai provider di credenziali configurati nella destinazione tramite il servizio di identità Amazon Bedrock. AgentCore

  • Credenziali IAM del chiamante (CALLER_IAM_CREDENTIALS): il gateway utilizza l'identità IAM e le autorizzazioni del chiamante per firmare le richieste alla destinazione utilizzando SigV4. Disponibile solo per gateway con o tipo di autorizzazione. AWS_IAM AUTHENTICATE_ONLY

  • Token passthrough (JWT_PASSTHROUGH): il gateway convalida il token in entrata e lo passa alla destinazione senza modifiche.

  • Chiave API (API_KEY): il gateway recupera una chiave API da un provider di credenziali configurato nel token vault e la inserisce nelle richieste in uscita come intestazione di richiesta specificata.