코드 샘플 요청 파라미터 도구 설명 입력 모드 응답 권장 사항 결과 오류

도구 설명 권장 사항 시작

에이전트에 대한 최적화된 도구 설명을 생성하려면 권장 사항을 시작합니다. 이 서비스는 에이전트 추적을 분석하여 도구 선택 혼동을 식별하고 에이전트가 도구 중에서 선택할 때 모호성을 줄이는 명확한 설명을 생성합니다.

참고

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

코드 샘플

예

AgentCore CLI

참고

정확히 하나의가 필요한 시스템 프롬프트 권장 사항과 달리 -e/--evaluator도구 설명은 -e/--evaluator 완전히 생략됩니다.

CloudWatch 트레이스를 사용한 인라인 도구 설명:


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --lookback 7

스팬 파일이 있는 인라인 도구 설명:


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --spans-file agent-traces.json

특정 세션 IDs 있는 인라인 도구 설명:


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --session-id 12345678-1234-1234-1234-123456789012

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


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --tool-desc-json-path "lookup_order:lookup_order" \
  --tool-desc-json-path "initiate_return:initiate_return" \
  --lookback 7

스팬 파일이 있는 구성 번들:


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --tool-desc-json-path "lookup_order:lookup_order" \
  --tool-desc-json-path "initiate_return:initiate_return" \
  --spans-file agent-traces.json

--lookback, --spans-file및 외에도는 --from-insights <id> (로컬 인사이트 실행을 트레이스 소스로 사용, CLI는 배치 평가 ARN을 확인) 및 --batch-evaluation-arn <arn> (배치 평가 ARN을 직접 사용)의 두 가지 트레이스 소스를 추가로 --session-id agentcore run recommendation 허용합니다. 모든 추적 소스에 대한 개요는 추적 소스에서 권장 사항을 참조하세요. --kms-key <arn>를 추가하여 고객 관리형 KMS 키로 권장 사항 결과를 암호화할 수도 있습니다.

권장 사항이 터미널 상태에 도달할 때까지 차단하려면를 추가합니다--wait.


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --lookback 7 \
  --wait

를 사용하여 최적화된 도구 설명을 포함하여 완료된 결과를 검색합니다agentcore view recommendation.


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-tool-rec",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "toolDescriptionText": {
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescription": {"text": "Look up an order by ID"},
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescription": {"text": "Initiate a return for an order"},
                        },
                    ]
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "arn:aws:logs:us-west-2:123456789012:log-group:/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"
                    ],
                    "serviceNames": ["MyAgent.DEFAULT"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
        }
    },
    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-tool-rec-spans",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "toolDescriptionText": {
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescription": {"text": "Look up an order by ID"},
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescription": {"text": "Initiate a return for an order"},
                        },
                    ]
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

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


response = client.start_recommendation(
    name="my-bundle-tool-rec",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescriptionJsonPath": "$.configuration.tools.lookup_order.description",
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescriptionJsonPath": "$.configuration.tools.initiate_return.description",
                        },
                    ],
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "arn:aws:logs:us-west-2:123456789012:log-group:/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"
                    ],
                    "serviceNames": ["MyAgent.DEFAULT"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

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


response = client.start_recommendation(
    name="my-bundle-tool-rec-spans",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescriptionJsonPath": "$.configuration.tools.lookup_order.description",
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescriptionJsonPath": "$.configuration.tools.initiate_return.description",
                        },
                    ],
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

요청 파라미터

파라미터	유형	필수	설명
`name`	문자열	예	권장 사항의 이름입니다. 최대 48자입니다. 패턴: `[a-zA-Z][a-zA-Z0-9_-]{0,47}`.
`type`	문자열	예	`TOOL_DESCRIPTION_RECOMMENDATION`여야 합니다.
`recommendationConfig`	객체	예	권장 사항에 대한 구성과 `toolDescriptionRecommendationConfig` 함께를 포함합니다.
`description`	문자열	No	선택적 설명 최대 4096자입니다.
`clientToken`	문자열	No	Idempotency 토큰입니다. 동일한 클라이언트 토큰으로 요청을 재시도하면 서비스는 새 클라이언트 토큰을 생성하는 대신 기존 권장 사항을 반환합니다.

