Konfigurasi target Membuat target passthrough HTTP Memanggil target passthrough HTTP Metode HTTP yang didukung Otorisasi 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 URL agen fronting, API eksternal, atau layanan HTTP apa pun yang ingin Anda akses melalui otentikasi terpusat gateway, penegakan kebijakan, dan pengamatan.

Menambahkan target passthrough HTTP ke gateway Anda berguna ketika 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.
Arahkan lalu lintas ke layanan eksternal sementara gateway mengelola otentikasi masuk dan injeksi kredensia keluar.
Terapkan 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 diterapkan target. Gateway menggunakan tipe protokol untuk pengamatan 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 khusus 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 (required) — URL HTTPS dari layanan target. Gateway meneruskan permintaan ke titik akhir ini.
ProtocolType (required) — Protokol aplikasi yang diimplementasikan 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).
- INFERENCE— Target adalah titik akhir inferensi.
- CUSTOM— Target mengimplementasikan protokol khusus atau eksklusif.
skema (opsional) — Skema API yang menjelaskan permintaan target passthrough dan struktur respons. 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 A2A tipe protokol, skema default diterapkan secara otomatis. Anda tidak perlu menyediakan skema kecuali Anda ingin mengganti defaultnya.
- Untuk jenis INFERENCE protokol dengan penyedia terkenal (OpenAI, Anthropic, atau Amazon Bedrock), skema default diterapkan berdasarkan domain titik akhir.
- Untuk jenis CUSTOM protokol, Anda harus menyediakan skema untuk menggunakan pagar pembatas.
  
  Ob schema jek berisi a source yang menentukan di mana konten skema berada:
- s3 — URI S3 menunjuk ke file skema (misalnya,s3://DOC-EXAMPLE-BUCKET/service-schema.yaml).
- inlinePayLoad — Konten skema 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

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 otentikasi berbasis peran IAM (SIGv4), dengan CUSTOM protokol dan skema S3:


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 dan berikan JWT pemanggil:


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

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

Metode HTTP yang didukung

Gateway mendukung metode HTTP yang digunakan oleh protokol yang diterapkan target passthrough: server MCP, agen A2A, dan titik akhir inferensi. Protokol ini bergantung pada subset metode tertentu untuk memanggil layanan dan routing lalu lintas.

Gateway mendukung metode HTTP berikut:

POST— Digunakan oleh semua protokol target passthrough sebagai metode utama. MCP menggunakan POST untuk JSON-RPC pesan, A2A menggunakan POST untuk mengirim pesan dan mengelola tugas, dan titik akhir inferensi menggunakan POST untuk penyelesaian dan permintaan obrolan.
GET- Digunakan oleh MCP untuk langganan aliran SSE, oleh A2A untuk mengambil status tugas dan daftar tugas, dan oleh titik akhir inferensi untuk daftar model.
DELETE- Digunakan oleh A2A untuk menghapus konfigurasi pemberitahuan push dan dengan titik akhir inferensi untuk menghapus sumber daya.

Gateway tidak mendukungPATCH,PUT,HEAD, atau OPTIONS metode. Target passthrough dirancang untuk memanggil layanan dan merutekan lalu lintas, dan metode ini berada di luar cakupan itu.

Jika klien mengirim permintaan dengan metode HTTP yang tidak didukung, gateway mengembalikan kesalahan.

Otorisasi keluar

Target passthrough HTTP mendukung jenis otorisasi keluar berikut:

IAM (SIGv4) (GATEWAY_IAM_ROLE) — Gateway mengambil peran layanan gateway untuk menandatangani permintaan ke target.
OAuth (OAUTH) — Gateway mengambil token OAuth dari penyedia kredensia yang dikonfigurasi di target melalui layanan identitas Amazon Bedrock. AgentCore
Caller IAM (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 jenis AUTHENTICATE_ONLY otorizer.
Token passthrough (JWT_PASSTHROUGH) — Gateway memvalidasi token masuk dan meneruskannya ke target tanpa modifikasi.
API key (API_KEY) — Gateway mengambil kunci API dari penyedia kredensia yang dikonfigurasi di brankas token dan menyuntikkannya ke permintaan keluar sebagai header permintaan tertentu.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

AgentCore Waktu pelaksanaan

Target inferensi