View a markdown version of this page

권장 사항 - Amazon Bedrock AgentCore
구성 입력 모드에이전트 추적 소스

권장 사항

권장 사항은 AI를 사용하여 실제 세션 추적에서 최적화된 에이전트 구성을 생성합니다. 프롬프트 또는 도구 설명을 수동으로 다시 작성하는 대신 서비스가 에이전트의 트레이스를 가리키고 대상 평가자를 보상 신호로 지정하며 최적화된 구성을 수신합니다.

참고

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

Amazon Bedrock AgentCore는 다음 두 가지 권장 유형을 지원합니다.

  • 시스템 프롬프트 권장 사항: 에이전트 추적을 분석하고 최적화된 시스템 프롬프트를 생성하여 대상 평가자의 성능을 개선합니다. 서비스는 장애 패턴을 식별하고 특정 동작 지침을 추가합니다.

  • 도구 설명 권장 사항: 에이전트 트레이스를 분석하고 도구 선택 혼동을 줄이는 선명화된 도구 설명을 생성합니다. 이는 에이전트가 모호한 요청에 대해 잘못된 도구를 선택할 때 유용합니다.

각 권장 사항에는 최적화할 현재 에이전트 구성과 분석할 에이전트 추적이라는 두 가지 입력이 필요합니다.

주제

구성 입력 모드

다음 두 가지 방법 중 하나로 현재 구성을 제공합니다.

  • 인라인 텍스트: API 요청에서 구성을 문자열로 직접 제공합니다. 시스템 프롬프트 권장 사항의 경우 systemPrompt.text 필드에 프롬프트 텍스트를 전달합니다. 도구 설명 권장 사항의 경우 toolDescription.toolDescriptionText.tools 목록에 각 도구의 이름과 설명을 전달합니다. 이 모드는 빠른 실험, 적극적으로 반복하는 프롬프트를 테스트하려는 경우 또는 구성이 번들에 저장되지 않은 경우에 유용합니다.

    추천 유형 CLI 플래그 API 필드

    시스템 프롬프트

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

    systemPrompt.text

    도구 설명

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

    toolDescription.toolDescriptionText.tools: toolName 및가 있는 객체 목록 toolDescription

  • 구성 번들: 기존 구성 번들 버전을 참조합니다. 서비스는 지정한 JSON 경로를 사용하여 번들에서 현재 구성을 읽고, 최적화된 버전을 생성하고, 결과를 새 번들 버전에 다시 씁니다. 이렇게 하면 최적화 기록이 번들과 함께 버전이 지정됩니다. 이 모드는 구성 번들을 사용하여 구성을 중앙에서 관리하고 최적화된 출력을 번들에 자동으로 다시 쓰도록 할 때 유용합니다.

    추천 유형 CLI 플래그 API 필드

    시스템 프롬프트

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

    systemPrompt.configurationBundle bundleArn, versionId, systemPromptJsonPath

    도구 설명

    --bundle-name <bundle-name> + --bundle-version <bundle-version> +--tool-desc-json-path "name:jsonpath"(각 도구에 대해 반복)

    toolDescription.configurationBundle 및 bundleArn가 포함된 versionId, toolName 및 tools 목록 포함 toolDescriptionJsonPath

    구성 번들을 사용하는 경우 권장 결과에는가 있는 configurationBundle 필드bundleArn와 최적화된 구성이 포함된 번들 버전을 versionId 가리키는 새가 포함됩니다.

에이전트 추적 소스

