View a markdown version of this page

Target passthrough HTTP - Batuan Dasar Amazon AgentCore
Konfigurasi targetMembuat target passthrough HTTPMemanggil target passthrough HTTPOtorisasi keluar

Target passthrough HTTP

Anda dapat menambahkan target passthrough HTTP untuk merutekan lalu lintas melalui gateway ke titik akhir HTTP apa pun. Gateway meneruskan permintaan ke titik akhir target tanpa terjemahan protokol, bertindak sebagai lapisan proxy yang aman. Hal ini membuat target passthrough ideal untuk memajukan URL agen, API eksternal, atau layanan HTTP apa pun yang ingin Anda akses melalui autentikasi terpusat gateway, penegakan kebijakan, dan observabilitas.

Menambahkan target passthrough HTTP ke gateway Anda berguna saat Anda ingin:

  • Layanan agen depan (seperti agen A2A, server MCP eksternal, atau titik akhir inferensi kustom) di belakang titik akhir gateway tunggal dengan kontrol akses terpadu.

  • Rutekan lalu lintas ke layanan eksternal sementara gateway mengelola otentikasi masuk dan injeksi kredenal keluar.

  • Menerapkan kebijakan gateway seperti pagar pembatas dan kontrol akses ke permintaan yang ditujukan untuk titik akhir eksternal.

  • Gunakan routing berbasis jalur (/{targetName}/{path}) untuk menjangkau beberapa layanan eksternal melalui satu gateway.

Konfigurasi target

Saat Anda membuat target passthrough HTTP, Anda memberikan URL titik akhir target dan jenis protokol yang menunjukkan protokol aplikasi yang diimplementasikan target. Gateway menggunakan jenis protokol untuk observabilitas dan evaluasi kebijakan tetapi tidak melakukan terjemahan protokol.

Konfigurasi target untuk target passthrough HTTP menggunakan struktur berikut:

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

Contoh berikut menunjukkan target passthrough dengan protokol kustom dan skema API eksplisit:

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

  • endpoint (wajib) — URL HTTPS dari layanan target. Gateway meneruskan permintaan ke titik akhir ini.

  • ProtocolType (wajib) — Protokol aplikasi yang diterapkan target. Nilai valid:

    • MCPTargetnya adalah server MCP. Gunakan ini saat merutekan ke server MCP tunggal yang ingin Anda akses secara langsung (tidak digabungkan dengan target MCP lainnya).

    • A2A— Target mengimplementasikan protokol Agent-to-Agent (A2A).

    • INFERENCETargetnya adalah titik akhir inferensi.

    • CUSTOM— Target mengimplementasikan protokol khusus atau berpemilik.

  • skema (opsional) - Skema API yang menjelaskan permintaan dan struktur respons target passthrough. Gateway menggunakan skema ini untuk mengaktifkan fitur mesin kebijakan seperti pagar pembatas. Format skema terdeteksi secara otomatis sebagai OpenAPI atau Smithy.

    Persyaratan skema tergantung pada jenis protokol:

    • Untuk MCP dan jenis A2A protokol, skema default diterapkan secara otomatis. Anda tidak perlu menyediakan skema kecuali Anda ingin mengganti default.

    • Untuk jenis INFERENCE protokol dengan penyedia terkenal (OpenAI, Anthropic, atau Amazon Bedrock), skema default diterapkan berdasarkan domain endpoint.

    • Untuk jenis CUSTOM protokol, Anda harus menyediakan skema untuk menggunakan pagar pembatas.

      schemaObjek berisi a source yang menentukan di mana konten skema berada:

    • s3 — URI S3 yang menunjuk ke file skema (misalnya,). s3://DOC-EXAMPLE-BUCKET/service-schema.yaml

    • InlinePayLoad - Konten skema yang disediakan langsung sebagai string.

Membuat target passthrough HTTP

Contoh berikut membuat target passthrough yang merutekan ke berbagai jenis titik akhir: agen A2A, server MCP eksternal, layanan IAM-authenticated internal, dan API eksternal yang diautentikasi dengan kunci API.

contoh
AgentCore CLI

  1. Rute ke agen A2A menggunakan kredensi 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

    Rute ke server MCP eksternal menggunakan kredensi 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

    Rute ke layanan internal menggunakan autentikasi berbasis peran IAM (SiGv4), dengan protokol dan skema 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

    Rute ke API eksternal menggunakan kredensi kunci 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

  1. Rute ke agen A2A menggunakan kredensi 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"
                }
            }
        }
    ]
}'

    Rute ke server MCP eksternal menggunakan kredensi 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"
                }
            }
        }
    ]
}'

    Rute ke layanan internal menggunakan otentikasi berbasis peran IAM, dengan CUSTOM protokol dan skema 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"}
    ]
}'

    Rute ke API eksternal menggunakan kredensi kunci 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"
                }
            }
        }
    ]
}'

Memanggil target passthrough HTTP

Untuk memanggil target passthrough HTTP melalui gateway, kirim permintaan ke target menggunakan routing berbasis jalur. Format URL adalah:

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

Gateway meneruskan permintaan ke {endpoint}/{path} target. Ganti {gatewayId} dengan ID gateway Anda, {region} dengan AWS Wilayah, {targetName} dengan nama target, dan {path} dengan jalur untuk meneruskan.

Contoh berikut mengirimkan pesan A2A ke agen mitra melalui 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"
            }
        }
    }'

Contoh berikut memanggil server MCP melalui 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"}'

Otorisasi keluar

Target passthrough HTTP mendukung jenis otorisasi keluar berikut:

  • IAM (SiGv4) (GATEWAY_IAM_ROLE) — Gateway mengasumsikan peran layanan gateway untuk menandatangani permintaan ke target.

  • OAuth (OAUTH) — Gateway mengambil token OAuth dari penyedia kredensi yang dikonfigurasi dalam target melalui layanan identitas Amazon Bedrock. AgentCore

  • Caller IAM credentials (CALLER_IAM_CREDENTIALS) — Gateway menggunakan identitas IAM dan izin pemanggil untuk menandatangani permintaan ke target menggunakan SigV4. Hanya tersedia untuk gateway dengan AWS_IAM atau tipe AUTHENTICATE_ONLY otorisasi.

  • Token passthrough (JWT_PASSTHROUGH) — Gateway memvalidasi token masuk dan meneruskannya ke target tanpa modifikasi.

  • Kunci API (API_KEY) — Gateway mengambil kunci API dari penyedia kredensyal yang dikonfigurasi di brankas token dan menyuntikkannya ke permintaan keluar sebagai header permintaan yang ditentukan.