View a markdown version of this page

Recomendaciones - Amazon Bedrock AgentCore
Modos de entrada de configuraciónFuentes de rastreo de agentes

Recomendaciones

Las recomendaciones utilizan la IA para generar configuraciones de agentes optimizadas a partir de seguimientos de sesiones reales. En lugar de volver a escribir manualmente las instrucciones o las descripciones de las herramientas, debes dirigir el servicio a las huellas de tu agente, especificar un evaluador objetivo como señal de recompensa y recibir una configuración optimizada.

nota

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

Amazon Bedrock AgentCore admite dos tipos de recomendaciones:

  • Recomendación rápida del sistema: analiza las trazas de los agentes y genera una solicitud de sistema optimizada que mejora el rendimiento del evaluador objetivo. El servicio identifica los patrones de fallo y añade instrucciones de comportamiento específicas.

  • Recomendación sobre la descripción de la herramienta: analiza las trazas de los agentes y genera descripciones de las herramientas más precisas para reducir la confusión al seleccionar las herramientas. Esto resulta útil cuando los agentes seleccionan la herramienta incorrecta para solicitudes ambiguas.

Cada recomendación requiere dos entradas: la configuración actual del agente para optimizarla y el seguimiento de los agentes para analizarla.

Temas

Modos de entrada de configuración

La configuración actual se proporciona de dos maneras:

  • Texto en línea: proporciona la configuración directamente como una cadena en la solicitud de API. Para obtener recomendaciones sobre los avisos del sistema, pasa el texto del mensaje en el systemPrompt.text campo. Para obtener recomendaciones sobre la descripción de la herramienta, introduzca el nombre y la descripción de cada herramienta en la toolDescription.toolDescriptionText.tools lista. Este modo resulta útil para experimentar rápidamente, cuando desee probar un indicador en el que esté iterando activamente o cuando la configuración no esté almacenada en un paquete.

    Tipo de recomendación Banderas CLI Campo de API

    Petición del sistema

    --inline "prompt text" o --prompt-file ./path.txt

    systemPrompt.text

    Descripción de la herramienta

    --tools "name:description, name:description"

    toolDescription.toolDescriptionText.tools: lista de objetos con toolName y toolDescription

  • Paquete de configuración: haga referencia a una versión existente del paquete de configuración. El servicio lee la configuración actual del paquete mediante la ruta JSON que especifique, genera la versión optimizada y vuelve a escribir el resultado en una nueva versión del paquete. De este modo, el historial de optimización se mantiene versionado junto con el paquete. Este modo resulta útil cuando se gestionan las configuraciones de forma centralizada con paquetes de configuración y se desea que el resultado optimizado se regrabe automáticamente en el paquete.

    Tipo de recomendación Banderas CLI Campo de API

    Petición del sistema

    --bundle-name <bundle-name> + --bundle-version <bundle-version> + --system-prompt-json-path <path>

    systemPrompt.configurationBundlecon bundleArnversionId, systemPromptJsonPath

    Descripción de la herramienta

    --bundle-name <bundle-name>+ --bundle-version <bundle-version> + --tool-desc-json-path "name:jsonpath" (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 de la recomendación incluye un configurationBundle campo con una nueva que versionId apunta a la versión del paquete que contiene la configuración optimizada. bundleArn

Fuentes de rastreo de agentes

El agentTraces parámetro acepta una de estas dos fuentes:

  • CloudWatch Registros: utilícelo cuando el agente en tiempo de ejecución escriba la telemetría. CloudWatch El servicio lee los seguimientos directamente de los grupos de registros especificados dentro de un intervalo de tiempo requerido. Debe proporcionarlogGroupArns, serviceNamesstartTime, yendTime. Un rule campo opcional le permite filtrar los seguimientos (por ejemplo, seleccionar solo las sesiones en las que goal_success_rate esté por debajo de un umbral).

    nota

    La API de recomendaciones utiliza los ARN de los grupos de registros (logGroupArns), no los nombres de los grupos de registros. Esto difiere de las evaluaciones por lotes, que utilizanlogGroupNames.

    Campo Tipo Obligatorio Description (Descripción)

    cloudwatchLogs.logGroupArns

    Lista de cadenas

    Sí

    CloudWatch Los registros de los ARN de los grupos de registros donde se almacena la telemetría del agente. Formato: arn:aws:logs:{region}:{account}:log-group:{log-group-name}.

    cloudwatchLogs.serviceNames

    Lista de cadenas

    Sí

    Nombres de servicios que identifican las trazas de su agente. CloudWatch Convención:{RuntimeName}.DEFAULT.

    cloudwatchLogs.startTime

    Fecha y hora ISO 8601

    Sí

    Inicio de la ventana de recopilación de trazas. Solo se incluyen los rastros después de este tiempo.

    cloudwatchLogs.endTime

    Fecha y hora ISO 8601

    Sí

    Fin de la ventana de recopilación de trazas. Solo se incluyen los rastros anteriores a esta hora.

    cloudwatchLogs.rule

    Objeto

    No

    Regla de filtrado opcional para restringir la selección de trazas. Contiene una filters lista en la que cada filtro especifica unkey, operator (por ejemploLESS_THAN) y value (por ejemplo{"doubleValue": 0.5}).
    ejemplo
    AgentCore CLI
    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --lookback 7 \
  --wait
    AWS SDK (boto3)
    from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
    }
}

    Con un filtro de reglas opcional para seleccionar solo las sesiones de bajo rendimiento:

    agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
        "rule": {
            "filters": [
                {
                    "key": "goal_success_rate",
                    "operator": "LESS_THAN",
                    "value": {"doubleValue": 0.5}
                }
            ]
        },
    }
}

  • Intervalos de sesión en línea: utilízalo cuando tengas rastreos disponibles localmente (por ejemplo, de una ejecución de prueba local, de una CI/CD canalización o de una sesión específica para la que desees optimizar). Los intervalos se proporcionan directamente en el cuerpo de la solicitud de la API, como una lista de objetos de OpenTelemetry-compatible intervalo.

    Campo Tipo Obligatorio Description (Descripción)

    sessionSpans

    Lista de objetos

    Sí

    El rastreo del agente se extiende en OpenTelemetry-compatible formato. Cada intervalo incluye el identificador de seguimiento, el identificador del intervalo, el nombre, las marcas de tiempo y los atributos.
    ejemplo
    AgentCore CLI

    Archivo de tramos (lee los intervalos de un archivo JSON local y los pasa como intervalos en línea):

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --spans-file agent-traces.json

    ID de sesión específicos (la CLI recopila los datos del lado del cliente y los pasa como intervalos en línea):

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --session-id <session-id-1> <session-id-2>
    AWS SDK (boto3)
    import json

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

