Definire la configurazione di destinazione del gateway
La configurazione della destinazione dipende dal tipo di destinazione che stai aggiungendo al gateway. Per ulteriori informazioni sui tipi di target gateway supportati, consulta Target supportati per i AgentCore gateway Amazon Bedrock.
Seleziona un argomento per visualizzare esempi di aggiunta di un tipo di target:
Aggiungere un obiettivo Lambda
È possibile aggiungere una destinazione Lambda al gateway utilizzando la AgentCore CLI specificando as e fornendo l'ARN Lambda --type e un file di schema lambda-function-arn dello strumento.
Configurazione del target
La configurazione di destinazione (o payload) per una funzione Lambda contiene i seguenti campi:
Per ulteriori informazioni sugli obiettivi Lambda, consulta Target delle funzioni AWS Lambda.
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
- AgentCore Python SDK
-
-
Con la AgentCore CLI, puoi creare facilmente un 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 esempio di argomento che è possibile 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, esegui, seleziona aggiungi agentcore, 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.
Aggiungere un target di fase API Gateway
Per aggiungere una fase di un'API REST API Gateway come destinazione, specifica l'ARN dell'API e dello stage e definisci le impostazioni per filtrare gli strumenti nel gateway API o per sovrascrivere i nomi e le descrizioni degli strumenti nel gateway:
Gli esempi seguenti mostrano come aggiungere un target API Gateway. Vengono inoltre applicate le seguenti configurazioni:
Seleziona uno dei seguenti metodi:
Esempio
- AgentCore CLI
-
-
Per aggiungere una fase API REST API Gateway 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 l'utilizzo dell'SDK AWS Python (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 aggiungi agentcore, scegli Gateway Target, quindi seleziona API API Gateway REST:
La procedura guidata richiede quindi il nome della destinazione, l'ID API REST, lo stadio e la configurazione dell'autorizzazione in uscita.
Aggiungere un target OpenAPI
Seleziona uno dei seguenti metodi:
Esempio
- AgentCore CLI
-
-
Per aggiungere un target 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 la destinazione 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, esegui, seleziona aggiungi agentcore, scegli Gateway Target, quindi seleziona OpenAPI Schema:
La procedura guidata richiede quindi il nome della destinazione, il percorso del file delle specifiche OpenAPI e la configurazione dell'autorizzazione in uscita.
Aggiungi un obiettivo Smithy
Seleziona uno dei seguenti metodi:
Esempio
- AgentCore CLI
-
-
Per aggiungere un target del modello Smithy, esegui agentcore add gateway-target con l'--type smithy-modelopzione e fornisci 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 AWS Python SDK (Boto3):
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 agentcore, scegli Gateway 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.
Aggiungere 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 Amazon Bedrock AgentCore Runtime targets.
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"
}
]
)
Aggiungere 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 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 il valore predefinito è la regione del gateway.
Il valore di service dipende da dove è ospitato il server MCP. Di seguito sono riportati i valori comuni:
-
bedrock-agentcore— Per i server MCP ospitati su Amazon Bedrock AgentCore, come il runtime (vedi Implementazione dei server MCP in AgentCore Runtime) o un altro gateway.
-
execute-api— Per i server MCP supportati da Amazon API Gateway.
-
lambda— Per i server MCP protetti dagli URL della funzione Lambda.
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 interattiva del terminale AgentCore CLI, esegui, seleziona aggiungi agentcore, 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, esegui agentcore add gateway-target con l'--type mcp-serveropzione e specifica 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 una destinazione 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 espone due strumenti, ciascuno denominato in base al relativo funzionamento di backend: AgenticRetrieveStream (recupero in più fasi, streaming agentic retrieval) e Retrieve (una singola ricerca ibrida). Si aggiunge una voce di configurazione per strumento.
PerAgenticRetrieveStream, set retrievers (le basi di conoscenza gestite su cui interrogare) e agenticRetrieveConfiguration inparameterValues. Entrambi sono obbligatori: l'omissione agenticRetrieveConfiguration causa un errore di runtime. Può essere un oggetto vuoto ({}) che accetta 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 l'knowledgeBaseIdparameterValuesingresso; è obbligatorio.
Il connettore supporta solo basi di conoscenza gestite. Le destinazioni dei connettori 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 AWS Python SDK (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 AWS CLI:
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 un target di connettore della Knowledge Base gestito, eseguilo agentcore add gateway-target 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 e una descrizione e consente di selezionare uno o più tipi e fonti di origine.
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. Sondaggio GetGatewayTarget fino a status esaurimentoREADY. Uno FAILED stato include un motivo che descrive il problema.
Per personalizzare il recupero degli agenti, ad esempio per limitare le iterazioni di pianificazione o collegare un guardrail, aggiungi i campi opzionali a. agenticRetrieveConfiguration Se li ometti, vengono applicate le impostazioni predefinite gestite dal servizio. Per tutti i valori accettati, vedi Riferimento alla configurazione.
{
"name": "AgenticRetrieveStream",
"parameterValues": {
"retrievers": [
{ "configuration": { "knowledgeBase": { "knowledgeBaseId": "<KB_ID>" } } }
],
"agenticRetrieveConfiguration": {
"maxAgentIteration": 5,
"policyConfiguration": {
"guardrailConfiguration": {
"guardrailId": "<GUARDRAIL_ID>",
"guardrailVersion": "1"
}
}
}
}
}
Controlla quali parametri può impostare l'agente
Ogni voce di configurazione dello strumento accetta due controlli di 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 a ogni chiamata, ad esempio il limite knowledgeBaseId o un valore predefinito. numberOfResults Vengono utilizzati a meno che l'agente non sovrascriva un campo che hai esposto.
-
parameterOverrides— un elenco che controlla i campi di richiesta che l'agente può visualizzare 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 per nasconderlo continuando false a inviare eventuali impostazioni predefinite configurate 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 passiCreateGateway, che il AgentCore servizio presume chiami il backend per tuo conto. Questo è un ruolo che crei tu, non 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 vincolata al momento della creazione dell'obiettivo. Interessato alla risorsa gestita della Knowledge Base.
-
bedrock:Retrieve— per lo Retrieve strumento. Interessato alla risorsa gestita della Knowledge Base.
-
bedrock:AgenticRetrieveStream— per lo AgenticRetrieveStream strumento. Questa azione non è limitata a una risorsa gestita della Knowledge Base, quindi concedila. *
Il Gateway firma le chiamate di backend come servizio. bedrock bedrock:GetKnowledgeBaseIncludi indipendentemente dagli strumenti aggiunti; 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 di servizio deve inoltre considerare attendibile il AgentCore servizio in modo che possa assumere il ruolo. Allega la seguente politica di fiducia, applicandola al tuo account e a Gateway con le aws:SourceArn condizioni aws:SourceAccount and:
{
"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 un target Connector con Web Search Tool
È possibile aggiungere un connettore integrato come destinazione al gateway. Il connettore Web Search Tool offre funzionalità di ricerca Web gestite senza richiedere infrastrutture personalizzate o chiavi API.
Per ulteriori informazioni sul connettore Web Search Tool, vedere Web Search Tool.
Configurare Web Search Tool
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"},
"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 AWS CLI:
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "<GATEWAY_ID>" \
--name "web-search-tool" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "web-search"
},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {}
}
]
}
}
}' \
--credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
--region "<REGION>"
- AgentCore CLI
-
-
Per aggiungere un target del 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.
Configura il filtraggio dei domini
È possibile limitare i domini su cui il Web Search Tool può interrogare configurando una denylist di domini. Ciò è utile per gli amministratori che desiderano impedire agli agenti di restituire risultati da siti Web specifici.
Il filtraggio dei domini viene configurato a livello di strumento utilizzando il parameterValues.domainFilter.exclude campo durante la creazione o l'aggiornamento di un Gateway Target. La denylist viene applicata lato server ed è nascosta al LLM: l'agente non è a conoscenza della restrizione e semplicemente non riceve risultati dai domini esclusi.
Gli esempi seguenti creano un oggetto Web Search Tool con filtro di dominio che esclude i risultati da e: blocked-website-1.com blocked-website-2.com
Esempio
- Boto3
-
-
Il seguente codice Python mostra come creare un target Web Search Tool con filtraggio del 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"},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {
"domainFilter": {
"exclude": ["blocked-website-1.com", "blocked-website-2.com"]
}
},
}
],
}
}
},
credentialProviderConfigurations=[
{"credentialProviderType": "GATEWAY_IAM_ROLE"}
],
)
- AWS CLI
-
-
Il comando seguente crea una destinazione Web Search Tool con filtraggio dei domini utilizzando la AWS CLI:
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "<GATEWAY_ID>" \
--name "web-search-tool" \
--target-configuration '{
"mcp": {
"connector": {
"source": {
"connectorId": "web-search"
},
"configurations": [
{
"name": "WebSearch",
"parameterValues": {
"domainFilter": {
"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 separati 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 separato da virgole di domini da escludere dai risultati di ricerca dopo aver selezionato Amazon Web Search e scelto un gateway. Lasciando il prompt vuoto si crea la destinazione senza filtri di dominio.
È inoltre possibile aggiornare una destinazione esistente per aggiungere o modificare il filtraggio 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 ogni 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"
}
]
}
