Codebeispiele Anforderungsparameter Eingabemodi für die Werkzeugbeschreibung Antwort Ergebnis der Empfehlung Fehler

Starten Sie eine Empfehlung für eine Werkzeugbeschreibung

Starten Sie eine Empfehlung zur Generierung optimierter Toolbeschreibungen für Ihren Agenten. Der Service analysiert die Spuren der Agenten, um Unklarheiten bei der Auswahl der Tools zu erkennen, und erstellt genauere Beschreibungen, die Unklarheiten verringern, wenn der Mitarbeiter zwischen Tools entscheidet.

Anmerkung

Empfehlungen werden von LLMs generiert. Überprüfen und testen Sie sie, bevor Sie sie anwenden.

Codebeispiele

Beispiel

AgentCore CLI

Anmerkung

Im Gegensatz zu Empfehlungen in der Systemaufforderung, für die genau eine Option erforderlich ist-e/--evaluator, wird bei der Beschreibung des Tools -e/--evaluator komplett darauf verzichtet.

Inline-Werkzeugbeschreibungen mit CloudWatch Spuren:


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

Inline-Werkzeugbeschreibungen mit einer Spans-Datei:


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

Beschreibungen von Inline-Tools mit spezifischen Sitzungs-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

Konfigurationspaket mit CloudWatch Traces:


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

Konfigurationspaket mit einer Spans-Datei:


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

Außerdem agentcore run recommendation akzeptiert--lookback, und --spans-file--session-id, zwei weitere Trace-Quellen: --from-insights <id> (Verwenden Sie einen lokalen Insights-Lauf als Trace-Quelle; die CLI löst den Batch-Evaluierungs-ARN auf) und --batch-evaluation-arn <arn> (verwenden Sie direkt einen Batch-Evaluierungs-ARN). Eine Übersicht über alle Trace-Quellen finden Sie unter Trace-Quellen für Empfehlungen. Sie können auch hinzufügen--kms-key <arn>, dass die Empfehlungsergebnisse mit einem vom Kunden verwalteten KMS-Schlüssel verschlüsselt werden.

Um zu blockieren, bis die Empfehlung einen Terminalstatus erreicht, fügen Sie Folgendes hinzu--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

Rufen Sie das vollständige Ergebnis, einschließlich der optimierten Werkzeugbeschreibungen, ab mitagentcore view recommendation:


agentcore view recommendation <recommendation-id> --json

AWS SDK (boto3)

Inline-Werkzeugbeschreibungen mit CloudWatch Spuren:


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

Inline-Werkzeugbeschreibungen mit Inline-Spans:


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

Konfigurationspaket mit CloudWatch Traces:


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

Konfigurationspaket mit Inline-Spans:


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

Anforderungsparameter

Parameter	Typ	Erforderlich	Beschreibung
`name`	Zeichenfolge	Ja	Ein Name für die Empfehlung. Maximal 48 Zeichen. Muster:`[a-zA-Z][a-zA-Z0-9_-]{0,47}`.
`type`	Zeichenfolge	Ja	Der Wert muss `TOOL_DESCRIPTION_RECOMMENDATION` sein.
`recommendationConfig`	Objekt	Ja	Enthält `toolDescriptionRecommendationConfig` die Konfiguration für die Empfehlung.
`description`	Zeichenfolge	Nein	Optionale Beschreibung. Maximal 4096 Zeichen.
`clientToken`	Zeichenfolge	Nein	Idempotenz-Token. Wenn Sie eine Anfrage mit demselben Client-Token erneut versuchen, gibt der Dienst die bestehende Empfehlung zurück, anstatt eine neue zu erstellen.

Werkzeugfelder DescriptionRecommendationConfig

Feld	Typ	Erforderlich	Description
`toolDescription`	Union	Ja	Die aktuellen Werkzeugbeschreibungen zur Optimierung. Geben Sie entweder `toolDescriptionText` (Inline-Liste mit Paaren aus Werkzeugname und Beschreibung) oder `configurationBundle` (Paketreferenz mit JSON-Pfaden zu jeder Werkzeugbeschreibung) an.
`agentTraces`	Union	Ja	Verfolgen Sie die Quelle für die Analyse. Empfehlungen finden Sie unter Trace-Quellen.