agentTraces 파라미터는 다음 두 가지 소스 중 하나를 허용합니다.

  • CloudWatch Logs: 에이전트 런타임이 CloudWatch에 원격 측정을 쓸 때 사용합니다. 서비스는 필요한 시간 범위 내에서 지정된 로그 그룹에서 직접 트레이스를 읽습니다. logGroupArns, serviceNames, startTime및를 제공해야 합니다endTime. 선택적 rule 필드를 사용하면 트레이스를 필터링할 수 있습니다(예: goal_success_rate가 임계값 미만인 세션만 선택).

    참고

    권장 사항 API는 로그 그룹 이름이 아닌 로그 그룹 ARNs(logGroupArns)을 사용합니다. 이는를 사용하는 배치 평가와 다릅니다logGroupNames.

    Field 유형 필수 설명

    cloudwatchLogs.logGroupArns

    문자열 목록

    예

    CloudWatch Logs 에이전트 원격 측정이 저장되는 로그 그룹 ARNs입니다. 형식: arn:aws:logs:{region}:{account}:log-group:{log-group-name}

    cloudwatchLogs.serviceNames

    문자열 목록

    예

    CloudWatch에서 에이전트의 트레이스를 식별하는 서비스 이름입니다. 규칙: {RuntimeName}.DEFAULT.

    cloudwatchLogs.startTime

    ISO 8601 날짜/시간

    예

    추적 수집 기간의 시작입니다. 이 시간 이후의 트레이스만 포함됩니다.

    cloudwatchLogs.endTime

    ISO 8601 날짜/시간

    예

    추적 수집 기간의 끝입니다. 이 시간 이전의 트레이스만 포함됩니다.

    cloudwatchLogs.rule

    객체

    아니요

    추적 선택 범위를 좁히는 선택적 필터 규칙입니다. 각 필터가 key, operator (예: LESS_THAN) 및 value (예: )를 지정하는 filters 목록을 포함합니다{"doubleValue": 0.5}.
    예
    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,
    }
}

    성능이 낮은 세션만 선택하는 선택적 규칙 필터를 사용하는 경우:

    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}
                }
            ]
        },
    }
}

  • 인라인 세션 범위: 로컬에서(예: 로컬 테스트 실행, CI/CD 파이프라인 또는 최적화하려는 특정 세션에서) 트레이스를 사용할 수 있는 경우 사용합니다. OpenTelemetry 호환 스팬 객체 목록으로 API 요청 본문에 스팬을 직접 제공합니다.

    Field 유형 필수 설명

    sessionSpans

    객체 목록

    예

    OpenTelemetry 호환 형식의 에이전트 추적 범위입니다. 각 스팬에는 트레이스 ID, 스팬 ID, 이름, 타임스탬프 및 속성이 포함됩니다.
    예
    AgentCore CLI

    스팬 파일(로컬 JSON 파일에서 스팬을 읽고 인라인 스팬으로 전달):

    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

    특정 세션 IDs(CLI는 클라이언트 측 스팬을 수집하여 인라인 스팬으로 전달):

    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
}
참고

agentcore run recommendation는 비동기식입니다. 이 없으면 --wait명령이 권장 작업을 제출하고 즉시 반환합니다. 작업은 비터미널 상태(예: PENDING 또는 IN_PROGRESS)에서 시작되며 나중에 결과를 검색합니다. 권장 사항이 터미널 상태에 도달할 때까지 --wait 블록에 전달합니다. 제출된 작업의 결과를 폴링하거나 검색하려면를 실행합니다. agentcore view recommendation <id>여기서 id는 권장 작업 ID입니다.

AgentCore CLI는 기본 API 트레이스 소스 유형에 매핑되는 편의 플래그를 제공합니다.

CLI 플래그 API 매핑 설명

--lookback <days>

cloudwatchLogs startTime 및가 계산된 endTime

CloudWatch Logs를 통해 지난 N일 동안의 추적을 수집합니다. CLI는 런타임 구성에서 로그 그룹 ARNs 및 서비스 이름을 확인합니다.

--session-id <id>

sessionSpans (인라인)

지정된 세션 클라이언트 측의 스팬을 수집하여 인라인 세션 스팬으로 전달합니다. 권장 사항 API 자체는 CloudWatch 소스에서 세션 ID 필터링을 지원하지 않습니다.

--spans-file <path>

sessionSpans (인라인)

로컬 JSON 파일에서 범위를 읽고 인라인 세션 범위로 전달합니다.

--wait

해당 사항 없음(클라이언트 측 폴링)

권장 사항이 터미널 상태에 도달할 때까지 차단합니다.