View a markdown version of this page

시스템 프롬프트 권장 사항 시작 - Amazon Bedrock AgentCore

시스템 프롬프트 권장 사항 시작

에이전트에 최적화된 시스템 프롬프트를 생성하려면 권장 사항을 시작합니다. 이 서비스는 에이전트 추적을 분석하고, 실패 패턴을 식별하고, 대상 평가자의 성능을 개선하는 수정된 시스템 프롬프트를 생성합니다.

참고

권장 사항은 LLMs에서 생성됩니다. 적용하기 전에 검토하고 테스트합니다.

코드 샘플

AgentCore CLI

CLI는 여러 추적 소스와 세 가지 시스템 프롬프트 입력 모드를 허용합니다. 필요에 따라 결합합니다.

  • 트레이스 소스: CloudWatch Logs(--lookback), 인라인 스팬(--spans-file), 로컬 인사이트 실행(--from-insights <id> - 로컬 인사이트 실행을 트레이스 소스로 사용, 배치 평가 ARN 확인) 또는 배치 평가 ARN 직접(--batch-evaluation-arn <arn> - 배치 평가 ARN을 트레이스 소스로 직접 사용)

  • 시스템 프롬프트 입력: 인라인 텍스트(--inline), 프롬프트 파일(--prompt-file) 또는 구성 번들(--bundle-name)

  • 선택적 필터: 분석되는 트레이IDs(--session-id)

  • 선택적 암호화: KMS 키(--kms-key <arn> — 권장 사항 결과 암호화를 위한 KMS 키 ARN)

    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 recommendation는 비동기 작업을 시작하고 recommendationId 및 초기 PENDING 또는 IN_PROGRESS 상태만 반환합니다. 권장 사항이 터미널 상태에 도달할 때까지를 --wait 블록에 추가합니다. 나중에 완료된 결과를 검색하려면 결과 검색을 참조하세요.

    CloudWatch 트레이스가 있는 파일의 인라인 시스템 프롬프트:

    agentcore run recommendation \ --type system-prompt \ --run my-prompt-rec \ --runtime MyAgent \ --evaluator Builtin.GoalSuccessRate \ --prompt-file ./system-prompt.txt \ --lookback 7

    스팬 파일이 있는 인라인 시스템 프롬프트:

    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

    특정 세션 IDs 있는 인라인 시스템 프롬프트:

    CLI는 지정된 세션 클라이언트 측의 스팬을 수집하여 인라인 스팬으로 전달합니다.

    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>

    CloudWatch 트레이스가 포함된 구성 번들:

    CLI는 에이전트 런타임 ARN의 configuration 상위 객체에서 전체 JSON 경로를 자동으로 확인합니다. 시스템 프롬프트가 포함된 키 이름만 제공하면 됩니다.

    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

    결과를 검색합니다.

    권장 작업 ID와 view recommendation 함께를 사용하여 완료된 결과를 가져옵니다. recommendedSystemPrompt--json를 포함하는 시스템 읽기 가능 출력에를 추가합니다explanation.

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

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']}")

인라인 범위가 있는 인라인 텍스트:

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()), )

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()), )

인라인 범위가 있는 구성 번들:

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()), )

요청 파라미터

파라미터 유형 필수 설명

name

문자열

권장 사항의 이름입니다. 최대 48자입니다. 패턴: [a-zA-Z][a-zA-Z0-9_-]{0,47}.

type

문자열

SYSTEM_PROMPT_RECOMMENDATION여야 합니다.

recommendationConfig

객체

권장 사항에 대한 구성과 systemPromptRecommendationConfig 함께를 포함합니다.

description

문자열

No

선택적 설명 최대 4096자입니다.

clientToken

문자열

No

Idempotency 토큰입니다. 동일한 클라이언트 토큰으로 요청을 재시도하면 서비스는 새 클라이언트 토큰을 생성하는 대신 기존 권장 사항을 반환합니다.

systemPromptRecommendationConfig 필드

Field 유형 필수 설명

systemPrompt

결합

최적화할 현재 시스템 프롬프트입니다. text (인라인 문자열, 최대 20,000자) 또는 configurationBundle (번들 참조)를 입력합니다.

agentTraces

결합

분석을 위한 추적 소스입니다. 권장 사항은 소스 추적을 참조하세요.

evaluationConfig

객체

