Ejemplos de código Parámetros de solicitud Cómo 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 una solicitud de sistema optimizada para su agente. El servicio analiza los rastros de los agentes, identifica los patrones de error y produce una solicitud de sistema revisada que mejora el rendimiento del evaluador objetivo.

nota

Las recomendaciones las generan los LLM. Revíselas y pruébelas antes de aplicarlas.

Ejemplos de código

ejemplo

AgentCore CLI

La CLI acepta varias fuentes de rastreo y tres modos de entrada de datos 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>— usa una generación de información local como fuente de rastreo; resuelve el ARN de evaluación de lotes) o un ARN de evaluación de lotes directamente (--batch-evaluation-arn <arn>— usa un ARN de evaluación de lotes directamente como fuente de rastreo)
Entrada de datos del sistema: texto en línea (--inline), archivo de mensaje () o paquete de configuración (--prompt-file) --bundle-name
Filtro opcional: identificadores de sesión específicos (--session-id) para restringir los rastros que se analizan
Cifrado opcional: una clave KMS (--kms-key <arn>— ARN de la clave KMS para cifrar los resultados de las recomendaciones)

Símbolo del sistema en línea con rastros: 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 asincrónico y devuelve solo un recommendationId y una inicial o un estado. PENDING IN_PROGRESS --waitAñádala al bloque hasta que la recomendación alcance un estado terminal. Para recuperar el resultado completo más adelante, consulte Recuperar el resultado.

Mensaje del sistema integrado desde un archivo con CloudWatch rastros:
```
agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --prompt-file ./system-prompt.txt \
  --lookback 7
```
Símbolo del sistema integrado con un archivo de intervalos:
```
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 de 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 a partir del objeto configuration principal del ARN en tiempo de ejecución del agente. Solo tiene que proporcionar el nombre de la clave que contiene la solicitud 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 completo. Agregue --json 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 trazas: 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 en línea:


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. 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 del sistema PromptRecommendationConfig

Campo	Tipo	Obligatorio	Description (Descripción)
`systemPrompt`	Unión	Sí	El indicador actual del sistema para la optimización. Indique `text` (cadena en línea, máximo 20 000 caracteres) o `configurationBundle` (referencia del paquete).
`agentTraces`	Unión	Sí	Rastrea la fuente para el análisis. Consulte 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.

Cómo elegir un evaluador

Seleccione un evaluador que esté alineado con la dirección en la que desea mejorar. El evaluador que seleccione determinará para qué se optimiza la recomendación; el optimizador impulsa el mensaje hacia lo que el evaluador obtenga una puntuación alta.

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

Si tu agente tiene una tarea clara que completar (reserva, recuperación, un flujo de trabajo de varios pasos), Builtin.GoalSuccessRate es la señal correcta.
Si su agente es más abierto y usted se preocupa por la calidad de la interacción en sí misma, Builtin.Helpfulness es una mejor opción.
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úralos ratingScale con una numerical escala (no). categorical En el caso de los evaluadores basados en código, incluya el value campo en el esquema de respuesta.

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


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

En la CLI, utilice la --evaluator marca:


--evaluator Builtin.GoalSuccessRate

Modos de entrada de mensajes del sistema

Mode	Indicadores de CLI	Campo 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 recupera mediante Obtener una recomendación), el resultado contiene:

Campo	Tipo	Description (Descripción)
`recommendedSystemPrompt`	Cadena	El texto de aviso del sistema optimizado.
`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 el mensaje optimizado aplicado.
`explanation`	Cadena	Una explicación del motivo por el que se generó la recomendación y de las razones en las que se basan los cambios sugeridos.
`errorCode`	Cadena	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 .

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 de descripción de la herramienta