Configurazione dell'obiettivo Creazione di un target HTTP passthrough Richiamo di un target HTTP passthrough Autorizzazione in uscita

obiettivi HTTP passthrough

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

L'aggiunta di una destinazione passthrough HTTP al gateway è utile quando si desidera:

Servizi di 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 di credenziali in uscita.
Applica politiche di gateway come guardrail e controllo degli accessi alle richieste destinate agli endpoint esterni.
Utilizza il routing basato sul percorso (/{targetName}/{path}) per raggiungere più servizi esterni tramite un unico gateway.

Configurazione dell'obiettivo

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 dal target. Il gateway utilizza il tipo di protocollo per l'osservabilità e la valutazione delle politiche, ma non esegue la traduzione del protocollo.

La configurazione di destinazione per un target 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 dal target. Valori validi:
- MCP— La destinazione è un server MCP. Utilizzatelo per il routing verso un singolo server MCP a cui desiderate accedere direttamente (non aggregato con altre destinazioni 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 dell'API che descrive la struttura di richiesta e risposta del target passthrough. Il gateway utilizza questo schema per abilitare le funzionalità del motore di policy come i guardrails. 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 sostituire 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 uno source che specifica dove si trova il contenuto dello schema:
- s3 — Un URI S3 che punta al file di 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 verso 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

Effettua il routing verso 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

Instradate verso 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

Effettua il routing verso un'API esterna utilizzando una credenziale di chiave API:


agentcore add gateway-target \
  --name external-api \
  --type passthrough \
  --passthrough-endpoint https://api.example.com \
  --passthrough-protocol CUSTOM \
  --outbound-auth api-key \
  --credential-name my-api-key \
  --credential-parameter-name x-api-key \
  --gateway MyGateway
agentcore deploy

AWS CLI

Indirizza 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"
                }
            }
        }
    ]
}'

Instradate verso 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"
                }
            }
        }
    ]
}'

Instradate verso un servizio interno utilizzando l'autenticazione basata sui ruoli IAM, 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"}
    ]
}'

Effettua il routing verso un'API esterna utilizzando una credenziale di 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 HTTP passthrough tramite il gateway, invia 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. Sostituiscilo {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"}'

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 verso la 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à e le autorizzazioni IAM del chiamante per firmare le richieste alla destinazione utilizzando SigV4. Disponibile solo per i gateway con o tipo di autorizzazione. AWS_IAM AUTHENTICATE_ONLY
Token passthrough (JWT_PASSTHROUGH): il gateway convalida il token in entrata e lo trasmette 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.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

AgentCore Runtime

Obiettivi di inferenza