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à.
Definire la configurazione della destinazione del gateway
La configurazione della destinazione dipende dal tipo di destinazione che stai aggiungendo al gateway. Per ulteriori informazioni sui tipi di destinazione dei gateway supportati, consulta Obiettivi supportati per i AgentCore gateway Amazon Bedrock.
Seleziona un argomento per visualizzare esempi di aggiunta di un tipo di destinazione:
Aggiungi un target Lambda
Puoi aggiungere un target Lambda al tuo gateway utilizzando la AgentCore CLI specificando l'--typeas lambda-function-arn e fornendo l'ARN Lambda e un file di schema dello strumento.
Configurazione del target
La configurazione di destinazione (o payload) per una funzione Lambda contiene i seguenti campi:
Per ulteriori informazioni sui target Lambda, vedere AWS Lambda function targets.
Seleziona uno dei seguenti metodi:
Esempio
- AgentCore CLI
-
-
Per aggiungere una funzione Lambda come destinazione, esegui agentcore add gateway-target con l'--type lambda-function-arnopzione. Fornisci l'ARN Lambda e un file JSON contenente lo schema dello strumento:
agentcore add gateway-target \
--name MyLambdaTarget \
--type lambda-function-arn \
--lambda-arn arn:aws:lambda:us-east-1:123456789012:function:MyFunction \
--tool-schema-file tools.json \
--gateway MyGateway
agentcore deploy
Per le lambda-function-arn destinazioni, fornisci lo schema dello strumento alla CLI AgentCore con. --tool-schema-file Per AgentCore Python SDK e Boto3, fornisci allo schema dello strumento. inlinePayload
- AgentCore Python SDK
-
-
Con AgentCore Python SDK, puoi creare un AWS target Lambda con configurazioni predefinite.
# Import dependencies
from bedrock_agentcore_starter_toolkit.operations.gateway.client import GatewayClient
# Initialize the client
client = GatewayClient(region_name="us-east-1")
# Create a lambda target.
lambda_target = client.create_mcp_gateway_target(
gateway=gateway,
name=None, # If you don't set one, one will be generated.
target_type="lambda",
target_payload=None, # Define your own lambda if you pre-created one. Otherwise leave this as None and one will be created for you.
credentials=None, # If you leave this as None, one will be created for you
)
Di seguito è riportato un argomento di esempio che puoi fornire per. target_payload Se si omette l'target_payloadargomento, viene utilizzato questo payload:
{
"lambdaArn": "<insert your lambda arn>",
"toolSchema": {
"inlinePayload": [
{
"name": "get_weather",
"description": "Get weather for a location",
"inputSchema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location e.g. seattle, wa"
}
},
"required": [
"location"
]
}
},
{
"name": "get_time",
"description": "Get time for a timezone",
"inputSchema": {
"type": "object",
"properties": {
"timezone": {
"type": "string"
}
},
"required": [
"timezone"
]
}
}
]
}
}
- Boto3
-
-
Il seguente codice Python mostra come aggiungere un target Lambda utilizzando AWS Python SDK (Boto3):
import boto3
# Create the agentcore client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create a Lambda target
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="LambdaTarget",
targetConfiguration={
"mcp": {
"lambda": {
"lambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:YourLambdaFunction",
"toolSchema": {
"inlinePayload": [
{
"name": "get_weather",
"description": "Get weather for a location",
"inputSchema": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
},
{
"name": "get_time",
"description": "Get time for a timezone",
"inputSchema": {
"type": "object",
"properties": {"timezone": {"type": "string"}},
"required": ["timezone"],
},
},
]
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]
)
- Interactive
-
-
Nell'interfaccia utente interattiva del terminale AgentCore CLI, agentcore esegui, seleziona aggiungi, scegli Gateway Target , quindi seleziona la funzione Lambda:
La procedura guidata richiede quindi il nome della destinazione, l'ARN della funzione Lambda, il file dello schema dello strumento e la configurazione dell'autorizzazione in uscita.
Aggiungi una destinazione di fase API Gateway
Per aggiungere una fase di un'API REST API Gateway come destinazione, specifica l'ARN dell'API e della fase e definisci le impostazioni per filtrare gli strumenti nell'API gateway o per sovrascrivere i nomi e le descrizioni degli strumenti nel gateway:
Gli esempi seguenti mostrano come aggiungere una destinazione API Gateway. Vengono inoltre applicate le seguenti configurazioni:
Seleziona uno dei seguenti metodi:
Esempio
- AgentCore CLI
-
-
Per aggiungere uno stage API Gateway REST API come destinazione, esegui agentcore add gateway-target con l'--type api-gatewayopzione:
agentcore add gateway-target \
--name MyAPIGatewayTarget \
--type api-gateway \
--rest-api-id your-rest-api-id \
--stage your-stage \
--gateway MyGateway
agentcore deploy
- AWS CLI
-
-
Il comando seguente utilizza la AWS CLI:
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "SearchAPITarget" \
--target-configuration '{
"mcp": {
"apiGateway": {
"restApiId": "your-rest-api-id",
"stage": "your-stage",
"apiGatewayToolConfiguration": {
"toolFilters": [
{
"filterPath": "/products",
"methods": [
"GET",
"POST"
]
}
],
"toolOverrides": [
{
"path": "/products",
"method": "GET",
"name": "get_items",
"description": "Gets information for items in the list of products."
}
]
}
}
}
}'
--credential-provider-configurations '[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]'
- Boto3
-
-
Il codice seguente mostra gli usi di AWS Python SDK (Boto3):
import boto3
# Create the client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create an API gateway REST API target with gateway service role authentication
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="SearchAPITarget",
targetConfiguration={
"mcp": {
"apiGateway": {
"restApiId": "your-rest-api-id",
"stage": "your-stage",
"apiGatewayToolConfiguration": {
"toolFilters": [
{
"filterPath": "/products",
"methods": [
"GET",
"POST"
]
}
],
"toolOverrides": [
{
"path": "/products",
"method": "GET",
"name": "get_item",
"description": "Gets information for a specific item in the product list."
}
]
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]
)
- Interactive
-
-
Nell'interfaccia utente interattiva del terminale AgentCore CLI, esegui, seleziona aggiungiagentcore, scegli Gateway Target , quindi seleziona API Gateway REST API:
La procedura guidata richiede quindi il nome della destinazione, l'ID API REST, la fase e la configurazione dell'autorizzazione in uscita.
Aggiungi un target OpenAPI
Seleziona uno dei seguenti metodi:
Esempio
- AgentCore CLI
-
-
Per aggiungere una destinazione dello schema OpenAPI, esegui agentcore add gateway-target con l'--type open-api-schemaopzione e fornisci il percorso del file delle specifiche OpenAPI:
agentcore add gateway-target \
--name MyOpenAPITarget \
--type open-api-schema \
--schema path/to/openapi-spec.json \
--outbound-auth none|api-key|oauth \
--gateway MyGateway
agentcore deploy
- Boto3
-
-
Il seguente codice Python mostra come aggiungere un target OpenAPI utilizzando AWS Python SDK (Boto3). Lo schema è stato caricato in una posizione S3 il cui URI è referenziato in. target_payload L'autorizzazione in uscita per il target avviene tramite una chiave API.
import boto3
# Create the client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create an OpenAPI target with API Key authentication
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="SearchAPITarget",
targetConfiguration={
"mcp": {
"openApiSchema": {
"s3": {
"uri": "s3://your-bucket/path/to/open-api-spec.json",
"bucketOwnerAccountId": "123456789012"
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "API_KEY",
"credentialProvider": {
"apiKeyCredentialProvider": {
"providerArn": "arn:aws:agent-credential-provider:us-east-1:123456789012:token-vault/default/apikeycredentialprovider/abcdefghijk",
"credentialLocation": "HEADER",
"credentialParameterName": "X-API-Key"
}
}
}
]
)
- Interactive
-
-
Nell'interfaccia utente interattiva del terminale AgentCore CLI, eseguiagentcore, seleziona aggiungi, scegli Gateway Target, quindi seleziona OpenAPI Schema:
La procedura guidata richiede quindi il nome della destinazione, il percorso del file di specifiche OpenAPI e la configurazione dell'autorizzazione in uscita.
Aggiungi un bersaglio Smithy
Seleziona uno dei seguenti metodi:
Esempio
- AgentCore CLI
-
-
Per aggiungere un target del modello Smithy, utilizzate l'--type smithy-modelopzione e agentcore add gateway-target fornite il percorso del file del modello Smithy:
agentcore add gateway-target \
--name MySmithyTarget \
--type smithy-model \
--schema path/to/smithy-model.json \
--gateway MyGateway
agentcore deploy
- Boto3
-
-
Il seguente codice Python mostra come aggiungere un target del modello Smithy utilizzando Python SDK (Boto3): AWS
import boto3
# Create the agentcore client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create a Smithy model target
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="DynamoDBTarget",
targetConfiguration={
"mcp": {
"smithyModel": {
"s3": {
"uri": "s3://your-bucket/path/to/smithy-model.json",
"bucketOwnerAccountId": "123456789012"
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]
)
- Interactive
-
-
Nell'interfaccia utente interattiva del terminale AgentCore CLI, esegui, seleziona aggiungi, scegli Gateway agentcore Target, quindi seleziona Smithy Model:
La procedura guidata richiede quindi il nome della destinazione, il percorso del file del modello Smithy e la configurazione dell'autorizzazione in uscita.
Aggiungi un target di runtime HTTP
Puoi aggiungere un agente Amazon Bedrock AgentCore Runtime come destinazione HTTP al tuo gateway. Il gateway invia il traffico direttamente all'agente di runtime senza aggregazione o traduzione del protocollo.
Per ulteriori informazioni sui target HTTP, consulta gli obiettivi di Amazon Bedrock AgentCore Runtime.
Seleziona uno dei seguenti metodi:
Esempio
- AWS CLI
-
-
Il comando seguente crea un target di runtime HTTP con autorizzazione IAM:
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "MyRuntimeTarget" \
--description "Runtime gateway target" \
--target-configuration '{
"http": {
"agentcoreRuntime": {
"arn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
}
}
}' \
--credential-provider-configurations '[{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}]'
- Boto3
-
-
Il seguente codice Python mostra come aggiungere un target di runtime HTTP utilizzando AWS Python SDK (Boto3):
import boto3
agentcore_client = boto3.client('bedrock-agentcore-control')
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="MyRuntimeTarget",
description="Runtime gateway target",
targetConfiguration={
"http": {
"agentcoreRuntime": {
"arn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]
)
Aggiungi una destinazione del server MCP
È possibile aggiungere una destinazione server MCP utilizzando la AgentCore CLI o AWS Python SDK (Boto3). Gli esempi seguenti mostrano come creare una destinazione server MCP con diversi tipi di autorizzazione in uscita.
Server MCP con autorizzazione IAM (Sigv4)
L'esempio seguente crea una destinazione del server MCP con autorizzazione IAM. Il gateway firma le richieste al server MCP utilizzando SIGv4 con le credenziali del ruolo del servizio gateway. È necessario specificare il nome per la firma. service regionÈ facoltativo e per impostazione predefinita è la regione del gateway.
Il valore di service dipende da dove è ospitato il server MCP. I seguenti sono valori comuni:
-
bedrock-agentcore— Per i server MCP ospitati su Amazon Bedrock AgentCore, ad esempio il runtime (vedi Distribuire i server MCP in AgentCore Runtime) o un altro gateway.
-
execute-api— Per i server MCP dietro Amazon API Gateway.
-
lambda— Per i server MCP dietro gli URL di Lambda Function.
Seleziona uno dei seguenti metodi:
Esempio
- AWS CLI
-
-
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "MyMCPTarget" \
--target-configuration '{
"mcp": {
"mcpServer": {
"endpoint": "https://my-server.bedrock-agentcore.us-west-2.api.aws"
}
}
}' \
--credential-provider-configurations '[{
"credentialProviderType": "GATEWAY_IAM_ROLE",
"credentialProvider": {
"iamCredentialProvider": {
"service": "bedrock-agentcore",
"region": "us-west-2"
}
}
}]'
- Interactive
-
-
Nell'interfaccia utente del terminale interattivo AgentCore CLI, eseguiagentcore, seleziona Aggiungi, scegli Gateway Target, quindi seleziona MCP Server endpoint:
La procedura guidata richiede quindi il nome della destinazione, l'URL dell'endpoint del server MCP e la configurazione dell'autorizzazione in uscita.
- Boto3
-
-
import boto3
agentcore_client = boto3.client('bedrock-agentcore-control')
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="MyMCPTarget",
targetConfiguration={
"mcp": {
"mcpServer": {
"endpoint": "https://my-server.bedrock-agentcore.us-west-2.api.aws"
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE",
"credentialProvider": {
"iamCredentialProvider": {
"service": "bedrock-agentcore",
"region": "us-west-2"
}
}
}
]
)
Server MCP con autorizzazione OAuth
L'esempio seguente crea una destinazione server MCP con autorizzazione OAuth (credenziali client).
Seleziona uno dei seguenti metodi:
Esempio
- AWS CLI
-
-
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "MyMCPTarget" \
--target-configuration '{
"mcp": {
"mcpServer": {
"endpoint": "https://my-mcp-server.example.com"
}
}
}' \
--credential-provider-configurations '[{
"credentialProviderType": "OAUTH",
"credentialProvider": {
"oauthCredentialProvider": {
"providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/oauth2credentialprovider/my-oauth-provider",
"scopes": []
}
}
}]'
- AgentCore CLI
-
-
Per aggiungere una destinazione server MCP con autorizzazione OAuth, utilizzate l'--type mcp-serveropzione e specificate agentcore add gateway-target le credenziali OAuth:
agentcore add gateway-target \
--type mcp-server \
--name MyMCPTarget \
--endpoint https://my-mcp-server.example.com \
--gateway MyGateway \
--outbound-auth oauth \
--oauth-client-id my-client \
--oauth-client-secret my-secret \
--oauth-discovery-url https://auth.example.com/.well-known/openid-configuration
agentcore deploy
- Boto3
-
-
import boto3
agentcore_client = boto3.client('bedrock-agentcore-control')
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="MyMCPTarget",
targetConfiguration={
"mcp": {
"mcpServer": {
"endpoint": "https://my-mcp-server.example.com"
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "OAUTH",
"credentialProvider": {
"oauthCredentialProvider": {
"providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/oauth2credentialprovider/my-oauth-provider",
"scopes": []
}
}
}
]
)
Server MCP con autorizzazione tramite chiave API
L'esempio seguente crea una destinazione server MCP con autorizzazione tramite chiave API.
Selezionate uno dei seguenti metodi:
Esempio
- AWS CLI
-
-
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "MyMCPTarget" \
--target-configuration '{
"mcp": {
"mcpServer": {
"endpoint": "https://my-mcp-server.example.com"
}
}
}' \
--credential-provider-configurations '[{
"credentialProviderType": "API_KEY",
"credentialProvider": {
"apiKeyCredentialProvider": {
"providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-api-key",
"credentialLocation": "HEADER",
"credentialParameterName": "x-api-key",
"credentialPrefix": ""
}
}
}]'
- Boto3
-
-
import boto3
agentcore_client = boto3.client('bedrock-agentcore-control')
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="MyMCPTarget",
targetConfiguration={
"mcp": {
"mcpServer": {
"endpoint": "https://my-mcp-server.example.com"
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "API_KEY",
"credentialProvider": {
"apiKeyCredentialProvider": {
"providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-api-key",
"credentialLocation": "HEADER",
"credentialParameterName": "x-api-key",
"credentialPrefix": ""
}
}
}
]
)
Aggiungi un obiettivo Connector con Amazon Bedrock Managed Knowledge Base
Puoi aggiungere il connettore Amazon Bedrock Managed Knowledge Bases come destinazione al tuo gateway.
Per ulteriori informazioni sul connettore Amazon Bedrock Managed Knowledge Bases, consulta Amazon Bedrock Managed Knowledge Bases.
Configura una knowledge base gestita
Il connettore presenta due strumenti, ciascuno denominato in base alla relativa operazione di backend: AgenticRetrieveStream (recupero tramite agente di streaming in più fasi) e Retrieve (una singola ricerca ibrida). È possibile aggiungere una voce di configurazione per strumento.
PerAgenticRetrieveStream, imposta retrievers (le knowledge base gestite su cui interrogare) e agenticRetrieveConfiguration accediparameterValues. Entrambi sono obbligatori: l'omissione agenticRetrieveConfiguration causa un errore di runtime. Può essere un oggetto vuoto ({}) per accettare le impostazioni predefinite gestite dal servizio, ma specifica foundationModelType e rende esplicita la configurazione. rerankingModelType L'agente non fornisce gli ID della knowledge base al momento della chiamata. PerRetrieve, imposta il knowledgeBaseId codice inparameterValues; è obbligatorio.
Il connettore supporta solo le knowledge base gestite. Le destinazioni del connettore supportano solo il tipo di provider di GATEWAY_IAM_ROLE credenziali.
Esempio
- Boto3
-
-
Il seguente codice Python mostra come creare un Gateway Target con la configurazione del connettore Amazon Bedrock Managed Knowledge Bases utilizzando l'SDK AWS Python (Boto3):
import boto3
gateway_client = boto3.client("bedrock-agentcore-control", region_name="<REGION>")
gateway_client.create_gateway_target(
name="managed-kb",
gatewayIdentifier="<GATEWAY_ID>",
targetConfiguration={
"mcp": {
"connector": {
"source": {"connectorId": "bedrock-knowledge-bases"},
"configurations": [
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{
"description": "Product documentation",
"configuration": {"knowledgeBase": {"knowledgeBaseId": "<KB_ID_1>"}},
},
{
"description": "Engineering runbooks",
"configuration": {"knowledgeBase": {"knowledgeBaseId": "<KB_ID_2>"}},
},
],
"agenticRetrieveConfiguration": {
"foundationModelType": "MANAGED",
"rerankingModelType": "MANAGED",
},
},
},
{
"name": "Retrieve",
"parameterValues": {"knowledgeBaseId": "<KB_ID>"},
},
],
}
}
},
credentialProviderConfigurations=[
{"credentialProviderType": "GATEWAY_IAM_ROLE"}
],
)
- AWS CLI
-
-
Il comando seguente crea un Gateway Target con la configurazione del connettore Amazon Bedrock Managed Knowledge Bases utilizzando la CLI: AWS
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "<GATEWAY_ID>" \
--name "managed-kb" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "bedrock-knowledge-bases"
},
"configurations": [
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{
"description": "Product documentation",
"configuration": {"knowledgeBase": {"knowledgeBaseId": "<KB_ID_1>"}}
},
{
"description": "Engineering runbooks",
"configuration": {"knowledgeBase": {"knowledgeBaseId": "<KB_ID_2>"}}
}
],
"agenticRetrieveConfiguration": {
"foundationModelType": "MANAGED",
"rerankingModelType": "MANAGED"
}
}
},
{
"name": "Retrieve",
"parameterValues": {
"knowledgeBaseId": "<KB_ID>"
}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region "<REGION>"
- AgentCore CLI
-
-
Per aggiungere una destinazione del connettore della knowledge base gestita, agentcore add gateway-target esegui con: --type connector --connector bedrock-knowledge-bases
agentcore add gateway-target \
--name MyKnowledgeBaseTarget \
--type connector \
--connector bedrock-knowledge-bases \
--knowledge-base-id <KB_ID> \
--gateway MyGateway
agentcore deploy
- Interactive
-
-
Nell'interfaccia utente interattiva del terminale AgentCore CLI, eseguiagentcore add gateway-target, quindi seleziona Amazon Bedrock Knowledge Bases dal selettore del tipo di destinazione:
La procedura guidata richiede un nome, una descrizione e consente di selezionare uno o più tipi e fonti di fonte.
Dopo la chiamataCreateGatewayTarget, il Gateway convalida la configurazione in modo asincrono (in genere entro circa 30 secondi), il che include un GetKnowledgeBase controllo su ogni knowledge base associata. Effettua il GetGatewayTarget polling fino a quando status FAILED lo stato include un motivo che descrive il problema. READY
Per personalizzare l'agentic retrieval, ad esempio per limitare le iterazioni di pianificazione o collegare un guardrail, aggiungi i campi opzionali a. agenticRetrieveConfiguration Se li ometti, si applicano le impostazioni predefinite gestite dal servizio. Per tutti i valori accettati, vedere Riferimento alla configurazione. Informazioni di riferimento sulla configurazione
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{ "configuration": { "knowledgeBase": { "knowledgeBaseId": "<KB_ID>" } } }
],
"agenticRetrieveConfiguration": {
"maxAgentIteration": 5,
"policyConfiguration": {
"guardrailConfiguration": {
"guardrailId": "<GUARDRAIL_ID>",
"guardrailVersion": "1"
}
}
}
}
}
Controlla quali parametri l'agente può impostare
Ogni voce di configurazione dello strumento accetta due controlli dei parametri che determinano ciò che vede l'agente chiamante e ciò che il Gateway invia alla knowledge base:
-
parameterValues— valori impostati dall'amministratore inviati alla knowledge base per ogni chiamata, ad esempio il limite knowledgeBaseId o il valore predefinito. numberOfResults Vengono utilizzati a meno che l'agente non sovrascriva un campo che hai esposto.
-
parameterOverrides— un elenco che controlla quali campi di richiesta l'agente può vedere e impostare al momento della chiamata. Ogni voce contiene:
-
path— il campo nella Retrieve richiesta, ad esempio $.retrievalQuery.text o$.retrievalConfiguration.managedSearchConfiguration.numberOfResults.
-
description— testo opzionale mostrato all'agente che descrive il campo.
-
visible— impostato per true esporre il campo all'agente o false per nasconderlo mentre si invia comunque qualsiasi impostazione predefinita configurata dall'amministratore.
Associalo parameterValues e non knowledgeBaseId esporlo.
La seguente voce di configurazione associa la knowledge base, imposta un valore predefinito di 10 risultati ed espone il testo della query e il conteggio dei risultati all'agente:
{
"name": "Retrieve",
"description": "Search the knowledge base for relevant documents.",
"parameterValues": {
"knowledgeBaseId": "<KB_ID>",
"retrievalConfiguration": {
"managedSearchConfiguration": {
"numberOfResults": 10
}
}
},
"parameterOverrides": [
{
"path": "$.retrievalQuery.text",
"description": "The search query. Use specific keywords for best results.",
"visible": true
},
{
"path": "$.retrievalConfiguration.managedSearchConfiguration.numberOfResults",
"description": "Number of results to retrieve (1-100).",
"visible": true
}
]
}
Configurare il ruolo del servizio Gateway
Questo connettore utilizza il ruolo di esecuzione del gateway, l'ARN del ruolo IAM a cui si passaCreateGateway, che il AgentCore servizio presume chiami il backend per conto dell'utente. Si tratta di un ruolo creato dall'utente, non di un ruolo collegato al servizio. Per il connettore Amazon Bedrock Managed Knowledge Bases, sono necessarie le seguenti autorizzazioni:
-
bedrock:GetKnowledgeBase— per convalidare la knowledge base associata al momento della creazione del target. Ambito alla risorsa della knowledge base gestita.
-
bedrock:Retrieve— per lo Retrieve strumento. Ambito alla risorsa gestita della knowledge base.
-
bedrock:AgenticRetrieveStream— per lo AgenticRetrieveStream strumento. Questa azione non è limitata a una risorsa gestita della knowledge base, quindi concedetela. *
Il Gateway firma le chiamate di backend come servizio. bedrock bedrock:GetKnowledgeBaseIncludi indipendentemente dagli strumenti che aggiungi; se aggiungi solo uno strumento, includi solo l'azione di recupero di quello strumento.
bedrock-agentcore:InvokeGatewaynon fa parte del ruolo di esecuzione. Tale autorizzazione appartiene al chiamante, l'agente o l'applicazione che richiama il Gateway, non al ruolo assunto dal Gateway.
Aggiungi una policy con il seguente contenuto al ruolo di esecuzione associato al Gateway:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ValidateKnowledgeBase",
"Effect": "Allow",
"Action": "bedrock:GetKnowledgeBase",
"Resource": "arn:aws:bedrock:<REGION>:<ACCOUNT_ID>:knowledge-base/<KB_ID>"
},
{
"Sid": "RetrieveFromKnowledgeBase",
"Effect": "Allow",
"Action": "bedrock:Retrieve",
"Resource": "arn:aws:bedrock:<REGION>:<ACCOUNT_ID>:knowledge-base/<KB_ID>"
},
{
"Sid": "AgenticRetrieveStream",
"Effect": "Allow",
"Action": "bedrock:AgenticRetrieveStream",
"Resource": "*"
}
]
}
Il ruolo del servizio deve inoltre considerare attendibile il AgentCore servizio in modo che possa assumere il ruolo. Allega la seguente politica di fiducia, assegnandola al tuo account e a Gateway con le aws:SourceArn condizioni aws:SourceAccount e:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowAgentCoreToAssumeRole",
"Effect": "Allow",
"Principal": {
"Service": "bedrock-agentcore.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "<ACCOUNT_ID>"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:bedrock-agentcore:<REGION>:<ACCOUNT_ID>:gateway/*"
}
}
}
]
}
Aggiungi una destinazione Connector con Web Search Tool
Puoi aggiungere un connettore integrato come destinazione al tuo gateway. Il connettore Web Search Tool fornisce funzionalità di ricerca Web gestite senza richiedere infrastrutture o chiavi API personalizzate.
Per ulteriori informazioni sul connettore Web Search Tool, vedere Web Search Tool.
Configurare lo strumento di ricerca Web
È possibile aggiungere facoltativamente la destinazione a una versione specifica del connettore inserendola version nel source campo. Se si ometteversion, la destinazione utilizza la versione predefinita corrente del connettore. Per ulteriori informazioni sulle versioni dei connettori, vedere Versioni Versioni del connettore del connettore.
Esempio
- Boto3
-
-
Il seguente codice Python mostra come creare un Gateway Target con la configurazione del connettore Web Search Tool utilizzando AWS Python SDK (Boto3):
import boto3
gateway_client = boto3.client("bedrock-agentcore-control", region_name="<REGION>")
gateway_client.create_gateway_target(
name="web-search-tool",
gatewayIdentifier="<GATEWAY_ID>",
targetConfiguration={
"mcp": {
"connector": {
"source": {"connectorId": "web-search", "version": "1.1.0"},
"configurations": [{"name": "WebSearch", "parameterValues": {}}],
}
}
},
credentialProviderConfigurations=[
{"credentialProviderType": "GATEWAY_IAM_ROLE"}
],
)
- AWS CLI
-
-
Il comando seguente crea un Gateway Target con la configurazione del connettore Web Search Tool utilizzando la CLI: AWS
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "<GATEWAY_ID>" \
--name "web-search-tool" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "web-search",
"version": "1.1.0"
},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region "<REGION>"
- AgentCore CLI
-
-
Per aggiungere una destinazione Web Search Tool, esegui agentcore add gateway-target con--type connector --connector web-search:
agentcore add gateway-target \
--name MyWebSearchTarget \
--type connector \
--connector web-search \
--gateway MyGateway
agentcore deploy
- Interactive
-
-
Nell'interfaccia utente interattiva del terminale AgentCore CLI, eseguiagentcore add gateway-target, quindi seleziona Amazon Web Search dal selettore del tipo di destinazione:
La procedura guidata richiede un nome di destinazione, il gateway a cui collegarsi e un elenco opzionale di domini da escludere dai risultati di ricerca.
Configurare il filtro dei domini
È possibile limitare i domini che il Web Search Tool può interrogare configurando un elenco di inclusione o esclusione dei domini. Ciò è utile per gli amministratori che desiderano impedire agli agenti di restituire risultati da siti Web specifici.
-
Target-level elenco di esclusione dei domini: un elenco di domini esclusi da tutte le ricerche su una destinazione, impostato al momento della creazione della destinazione utilizzando. parameterValues.domainFilter.exclude L'elenco di esclusione viene applicato sul lato server e nascosto all'agente chiamante.
-
Target-level elenco di inclusione dei domini (versione del connettore 1.2.0 e successive): oltre all'elenco delle esclusioni, è possibile configurare la limitazione delle ricerche parameterValues.domainFilter.include a un set specifico di domini.
Request-level i filtri (dominio include/exclude e intervallo di date di pubblicazione) sono disponibili per l'agente chiamante nella versione del connettore e successive. 1.2.0 Request-level i filtri si compongono con gli elenchi di esclusione e inclusione a livello di destinazione: le esclusioni e le inclusioni a livello di destinazione si applicano sempre e l'agente non può ridurle.
Gli esempi seguenti creano una destinazione dello Strumento di ricerca Web associata a una versione 1.2.0 con elenchi di inclusione ed esclusione dei domini:
Esempio
- Boto3
-
-
Il seguente codice Python mostra come creare un target per lo strumento di ricerca Web con filtro di dominio utilizzando AWS Python SDK (Boto3):
import boto3
gateway_client = boto3.client("bedrock-agentcore-control", region_name="<REGION>")
gateway_client.create_gateway_target(
name="web-search-tool",
gatewayIdentifier="<GATEWAY_ID>",
targetConfiguration={
"mcp": {
"connector": {
"source": {"connectorId": "web-search", "version": "1.2.0"},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {
"domainFilter": {
"include": ["allowed-website-1.com", "allowed-website-2.com"],
"exclude": ["blocked-website-1.com", "blocked-website-2.com"]
}
},
}
],
}
}
},
credentialProviderConfigurations=[
{"credentialProviderType": "GATEWAY_IAM_ROLE"}
],
)
- AWS CLI
-
-
Il comando seguente crea un target Web Search Tool con filtro di dominio utilizzando la CLI: AWS
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "<GATEWAY_ID>" \
--name "web-search-tool" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "web-search",
"version": "1.2.0"
},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {
"domainFilter": {
"include": ["allowed-website-1.com", "allowed-website-2.com"],
"exclude": ["blocked-website-1.com", "blocked-website-2.com"]
}
}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region "<REGION>"
- AgentCore CLI
-
-
Passa un elenco di domini separato da virgole tramite: --exclude-domains
agentcore add gateway-target \
--name MyWebSearchTarget \
--type connector \
--connector web-search \
--exclude-domains blocked-website-1.com,blocked-website-2.com \
--gateway MyGateway
agentcore deploy
- Interactive
-
-
Nell'interfaccia utente interattiva del terminale AgentCore CLI, la procedura guidata Add Gateway Target richiede un elenco opzionale di domini separati da virgole da escludere dai risultati della ricerca dopo aver selezionato Amazon Web Search e scelto un gateway. Se il prompt viene lasciato vuoto, la destinazione non viene filtrata dal dominio.
Puoi anche aggiornare una destinazione esistente per aggiungere o modificare il filtro del dominio utilizzando. UpdateGatewayTarget
Configurare il ruolo del servizio Gateway
Il Gateway necessita di un ruolo di servizio che consenta al AgentCore servizio di eseguire azioni per conto dell'utente. Per il Web Search Tool, il ruolo richiede le seguenti autorizzazioni:
-
bedrock-agentcore:InvokeGateway— per richiamare il Gateway
-
bedrock-agentcore:InvokeWebSearch— per autorizzare le chiamate di ricerca sul Web, verificate per richiesta rispetto all'ARN di proprietà del servizio arn:aws:bedrock-agentcore:<region>:aws:tool/web-search.v1
Aggiungi una policy con il seguente contenuto al ruolo di servizio associato al Gateway:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "InvokeGateway",
"Effect": "Allow",
"Action": "bedrock-agentcore:InvokeGateway",
"Resource": "arn:aws:bedrock-agentcore:<REGION>:<ACCOUNT_ID>:gateway/*"
},
{
"Sid": "InvokeWebSearch",
"Effect": "Allow",
"Action": "bedrock-agentcore:InvokeWebSearch",
"Resource": "arn:aws:bedrock-agentcore:<REGION>:aws:tool/web-search.v1"
}
]
}