Anmerkung

Für Empfehlungen zur Beschreibung von Tools ist keinevaluationConfig. Im Gegensatz zu Empfehlungen zur Systemabfrage, bei denen ein Evaluator als Optimierungssignal verwendet wird, analysieren Toolbeschreibungsempfehlungen die Werkzeugauswahlmuster direkt anhand der Agentenspuren, um Unklarheiten zwischen Tools zu erkennen und genauere Beschreibungen zu generieren.

Eingabemodi für die Werkzeugbeschreibung

Mode	CLI-Flaggen	API-Feld
Inline-Text	`--tools "name:description"`(für jedes Werkzeug wiederholen)	`toolDescription.toolDescriptionText.tools`. Liste der Objekte mit `toolName` und `toolDescription`
Konfigurationspaket	`--bundle-name <bundle-name>`+ `--bundle-version <bundle-version>` + `--tool-desc-json-path "name:field"` (für jedes Tool wiederholen)	`toolDescription.configurationBundle`mit `bundleArnversionId`, und einer `tools` Liste, die `toolName` und enthält `toolDescriptionJsonPath`

Wenn Sie ein Konfigurationspaket verwenden, enthält das Ergebnis eine neue Bundle-Version, auf die die optimierten Toolbeschreibungen angewendet wurden.

Antwort

Feld	Typ	Description
`recommendationId`	Zeichenfolge	Eindeutige ID für die Empfehlung.
`recommendationArn`	Zeichenfolge	ARN der Empfehlung.
`name`	Zeichenfolge	Der Name, den Sie angegeben haben.
`type`	Zeichenfolge	`TOOL_DESCRIPTION_RECOMMENDATION`.
`status`	Zeichenfolge	Ursprünglicher Status: `PENDING` oder`IN_PROGRESS`.
`createdAt`	Zeitstempel	Wann die Empfehlung erstellt wurde.
`updatedAt`	Zeitstempel	Wann die Empfehlung zuletzt aktualisiert wurde.

Ergebnis der Empfehlung

Wenn die Empfehlung den COMPLETED Status erreicht (abgerufen über Empfehlung abrufen), enthält das Ergebnis:

Feld	Typ	Description
`tools`	Auflisten	Per-tool Ergebnisse. Jeder Eintrag enthält `toolNamerecommendedToolDescription`, und`explanation`.
`configurationBundle`	Objekt	Vorhanden, wenn es sich bei der Eingabe um ein Konfigurationspaket handelte. Enthält `bundleArn` und `versionId` verweist auf eine neue Bundle-Version, auf die die optimierten Beschreibungen angewendet wurden.
`errorCode`	Zeichenfolge	Vorhanden, wenn die Empfehlung fehlgeschlagen ist. Fehlercode, der den Fehler beschreibt.
`errorMessage`	Zeichenfolge	Vorhanden, wenn die Empfehlung fehlgeschlagen ist. Human-readable Beschreibung des Fehlers.

Fehler

Fehler	HTTP-Status	Description
`ValidationException`	400	Ungültige Anforderungsparameter. Überprüfen Sie die Feldbeschränkungen und die erforderlichen Felder.
`AccessDeniedException`	403	Unzureichende Berechtigungen. Überprüfen Sie die IAM-Richtlinien.
`ConflictException`	409	Eine Empfehlung mit demselben Client-Token mit unterschiedlichen Parametern ist bereits vorhanden.
`ServiceQuotaExceededException`	402	Sie haben die maximale Anzahl gleichzeitiger Empfehlungen überschritten.
`ThrottlingException`	429	Die Anforderungsrate wurde überschritten. Versuchen Sie es erneut mit exponentiellem Backoff.
`InternalServerException`	500	Service-side Fehler. Wiederholen Sie die Anforderung.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Empfehlung zur Systemaufforderung

Empfehlung einholen