Sampel Kode Permintaan parameter Mode masukan deskripsi alat Respons Hasil rekomendasi Kesalahan

Mulai rekomendasi deskripsi alat

Mulai rekomendasi untuk menghasilkan deskripsi alat yang dioptimalkan untuk agen Anda. Layanan menganalisis jejak agen untuk mengidentifikasi kebingungan pemilihan alat dan menghasilkan deskripsi tajam yang mengurangi ambiguitas ketika agen memilih antara alat.

catatan

Rekomendasi dihasilkan oleh LLM. Tinjau dan uji sebelum menerapkannya.

Sampel Kode

contoh

AgentCore CLI

catatan

Tidak seperti rekomendasi prompt sistem, yang membutuhkan tepat satu-e/--evaluator, deskripsi alat berjalan menghilangkan -e/--evaluator sepenuhnya.

Deskripsi alat sebaris dengan CloudWatch jejak:


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

Deskripsi alat sebaris dengan file bentang:


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

Deskripsi alat sebaris dengan ID sesi tertentu:


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

Bundel konfigurasi dengan CloudWatch jejak:


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

Bundel konfigurasi dengan file bentang:


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

Selain itu --lookback--spans-file,, dan--session-id, agentcore run recommendation menerima dua sumber jejak lagi: --from-insights <id> (gunakan wawasan lokal yang dijalankan sebagai sumber jejak; CLI menyelesaikan ARN evaluasi batch--batch-evaluation-arn <arn>) dan (gunakan ARN evaluasi batch secara langsung). Untuk ikhtisar semua sumber jejak, lihat Melacak sumber untuk rekomendasi. Anda juga dapat menambahkan --kms-key <arn> untuk mengenkripsi hasil rekomendasi dengan kunci KMS yang dikelola pelanggan.

Untuk memblokir hingga rekomendasi mencapai status terminal, tambahkan--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

Ambil hasil yang sudah selesai, termasuk deskripsi alat yang dioptimalkan, dengan: agentcore view recommendation


agentcore view recommendation <recommendation-id> --json

AWS SDK (boto3)

Deskripsi alat sebaris dengan CloudWatch jejak:


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

Deskripsi alat sebaris dengan bentang sebaris:


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

Bundel konfigurasi dengan CloudWatch jejak:


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

Bundel konfigurasi dengan bentang sebaris:


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

Permintaan parameter

Parameter	Tipe	Diperlukan	Deskripsi
`name`	Tali	Ya	Nama untuk rekomendasi. Maksimal 48 karakter. Pola:`[a-zA-Z][a-zA-Z0-9_-]{0,47}`.
`type`	Tali	Ya	Harus berupa `TOOL_DESCRIPTION_RECOMMENDATION`.
`recommendationConfig`	Objek	Ya	Berisi `toolDescriptionRecommendationConfig` dengan konfigurasi untuk rekomendasi.
`description`	String	Tidak	Deskripsi opsional. Maksimal 4096 karakter.
`clientToken`	String	Tidak	Token idempotensi. Jika Anda mencoba lagi permintaan dengan token klien yang sama, layanan mengembalikan rekomendasi yang ada alih-alih membuat yang baru.

DescriptionRecommendationConfig bidang alat

Bidang	Tipe	Diperlukan	Deskripsi
`toolDescription`	Union	Ya	Deskripsi alat saat ini untuk mengoptimalkan. Berikan `toolDescriptionText` (daftar sebaris nama alat dan pasangan deskripsi) atau `configurationBundle` (referensi bundel dengan jalur JSON ke setiap deskripsi alat).
`agentTraces`	Union	Ya	Sumber jejak untuk analisis. Lihat Melacak sumber untuk rekomendasi.

catatan

Rekomendasi deskripsi alat tidak memerlukanevaluationConfig. Tidak seperti rekomendasi prompt sistem, yang menggunakan evaluator sebagai sinyal pengoptimalan, rekomendasi deskripsi alat menganalisis pola pemilihan alat langsung dari jejak agen untuk mengidentifikasi ambiguitas antara alat dan menghasilkan deskripsi yang tajam.

Mode masukan deskripsi alat

Modus	Bendera CLI	Bidang API
Teks sebaris	`--tools "name:description"`(ulangi untuk setiap alat)	`toolDescription.toolDescriptionText.tools`. Daftar objek dengan `toolName` dan `toolDescription`
Bundel konfigurasi	`--bundle-name <bundle-name>`+ `--bundle-version <bundle-version>` + `--tool-desc-json-path "name:field"` (ulangi untuk setiap alat)	`toolDescription.configurationBundle`dengan`bundleArn`,`versionId`, dan `tools` daftar yang berisi `toolName` dan `toolDescriptionJsonPath`

Saat menggunakan bundel konfigurasi, hasilnya menyertakan versi bundel baru dengan deskripsi alat yang dioptimalkan diterapkan.

Respons

Bidang	Tipe	Deskripsi
`recommendationId`	String	Pengidentifikasi unik untuk rekomendasi.
`recommendationArn`	String	ARN dari rekomendasi.
`name`	String	Nama yang Anda tentukan.
`type`	String	`TOOL_DESCRIPTION_RECOMMENDATION`.
`status`	String	Status awal: `PENDING` atau`IN_PROGRESS`.
`createdAt`	Stempel waktu	Ketika rekomendasi dibuat.
`updatedAt`	Stempel waktu	Ketika rekomendasi terakhir diperbarui.

Hasil rekomendasi

Ketika rekomendasi mencapai COMPLETED status (diambil melalui Dapatkan rekomendasi), hasilnya berisi:

Bidang	Tipe	Deskripsi
`tools`	Daftar	Per-tool hasil. Setiap entri berisi`toolName`,`recommendedToolDescription`, dan`explanation`.
`configurationBundle`	Objek	Hadir saat input adalah bundel konfigurasi. Berisi `bundleArn` dan `versionId` menunjuk ke versi bundel baru dengan deskripsi yang dioptimalkan diterapkan.
`errorCode`	String	Hadir jika rekomendasi gagal. Kode kesalahan yang menggambarkan kegagalan.
`errorMessage`	String	Hadir jika rekomendasi gagal. Human-readable deskripsi kesalahan.

Kesalahan

Kesalahan	Status HTTP	Deskripsi
`ValidationException`	400	Parameter permintaan tidak valid. Periksa batasan bidang dan bidang wajib.
`AccessDeniedException`	403	Izin tidak mencukupi. Verifikasi kebijakan IAM.
`ConflictException`	409	Rekomendasi dengan token klien yang sama sudah ada dengan parameter yang berbeda.
`ServiceQuotaExceededException`	402	Anda telah melampaui jumlah maksimum rekomendasi bersamaan.
`ThrottlingException`	429	Tingkat permintaan terlampaui. Coba lagi dengan backoff eksponensial.
`InternalServerException`	500	Service-side kesalahan. Coba lagi permintaannya.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Rekomendasi prompt sistem

Dapatkan rekomendasi