대상 평가자를 지정하는 평가 구성입니다. 정확히 하나의 평가자 참조가 있는 evaluators 목록을 포함합니다.

평가자 선택

개선하려는 방향에 맞는 평가자를 선택합니다. 선택한 평가자는 권장 사항이 최적화되는 대상을 결정합니다. 평가자의 점수가 높으면 최적화 프로그램이 프롬프트를 푸시하는 대상이 됩니다.

기본 제공 평가자를 사용하거나 사용자 지정 평가자 ARN을 제공할 수 있습니다. 다음 지침에 따라 선택합니다.

  • 에이전트가 완료해야 할 명확한 작업(예약, 검색, 다단계 워크플로)이 있는 경우가 올바른 신호Builtin.GoalSuccessRate입니다.

  • 에이전트가 더 개방형이고 상호 작용 자체의 품질을 중시하는 경우 Builtin.Helpfulness가 더 적합합니다.

  • 관심 있는 품질이 도메인별로 다르거나 기본 제공 평가자에 의해 캡처되지 않은 경우 사용자 지정 평가자를 사용하여 측정을 가장 잘 표현합니다.

참고

권장 사항은 기본 제공, 사용자 지정 LLM-as-judge 및 코드 기반 평가자를 지원하지만, 평가자는 숫자 값을 최적화 신호로 반환해야 합니다. 사용자 지정 LLM-as-judge 평가자의 경우 numerical 스케일( 아님)ratingScale을 사용하여를 구성합니다categorical. 코드 기반 평가자의 경우 응답 스키마value 필드를 포함합니다.

API에서 정확히 하나의 평가자 참조로 evaluationConfig.evaluators 목록에 평가자를 지정합니다.

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

CLI에서 --evaluator 플래그를 사용합니다.

--evaluator Builtin.GoalSuccessRate

시스템 프롬프트 입력 모드

Mode CLI 플래그 API 필드

인라인 텍스트

--inline "prompt text" 또는 --prompt-file ./path.txt

systemPrompt.text

구성 번들

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

systemPrompt.configurationBundle bundleArn, versionId, systemPromptJsonPath

구성 번들을 사용할 때 최적화된 시스템 프롬프트가 적용된 새 번들 버전이 결과에 포함됩니다.

응답

Field 유형 설명

recommendationId

문자열

권장 사항의 고유 식별자입니다.

recommendationArn

문자열

권장 사항의 ARN입니다.

name

문자열

지정한 이름입니다.

type

문자열

SYSTEM_PROMPT_RECOMMENDATION.

status

문자열

초기 상태: PENDING 또는 IN_PROGRESS.

createdAt

타임스탬프

권장 사항이 생성된 시간입니다.

updatedAt

타임스탬프

권장 사항이 마지막으로 업데이트된 시간입니다.

권장 사항 결과

권장 사항이 COMPLETED 상태에 도달하면(권장 사항 가져오기를 통해 검색) 결과에 다음이 포함됩니다.

Field 유형 설명

recommendedSystemPrompt

문자열

최적화된 시스템 프롬프트 텍스트입니다.

configurationBundle

객체

입력이 구성 번들일 때 표시됩니다. 최적화된 프롬프트가 적용된 새 번들 버전을 포함하고 bundleArn versionId 가리킵니다.

explanation

문자열

권장 사항이 생성된 이유와 제안된 변경 사항의 근거에 대한 설명입니다.

errorCode

문자열

권장 사항이 실패한 경우 표시됩니다. 실패를 설명하는 오류 코드입니다.

errorMessage

문자열

권장 사항이 실패한 경우 표시됩니다. 사람이 읽을 수 있는 오류 설명입니다.

오류

오류 HTTP 상태 설명

ValidationException

400

잘못된 요청 파라미터입니다. 필드 제약 조건 및 필수 필드를 확인합니다.

AccessDeniedException

403

권한이 부족합니다. IAM 정책을 확인합니다.

ConflictException

409

동일한 클라이언트 토큰을 사용하는 권장 사항이 이미 다른 파라미터와 함께 존재합니다.

ServiceQuotaExceededException

402

최대 동시 권장 사항 수를 초과했습니다.

ThrottlingException

429

요청 속도가 초과되었습니다. 지수 백오프를 사용하여 재시도하세요.

InternalServerException

500

서비스 측 오류입니다. 요청을 다시 시도하세요.