View a markdown version of this page

Iniciar una recomendación de descripción de la herramienta - Amazon Bedrock AgentCore
Ejemplos de códigoParámetros de solicitudModos de entrada de descripciones de herramientasRespuestaResultado de la recomendaciónErrores

Iniciar una recomendación de descripción de la herramienta

Inicie una recomendación para generar descripciones de herramientas optimizadas para su agente. El servicio analiza las huellas de los agentes para identificar la confusión en la selección de herramientas y produce descripciones más precisas que reducen la ambigüedad cuando el agente elige entre las herramientas.

nota

Las recomendaciones las generan los LLM. Revíselos y pruébelos antes de aplicarlos.

Ejemplos de código

ejemplo
AgentCore CLI
nota

A diferencia de las recomendaciones rápidas del sistema, que requieren exactamente una-e/--evaluator, la descripción de la herramienta se omite -e/--evaluator por completo.

Descripciones de herramientas en línea con trazas CloudWatch :

agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --lookback 7

Descripciones de herramientas en línea con un archivo de extensiones:

agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --spans-file agent-traces.json

Descripciones de herramientas en línea con identificadores de sesión específicos:

agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --session-id 12345678-1234-1234-1234-123456789012

Paquete de configuración con CloudWatch trazas:

agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --tool-desc-json-path "lookup_order:lookup_order" \
  --tool-desc-json-path "initiate_return:initiate_return" \
  --lookback 7

Paquete de configuración con un archivo spans:

agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --tool-desc-json-path "lookup_order:lookup_order" \
  --tool-desc-json-path "initiate_return:initiate_return" \
  --spans-file agent-traces.json

Además--lookback, y --spans-file--session-id, agentcore run recommendation acepta dos fuentes de rastreo más: --from-insights <id> (utilice una ejecución de información local como fuente de rastreo; la CLI resuelve el ARN de evaluación por lotes) y --batch-evaluation-arn <arn> (use un ARN de evaluación por lotes directamente). Para obtener una descripción general de todas las fuentes de rastreo, consulte Fuentes de rastreo para obtener recomendaciones. También puedes --kms-key <arn> añadir una clave KMS gestionada por el cliente para cifrar los resultados de las recomendaciones.

Para bloquear hasta que la recomendación alcance un estado terminal, añade--wait:

agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --lookback 7 \
  --wait

Recupere el resultado completo, incluidas las descripciones de las herramientas optimizadas, conagentcore view recommendation:

agentcore view recommendation <recommendation-id> --json
AWS SDK (boto3)

Descripciones de herramientas en línea con CloudWatch trazas:

import boto3
import json
import uuid
from datetime import datetime, timedelta, timezone

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

now = datetime.now(timezone.utc)

response = client.start_recommendation(
    name="my-tool-rec",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "toolDescriptionText": {
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescription": {"text": "Look up an order by ID"},
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescription": {"text": "Initiate a return for an order"},
                        },
                    ]
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "arn:aws:logs:us-west-2:123456789012:log-group:/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"
                    ],
                    "serviceNames": ["MyAgent.DEFAULT"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

recommendation_id = response["recommendationId"]
print(f"Started recommendation: {recommendation_id}")
print(f"Status: {response['status']}")

Descripciones de herramientas en línea con intervalos en línea:

with open("agent-traces.json") as f:
    spans = json.load(f)

response = client.start_recommendation(
    name="my-tool-rec-spans",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "toolDescriptionText": {
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescription": {"text": "Look up an order by ID"},
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescription": {"text": "Initiate a return for an order"},
                        },
                    ]
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Paquete de configuración con trazas: CloudWatch 

response = client.start_recommendation(
    name="my-bundle-tool-rec",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescriptionJsonPath": "$.configuration.tools.lookup_order.description",
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescriptionJsonPath": "$.configuration.tools.initiate_return.description",
                        },
                    ],
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "arn:aws:logs:us-west-2:123456789012:log-group:/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"
                    ],
                    "serviceNames": ["MyAgent.DEFAULT"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Paquete de configuración con intervalos en línea:

response = client.start_recommendation(
    name="my-bundle-tool-rec-spans",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescriptionJsonPath": "$.configuration.tools.lookup_order.description",
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescriptionJsonPath": "$.configuration.tools.initiate_return.description",
                        },
                    ],
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Parámetros de solicitud

