Ejemplos de código Parámetros de solicitud Elegir un evaluador Modos de entrada de mensajes del sistema Respuesta Resultado de la recomendación Errores

Iniciar una recomendación rápida del sistema

Inicie una recomendación para generar un mensaje de sistema optimizado para su agente. El servicio analiza los rastros de los agentes, identifica los patrones de error y produce un aviso del sistema revisado que mejora el rendimiento del evaluador objetivo.

nota

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

Ejemplos de código

ejemplo

AgentCore CLI

La CLI acepta varias fuentes de rastreo y tres modos de entrada de avisos del sistema. Combínelos según sea necesario:

Fuentes de rastreo: CloudWatch registros (--lookback), intervalos en línea (--spans-file), una ejecución de información local (--from-insights <id>— utiliza una ejecución de información local como fuente de rastreo; resuelve el ARN de evaluación por lotes) o un ARN de evaluación por lotes directamente (— --batch-evaluation-arn <arn> usa un ARN de evaluación por lotes directamente como fuente de rastreo)
Entrada de mensajes del sistema: texto en línea (--inline), archivo de solicitud () o paquete de configuración (--prompt-file) --bundle-name
Filtro opcional: identificadores de sesión específicos (--session-id) para restringir las trazas que se analizan
Cifrado opcional: una clave KMS (--kms-key <arn>— ARN de clave KMS para cifrar los resultados de las recomendaciones)

Indicador de sistema en línea con trazas: CloudWatch
```
agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful customer support assistant. Help users with their orders and returns." \
  --lookback 7 \
  --wait
```
run recommendationinicia un trabajo asíncrono y devuelve solo una inicial o un recommendationId estado. PENDING IN_PROGRESS --waitAñádalo al bloque hasta que la recomendación alcance un estado terminal. Para recuperar el resultado completo más adelante, consulte Recuperar el resultado.

Solicitud de sistema en línea desde un archivo con CloudWatch trazas:
```
agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --prompt-file ./system-prompt.txt \
  --lookback 7
```
Mensaje de sistema en línea con un archivo de extensión:
```
agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful customer support assistant." \
  --spans-file agent-traces.json
```
Mensaje del sistema en línea con identificadores de sesión específicos:

La CLI recopila los intervalos para la sesión especificada 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 customer support assistant." \
  --session-id <session-id-1> <session-id-2>
```
Paquete de configuración con trazas: CloudWatch

La CLI resuelve automáticamente la ruta JSON completa del objeto configuration principal del ARN en tiempo de ejecución del agente. Solo tiene que proporcionar el nombre de la clave que contiene el indicador del sistema.
```
agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --system-prompt-json-path "system_prompt" \
  --lookback 7
```
Recupera el resultado:

view recommendationUtilícelo con el identificador del trabajo recomendado para obtener el resultado final. Añada esta --json opción para obtener una salida legible por máquina que contenga y. recommendedSystemPrompt explanation
```
agentcore view recommendation <recommendation-id> --json
```

AWS SDK (boto3)

Texto en línea con trazos: CloudWatch


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-prompt-rec",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "text": "You are a helpful customer support assistant. Help users with their orders and returns."
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "<log-group-arn>"
                    ],
                    "serviceNames": ["<service-name>"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

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

Texto en línea con intervalos entre líneas:


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

response = client.start_recommendation(
    name="my-prompt-rec-spans",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "text": "You are a helpful customer support assistant."
            },
            "agentTraces": {
                "sessionSpans": spans
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Paquete de configuración con trazas: CloudWatch


response = client.start_recommendation(
    name="my-bundle-prompt-rec",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "systemPromptJsonPath": "$.configuration.system_prompt",
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "<log-group-arn>"
                    ],
                    "serviceNames": ["<service-name>"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

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


response = client.start_recommendation(
    name="my-bundle-prompt-rec-spans",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "systemPromptJsonPath": "$.configuration.system_prompt",
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    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 `SYSTEM_PROMPT_RECOMMENDATION`.
`recommendationConfig`	Objeto	Sí	Contiene `systemPromptRecommendationConfig` 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 del sistema PromptRecommendationConfig

Campo	Tipo	Obligatorio	Description (Descripción)
`systemPrompt`	Unión	Sí	El sistema actual solicita la optimización. Indique `text` (cadena en línea, máximo 20 000 caracteres) o `configurationBundle` (referencia del paquete).
`agentTraces`	Unión	Sí	Rastree la fuente para su análisis. Consulte las fuentes de rastreo para obtener recomendaciones.
`evaluationConfig`	Objeto	Sí	Configuración de evaluación que especifica el evaluador objetivo. Contiene una `evaluators` lista con exactamente una referencia de evaluador.

Elegir un evaluador

Seleccione un evaluador alineado con la dirección en la que desea mejorar. El evaluador que seleccione determinará los objetivos de optimización de la recomendación; sea cual sea la puntuación alta que obtenga el evaluador, es lo que busca el optimizador.

Puede usar un evaluador integrado o proporcionar un ARN de evaluador personalizado. Use las siguientes pautas para elegir:

Si su agente tiene una tarea clara que completar (reservar, recuperar, un flujo de trabajo de varios pasos), Builtin.GoalSuccessRate es la señal correcta.
Si su agente es más abierto y a usted le importa la calidad de la interacción en sí, Builtin.Helpfulness es la opción más adecuada.
Si la calidad que le interesa es específica de un dominio o no la capta un evaluador integrado, utilice un evaluador personalizado para representar mejor la medición.

nota

Las recomendaciones admiten evaluadores integrados LLM-as-judge, personalizados y basados en código, pero requieren que el evaluador devuelva un valor numérico como señal de optimización. En el caso de LLM-as-judge los evaluadores personalizados, configúrelos ratingScale con una numerical escala (no). categorical Para los evaluadores basados en código, incluya el value campo en el esquema de respuesta.

En la API, especifique el evaluador de la evaluationConfig.evaluators lista con exactamente una referencia de evaluador:


"evaluationConfig": {
    "evaluators": [
        {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
    ]
}

En la CLI, utilice el --evaluator indicador:


--evaluator Builtin.GoalSuccessRate

Modos de entrada de mensajes del sistema

Mode	Banderas CLI	Campo de API
Texto en línea	`--inline "prompt text"` o `--prompt-file ./path.txt`	`systemPrompt.text`
Paquete de configuración	`--bundle-name <bundle-name>` + `--bundle-version <bundle-version>` + `--system-prompt-json-path <path>`	`systemPrompt.configurationBundle`con `bundleArnversionId`, `systemPromptJsonPath`

Cuando se utiliza un paquete de configuración, el resultado incluye una nueva versión del paquete con el indicador de sistema optimizado aplicado.

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	`SYSTEM_PROMPT_RECOMMENDATION`.
`status`	Cadena	Estado inicial: `PENDING` o`IN_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)
`recommendedSystemPrompt`	Cadena	El texto del mensaje del sistema optimizado.
`configurationBundle`	Objeto	Estaba presente cuando la entrada era un paquete de configuración. Contiene `bundleArn` y `versionId` apunta a una nueva versión del paquete con el mensaje optimizado aplicado.
`explanation`	Cadena	Una explicación de por qué se generó la recomendación y el razonamiento en el que se basan los cambios sugeridos.
`errorCode`	Cadena	Está presente si la recomendación no ha sido aprobada. 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 .

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Recomendaciones

Recomendación sobre la descripción de la herramienta