View a markdown version of this page

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

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

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

Haga una recomendación para generar descripciones de herramientas optimizadas para su agente. El servicio analiza los rastros 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íselas y pruébelas antes de aplicarlas.

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 intervalos:

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 de intervalos:

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> (usa una ejecución de insights local como fuente de rastreo; la CLI resuelve el ARN de evaluación por lotes) y --batch-evaluation-arn <arn> (usa directamente un ARN de evaluación por lotes). Para obtener una descripción general de todas las fuentes de rastreo, consulte las fuentes de rastreo para obtener recomendaciones. También puedes agregar y cifrar --kms-key <arn> los resultados de las recomendaciones con una clave de KMS administrada por el cliente.

Para bloquearla hasta que la recomendación llegue a un estado terminal, agrega--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

Recupera el resultado completo, incluidas las descripciones optimizadas de las herramientas, 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. 4096 caracteres como máximo.

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 actuales de las herramientas que se van a optimizar. Proporcione una toolDescriptionText (lista integrada de pares de nombres y descripciones de herramientas) o configurationBundle (una referencia de paquete con rutas JSON a la descripción de cada herramienta).

agentTraces

Unión

Sí

Rastrea la fuente para su análisis. Consulte Fuentes de rastreo para obtener recomendaciones.
nota

Las recomendaciones de descripción de las herramientas 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 los rastros 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 Indicadores de CLI Campo 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 recupera 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

Está 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

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. Verifique las políticas de IAM.

ConflictException

409

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

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 .