Parámetro Tipo Obligatorio Descripción

name

Cadena

Sí

Un nombre para la recomendación. Máximo 48 caracteres. Patrón:[a-zA-Z][a-zA-Z0-9_-]{0,47}.

type

Cadena

Sí

Debe ser TOOL_DESCRIPTION_RECOMMENDATION.

recommendationConfig

Objeto

Sí

Contiene toolDescriptionRecommendationConfig la configuración de la recomendación.

description

Cadena

No

Descripción opcional. Máximo 4096 caracteres.

clientToken

Cadena

No

Símbolo de idempotencia. Si vuelves a intentar una solicitud con el mismo token de cliente, el servicio devuelve la recomendación existente en lugar de crear una nueva.

campos de herramientas DescriptionRecommendationConfig

Campo Tipo Obligatorio Description (Descripción)

toolDescription

Unión

Sí

Las descripciones de las herramientas actuales que se deben optimizar. Indique toolDescriptionText (lista en línea de pares de nombres y descripciones de la herramienta) o configurationBundle (agrupe la referencia con las rutas JSON de cada descripción de la herramienta).

agentTraces

Unión

Sí

Rastrea la fuente para el análisis. Consulte las fuentes de rastreo para obtener recomendaciones.
nota

Las recomendaciones de descripción de la herramienta no requieren unevaluationConfig. A diferencia de las recomendaciones rápidas del sistema, que utilizan un evaluador como señal de optimización, las recomendaciones de descripción de herramientas analizan los patrones de selección de herramientas directamente a partir de las trazas de los agentes para identificar la ambigüedad entre las herramientas y generar descripciones más precisas.

Modos de entrada de descripciones de herramientas

Mode Banderas CLI Campo de API

Texto en línea

--tools "name:description"(repita para cada herramienta)

toolDescription.toolDescriptionText.tools. Lista de objetos con toolName y toolDescription

Paquete de configuración

--bundle-name <bundle-name>+ --bundle-version <bundle-version> + --tool-desc-json-path "name:field" (repita para cada herramienta)

toolDescription.configurationBundlecon bundleArnversionId, y tools una lista que contiene toolName y toolDescriptionJsonPath

Cuando se utiliza un paquete de configuración, el resultado incluye una nueva versión del paquete con las descripciones optimizadas de las herramientas aplicadas.

Respuesta

Campo Tipo Description (Descripción)

recommendationId

Cadena

Identificador único de la recomendación.

recommendationArn

Cadena

ARN de la recomendación.

name

Cadena

El nombre que especificó.

type

Cadena

TOOL_DESCRIPTION_RECOMMENDATION.

status

Cadena

Estado inicial: PENDING oIN_PROGRESS.

createdAt

Timestamp

Cuándo se creó la recomendación.

updatedAt

Timestamp

Cuándo se actualizó la recomendación por última vez.

Resultado de la recomendación

Cuando la recomendación alcanza el COMPLETED estado (se obtiene mediante Obtener una recomendación), el resultado contiene:

Campo Tipo Description (Descripción)

tools

Enumeración

Per-tool resultados. Cada entrada contiene toolNamerecommendedToolDescription, yexplanation.

configurationBundle

Objeto

Presente cuando la entrada era un paquete de configuración. Contiene bundleArn y versionId apunta a una nueva versión del paquete con las descripciones optimizadas aplicadas.

errorCode

Cadena

Está presente si la recomendación falló. Código de error que describe el error.

errorMessage

Cadena

Está presente si la recomendación falló. Human-readable descripción del error.

Errores

Error Estado HTTP Description (Descripción)

ValidationException

400

Parámetros de solicitud no válidos. Compruebe las restricciones de campo y los campos obligatorios.

AccessDeniedException

403

Permisos insuficientes. Compruebe las políticas de IAM.

ConflictException

409

Ya existe una recomendación con el mismo token de cliente con parámetros diferentes.

ServiceQuotaExceededException

402

Has superado el número máximo de recomendaciones simultáneas.

ThrottlingException

429

Se superó la tasa de solicitudes. Vuelva a intentarlo con retroceso exponencial.

InternalServerException

500

Service-side error. Intente realizar de nuevo la solicitud .