agent_traces = {
    "sessionSpans": spans
}
nota

agentcore run recommendationes asíncrono. Sin --wait ella, el comando envía el trabajo recomendado y lo devuelve inmediatamente; el trabajo se inicia en un estado no terminal (por ejemplo, PENDING oIN_PROGRESS) y el resultado se recupera más adelante. Pase --wait a bloquear hasta que la recomendación alcance un estado terminal. Para sondear o recuperar el resultado de un trabajo enviado, ejecutaagentcore view recommendation <id>, donde id está el ID del trabajo recomendado.

La AgentCore CLI proporciona indicadores de conveniencia que se asignan a los tipos de fuentes de rastreo de la API subyacentes:

Bandera CLI Mapeo de API Description (Descripción)

--lookback <days>

cloudwatchLogscon computerizado startTime y endTime

Recopila los rastros de los últimos N días a través CloudWatch de registros. La CLI resuelve los ARN de los grupos de registros y los nombres de los servicios a partir de la configuración del tiempo de ejecución.

--session-id <id>

sessionSpans(en línea)

Recopila los intervalos de la sesión especificada del lado del cliente y los pasa como intervalos de sesión en línea. La propia API de recomendaciones no admite el filtrado de ID de sesión en las fuentes. CloudWatch

--spans-file <path>

sessionSpans(en línea)

Lee los intervalos de un archivo JSON local y los pasa como intervalos de sesión en línea.

--wait

n/a (sondeo del lado del cliente)

Bloquee hasta que la recomendación alcance un estado terminal.