toolDescriptionRecommendationConfig 필드

Field	유형	필수	설명
`toolDescription`	결합	예	최적화할 현재 도구 설명입니다. `toolDescriptionText` (도구 이름 및 설명 페어의 인라인 목록) 또는 `configurationBundle` (각 도구 설명에 대한 JSON 경로가 포함된 번들 참조)를 제공합니다.
`agentTraces`	결합	예	분석을 위한 추적 소스입니다. 권장 사항은 소스 추적을 참조하세요.

참고

도구 설명 권장 사항에는가 필요하지 않습니다evaluationConfig. 평가자를 최적화 신호로 사용하는 시스템 프롬프트 권장 사항과 달리 도구 설명 권장 사항은 에이전트 추적에서 직접 도구 선택 패턴을 분석하여 도구 간의 모호성을 식별하고 명확한 설명을 생성합니다.

도구 설명 입력 모드

Mode	CLI 플래그	API 필드
인라인 텍스트	`--tools "name:description"` (각 도구에 대해 반복)	`toolDescription.toolDescriptionText.tools`. `toolName` 및가 있는 객체 목록 `toolDescription`
구성 번들	`--bundle-name <bundle-name>` + `--bundle-version <bundle-version>` +`--tool-desc-json-path "name:field"`(각 도구에 대해 반복)	`toolDescription.configurationBundle` 및 `bundleArn`가 포함된 `versionId`, `toolName` 및 `tools` 목록 포함 `toolDescriptionJsonPath`

구성 번들을 사용할 때 결과에는 최적화된 도구 설명이 적용된 새 번들 버전이 포함됩니다.

응답

Field	유형	설명
`recommendationId`	문자열	권장 사항의 고유 식별자입니다.
`recommendationArn`	문자열	권장 사항의 ARN입니다.
`name`	문자열	지정한 이름입니다.
`type`	문자열	`TOOL_DESCRIPTION_RECOMMENDATION`.
`status`	문자열	초기 상태: `PENDING` 또는 `IN_PROGRESS`.
`createdAt`	타임스탬프	권장 사항이 생성된 시간입니다.
`updatedAt`	타임스탬프	권장 사항이 마지막으로 업데이트된 시간입니다.

권장 사항 결과

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

Field	유형	설명
`tools`	목록	도구별 결과. 각 항목에는 `toolName`, 및 `recommendedToolDescription`가 포함됩니다`explanation`.
`configurationBundle`	객체	입력이 구성 번들일 때 표시됩니다. 최적화된 설명이 적용된 새 번들 버전을 포함하고 `bundleArn` `versionId` 가리킵니다.
`errorCode`	문자열	권장 사항이 실패한 경우 표시됩니다. 실패를 설명하는 오류 코드입니다.
`errorMessage`	문자열	권장 사항이 실패한 경우 표시됩니다. 사람이 읽을 수 있는 오류 설명입니다.

오류

오류	HTTP 상태	설명
`ValidationException`	400	잘못된 요청 파라미터입니다. 필드 제약 조건 및 필수 필드를 확인합니다.
`AccessDeniedException`	403	권한이 부족합니다. IAM 정책을 확인합니다.
`ConflictException`	409	동일한 클라이언트 토큰을 사용하는 권장 사항이 이미 다른 파라미터와 함께 존재합니다.
`ServiceQuotaExceededException`	402	최대 동시 권장 사항 수를 초과했습니다.
`ThrottlingException`	429	요청 속도가 초과되었습니다. 지수 백오프를 사용하여 재시도하세요.
`InternalServerException`	500	서비스 측 오류입니다. 요청을 다시 시도하세요.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

시스템 프롬프트 권장 사항

권장 사항 가져오기