Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Verwendung von Tools (Funktionsaufruf) mit Amazon Nova **Anmerkung** Diese Dokumentation bezieht sich auf Amazon Nova Version 1. Informationen zur Verwendung von Tools mit Amazon Nova 2 finden Sie [unter Tools verwenden (Funktionsaufruf)](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-tools.html). Tools sind eine Möglichkeit, Amazon Nova externe Funktionen wie API-Aufrufe oder Codefunktionen zur Verfügung zu stellen. In diesem Abschnitt wird erläutert, wie Sie Tools definieren und integrieren können, wenn Sie mit Amazon-Nova-Modellen arbeiten. Die Verwendung von Tools umfasst drei grundlegende Schritte: + **Benutzerabfrage** – Sie definieren die Tools, die Amazon Nova verwenden kann, indem Sie ein JSON-Schema bereitstellen, das die Funktionalität und Eingabeanforderungen jedes Tools beschreibt. + **Tool-Auswahl** – Wenn ein Benutzer eine Nachricht sendet, analysiert Amazon Nova diese, um festzustellen, ob ein Tool zur Generierung einer Antwort erforderlich ist. Dies wird als `Auto`-Tool-Auswahl bezeichnet. Weitere Informationen finden Sie unter [Auswahl eines Tools](https://docs.aws.amazon.com/nova/latest/userguide/tool-choice.html). Wenn Amazon Nova ein geeignetes Tool identifiziert, ruft es das Tool auf und gibt den Namen des Tools sowie die zu verwendenden Parameter zurück. Sie als Entwickler sind dafür verantwortlich, das Tool gemäß den Anforderungen des Modells auszuführen. Dies bedeutet, dass Sie den Code schreiben müssen, der die Funktionalität des Tools aufruft und die vom Modell bereitgestellten Eingabeparameter verarbeitet. **Anmerkung** Wie bei allen LLM-Antworten ist es auch bei Amazon Nova möglich, einen Tool-Aufruf zu halluzinieren. Es liegt in Ihrer Verantwortung als Entwickler, zu überprüfen, ob das Tool vorhanden ist, die Eingaben korrekt formatiert sind und die entsprechenden Berechtigungen bereits vorhanden sind. + **Ergebnisse zurückgeben** – Nach der Ausführung des Tools müssen Sie die Ergebnisse in einem strukturierten Format an Amazon Nova zurücksenden. Zu den gültigen Formaten gehören JSON oder eine Kombination aus Text und Bildern. Auf diese Weise kann Amazon Nova die Ausgabe des Tools in die endgültige Antwort an den Benutzer einbeziehen. Wenn bei der Ausführung des Tools Fehler auftreten, können Sie dies in der Antwort des Tools an Amazon Nova angeben, sodass Amazon Nova die Antwort entsprechend anpassen kann. Stellen Sie sich ein einfaches Beispiel für ein Taschenrechner-Tool vor: ------ #### [ User query ] Der erste Schritt im Workflow zum Aufrufen von Tools ist die Benutzerabfrage an Amazon Nova nach dem Ergebnis einer mathematischen Gleichung: 10 mal 5. Diese Abfrage wird zusammen mit einer Toolspezifikation, die den Rechner darstellt, als Prompt an Amazon Nova gesendet. ``` user_query = "10*5" messages = [{ "role": "user", "content": [{"text": user_query}] }] tool_config = { "tools": [ { "toolSpec": { "name": "calculator", # Name of the tool "description": "A calculator tool that can execute a math equation", # Concise description of the tool "inputSchema": { "json": { "type": "object", "properties": { "equation": { # The name of the parameter "type": "string", # parameter type: string/int/etc "description": "The full equation to evaluate" # Helpful description of the parameter } }, "required": [ # List of all required parameters "equation" ] } } } } ] } ``` ------ #### [ Tool selection ] Amazon Nova verwendet den Kontext des Tools zusammen mit dem Benutzer-Prompt, um das zu verwendende Tool und die erforderliche Konfiguration zu ermitteln. Dies wird als Teil der API-Antwort zurückgegeben. ``` { "toolUse": { "toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ", "name": "calculator", "input": { "equation": "10*5" } } } ``` Die Anwendung ist dafür verantwortlich, das Tool auszuführen und das Ergebnis zu speichern. ``` def calculator(equation: str): return eval(equation) tool_result = calculator("10*5") ``` ------ #### [ Return results ] Um das Ergebnis des Tools an Amazon Nova zurückzugeben, ist das Tool-Ergebnis in einer neuen API-Anfrage enthalten. Beachten Sie, dass die Verwendungs-ID des Tools mit der ID übereinstimmt, die von Amazon Nova in der vorherigen Antwort zurückgegeben wurde. ``` { "toolResult": { "toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ", "content": [ { "json": { "result": "50" } } ], "status": "success" } } ``` + Amazon Nova verwendet den vollständigen Kontext der Nachrichten, einschließlich der ersten Benutzeranfrage, der Verwendung des Tools und des Toolergebnisses, um die endgültige Antwort an den Benutzer zu ermitteln. In diesem Fall antwortet Amazon Nova dem Benutzer, „10 mal 5 ist 50". ------ Amazon Nova ermöglicht die Verwendung von Tools sowohl in der Invoke- als auch in der Converse-API. Für den vollen Umfang aller Features empfehlen wir die Verwendung der [Converse-API](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use-inference-call.html) und werden in Zukunft Beispiele mit dieser API verwenden. **Topics** + [Ein Tool definieren](tool-use-definition.md) + [Aufrufen eines Tools](tool-use-invocation.md) + [Auswahl eines Tools](tool-choice.md) + [Rückgabe von Tool-Ergebnissen](tool-use-results.md) + [Integrierte Tools verwenden](tool-built-in.md) + [Einen Fehler melden](tool-use-error.md) + [Zusätzliche Verweise](#tool-use-resources) # Ein Tool definieren Ein entscheidender Schritt im Workflow zum Aufrufen von Tools ist die Definition des Tools. Die Tooldefinition muss alle erforderlichen Kontextinformationen enthalten, um dem Modell mitzuteilen, wann es angebracht ist, das Tool aufzurufen. Um ein Tool zu definieren, erstellen Sie eine Tool-Konfiguration und übergeben Sie diese zusammen mit der Benutzernachricht an die API. Das [Tool-Konfigurationsschema](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html) erwartet ein Array von Werkzeugen und optional einen Tool-Auswahlparameter. **Anmerkung** Amazon Nova unterstützt die Optionen `auto`, `any` und `tool` für `toolChoice`. Weitere Informationen finden Sie [ToolChoice](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolChoice.html)in der Amazon Bedrock API-Dokumentation und [Verwenden Sie ein Tool, um eine Amazon Bedrock-Modellantwort abzuschließen](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html). Hier finden Sie ein Beispiel für die Definition eines Tools: ``` tool_config = { "tools": [ { "toolSpec": { "name": "top_song", "description": "Get the most popular song played on a radio station.", "inputSchema": { "json": { "type": "object", "properties": { "sign": { "type": "string", "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ, and WKRP." } }, "required": [ "sign" ] } } } } ], } ``` Der Name, die Beschreibung und das Eingabeschema müssen mit der genauen Funktionalität des Tools übereinstimmen. Stellen Sie sicher, dass alle wichtigen Unterscheidungsmerkmale bei der Verwendung des Tools in der Tool-Konfiguration berücksichtigt werden. **Anmerkung** Die Verständnismodelle von Amazon Nova unterstützen derzeit nur einen Teil der JsonSchema Funktionalität, wenn sie zur Definition der [ToolInputSchema](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolInputSchema.html)in Converse API verwendet werden. Das Schema der obersten Ebene muss vom Typ [Objekt](https://json-schema.org/understanding-json-schema/reference/object) sein. Nur drei Felder werden im Objekt der obersten Ebene unterstützt – Typ (muss auf „Objekt“ gesetzt sein), [https://json-schema.org/understanding-json-schema/reference/object#properties](https://json-schema.org/understanding-json-schema/reference/object#properties) und [https://json-schema.org/understanding-json-schema/reference/object#required](https://json-schema.org/understanding-json-schema/reference/object#required). Für das Aufrufen von Tools empfehlen wir, die Temperatur auf 0 zu setzen, um eine Greed-Dekodierung zu ermöglichen. Hier finden Sie ein Beispiel für den Aufrufen eines Tools mit der Converse-API: ``` import json import boto3 client = boto3.client("bedrock-runtime", region_name="us-east-1") input_text = "What is the most popular song on WZPZ?" messages = [{ "role": "user", "content": [{"text": input_text}] }] inf_params = {"maxTokens": 1000, "temperature": 0} response = client.converse( modelId="us.amazon.nova-lite-v1:0", messages=messages, toolConfig=tool_config, inferenceConfig=inf_params ) messages.append(response["output"]["message"]) # Pretty print the response JSON. print("[Full Response]") print(json.dumps(response, indent=2)) # Print the tool content for easy readability. tool = next( block["toolUse"] for block in response["output"]["message"]["content"] if "toolUse" in block ) print("\n[Tool Response]") print(tool) ``` # Aufrufen eines Tools Wenn Amazon Nova beschließt, ein Tool aufzurufen, wird ein Block zur Verwendung des Tools als Teil der Assistentennachricht zurückgegeben, und der Grund für den Stopp ist „tool\$1use“. Der Tool-Block enthält den Namen des Tools und seine Eingaben. **Anmerkung** Um die Genauigkeit von Toolaufrufen zu verbessern, verwenden Amazon Nova-Modelle standardmäßig chain-of-thought Argumentation für Tool-Aufrufe. Der Denkprozess wird Ihnen in der Assistentenmeldung zur Verfügung gestellt und in „“ Tags enthalten sein. Es ist möglich, dass eine Antwort mehrere Tool-Aufrufe und Denkblöcke enthält, daher sollte Ihre Anwendung dies berücksichtigen. Wenn die Toolauswahl auf `any` oder konfiguriert ist`tool`, wird das chain-of-thought Verhalten dadurch außer Kraft gesetzt und die Antwort enthält nur die erforderlichen Tool-Aufrufe. ``` { "toolUse": { "toolUseId": "tooluse_20Z9zl0BQWSXjFuLKdTJcA", "name": "top_song", "input": { "sign": "WZPZ" } } } ``` Um das Tool tatsächlich aufzurufen, können der Tool-Name und die Argumente aus der Nachricht extrahiert werden, woraufhin die Anwendung es aufrufen kann. Hier ist ein Beispiel dafür, wie Sie einen Tool-Aufruf verarbeiten können. ``` def get_top_song(sign): print(f"Getting the top song at {sign}") return ("Espresso", "Sabrina Carpenter") stop_reason = response["stopReason"] tool, song, artist = None, None, None if stop_reason == "tool_use": thought_process = next( block["text"] for block in response["output"]["message"]["content"] if "text" in block ) print(thought_process) tool = next( block["toolUse"] for block in response["output"]["message"]["content"] if "toolUse" in block ) if tool["name"] == "top_song": song, artist = get_top_song(tool["input"]["sign"]) ``` Beim Definieren und Aufrufen von Tools ist es wichtig, die Sicherheit im Auge zu behalten. LLMs wie Amazon Nova haben keinen Zugriff auf die Sitzungsdetails, daher sollten die Berechtigungen bei Bedarf überprüft werden, bevor ein Tool aufgerufen wird. Verlassen Sie sich auf die Benutzerdaten aus Ihrer Sitzung, anstatt den Prompt zu erweitern und Amazon Nova zu erlauben, ihn in den Tool-Aufruf einzufügen. # Auswahl eines Tools Amazon-Nova-Modelle unterstützen die Funktionalität der *Tool-Auswahl*. Mit der Tool-Auswahl können Sie als Entwickler steuern, wie ein Tool aufgerufen wird. Es gibt drei unterstützte Parameteroptionen für die Tool-Auswahl: `tool`, `any` und `auto`. + **Tool** – Das angegebene Tool wird einmal aufgerufen. + **Beliebig** – Eines der bereitgestellten Tools wird mindestens einmal aufgerufen. + **Automatisch** – Das Modell entscheidet, ob ein Tool aufgerufen werden soll. Falls erforderlich, werden mehrere Tools aufgerufen. ------ #### [ Tool ] Durch die Verwendung von `tool` als Tool-Auswahl können Sie das spezifische Tool steuern, welches das Modell aufruft. Das folgende Beispiel verdeutlicht dies anhand eines strukturierten Anwendungsfalls, bei dem die Antwort in einer einheitlichen Weise formatiert werden muss. ``` tool_config = { "toolChoice": { "tool": { "name" : "extract_recipe"} }, "tools": [ { "toolSpec": { "name": "extract_recipe", "description": "Extract recipe for cooking instructions", "inputSchema": { "json": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the recipe" }, "description": { "type": "string", "description": "Brief description of the dish" }, "ingredients": { "type": "array", "items": { "type": "string", "description": "Name of ingredient" } } }, "required": ["name", "description", "ingredients"] } } } } ] } ``` ------ #### [ Any ] Durch die Verwendung von `any` als Tool-Auswahl können Sie sicherstellen, dass jedes Mal mindestens ein Tool aufgerufen wird. Die Entscheidung, welches Tool aufgerufen wird, liegt zwar beim Modell, es wird jedoch immer ein Tool zurückgegeben. Das folgende Beispiel veranschaulicht die Verwendung von „Tool-Auswahl, beliebig“ für einen API-Auswahl-Endpunkt-Anwendungsfall. Dies ist ein Beispiel dafür, wann es hilfreich ist, vom Modell die Rückgabe eines bestimmten Tools zu verlangen. ``` tool_config = { "toolChoice": { "any": {} }, "tools": [ { "toolSpec": { "name": "get_all_products", "description": "API to retrieve multiple products with filtering and pagination options", "inputSchema": { "json": { "type": "object", "properties": { "sort_by": { "type": "string", "description": "Field to sort results by. One of: price, name, created_date, popularity", "default": "created_date" }, "sort_order": { "type": "string", "description": "Order of sorting (ascending or descending). One of: asc, desc", "default": "desc" }, }, "required": [] } } } }, { "toolSpec": { "name": "get_products_by_id", "description": "API to retrieve retail products based on search criteria", "inputSchema": { "json": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Unique identifier of the product" }, }, "required": ["product_id"] } } } } ] } ``` ------ #### [ Auto ] Die Verwendung von `auto` als Tool-Auswahl ist die Standardfunktion der Tool-Unterstützung und ermöglicht es dem Modell zu entscheiden, wann ein Tool aufgerufen wird und wie viele Tools aufgerufen werden sollen. Dies ist das Verhalten, wenn Sie die Tool-Auswahl nicht in Ihre Anfrage aufnehmen. **Anmerkung** Das Standardverhalten beim Aufrufen von Amazon Nova-Tools ist die Verwendung chain-of-thought für die Werkzeugauswahl. Bei Verwendung des Standardverhaltens oder der Standard-Tool-Auswahl `auto`, wird auch der Denkprozess in -Tags ausgegeben. Das folgende Beispiel veranschaulicht einen Anwendungsfall für einen Chatbot, bei dem es wünschenswert sein könnte, dass das Modell im Internet nach aktuellen Informationen sucht oder direkt auf den Benutzer reagiert. Diese Tool-Auswahl bietet Flexibilität und überlässt die Argumentation dem Modell. ``` tool_config = { "toolChoice": { "auto": {} }, "tools": [ { "toolSpec": { "name": "search", "description": "API that provides access to the internet", "inputSchema": { "json": { "type": "object", "properties": { "query": { "type": "string", "description": "Query to search by", }, }, "required": ["query"] } } } } ] } ``` ------ **Anmerkung** Bei der Einstellung des Tool-Auswahlparameters kann es vorkommen, dass der Modellausgabetext weiterhin angezeigt wird oder dass nach der ursprünglichen Tool-Auswahl sequenzielle Tool-Aufrufe durchgeführt werden. Wir empfehlen, hier eine Stoppsequenz festzulegen, um die Ausgabe auf das Tool zu beschränken: ``` “stopSequences”: [“”] ``` Weitere Informationen finden Sie [InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_InferenceConfiguration.html)im Amazon Bedrock API-Leitfaden. # Rückgabe von Tool-Ergebnissen Nachdem das Tool von der Anwendung aufgerufen wurde, besteht der letzte Schritt darin, das Ergebnis des Tools an das Modell zu übergeben. Dies wird erreicht, indem ein Tool-Ergebnis mit der ID des Tool-Aufrufs und dem Antwortinhalt zurückgegeben wird. Dieser Inhalt folgt dem [ToolResultBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultBlock.html)Schema: ``` { "toolResult": { "toolUseId": tool['toolUseId'], "content": [{"json": {"song": song, "artist": artist}}], "status": "success" } } ``` Der Inhalt von `ToolResultBlock` sollte entweder ein einzelnes JSON oder eine Mischung aus Text und Bildern sein. Das Statusfeld kann verwendet werden, um dem Modell den Status der Werkzeugausführung mitzuteilen. Wenn die Ausführung des Tools fehlgeschlagen ist, können Sie den Fehler angeben, und Amazon Nova wird versuchen, den ursprünglichen Tool-Aufruf zu ändern. Weitere Informationen zum Schema finden Sie in der [ToolResultContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultContentBlock.html)Dokumentation. Hier finden Sie ein Beispiel für die Verwendung der Converse-API für die Rückgabe von Tool-Ergebnissen: ``` messages.append({ "role": "user", "content": [ { "toolResult": { "toolUseId": tool['toolUseId'], "content": [{"json": {"song": song, "artist": artist}}], "status": "success" } } ] }) inf_params = {"maxTokens": 1000, "temperature": 0} # Send the tool result to the model. response = client.converse( modelId="us.amazon.nova-lite-v1:0", messages=messages, toolConfig=tool_config, inferenceConfig=inf_params ) print(response['output']['message']) ``` Weitere Informationen zur Nutzung der Tools finden Sie in der Dokumentation zur [Verwendung von Tools in Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html) oder in den [Beispielen zur Tool-Verwendung](https://github.com/aws-samples/amazon-nova-samples/blob/main/multimodal-understanding/repeatable-patterns/10-tool-calling-with-converse/10_tool_calling_with_converse.ipynb) im Amazon-Nova-Beispiel-Repository. # Integrierte Tools verwenden Integrierte Tools sind vollständig verwaltete Tools, die sofort einsatzbereit sind, sodass keine benutzerdefinierte Implementierung erforderlich ist. Diese können in der Converse-API mit einem einfachen Schalter aktiviert werden. ## Code-Interpreter Mit dem Code Interpreter kann Nova Python-Code in isolierten Sandbox-Umgebungen sicher ausführen. Dies ermöglicht das Schreiben und Ausführen von Code, das Analysieren von Daten, das Erstellen von Visualisierungen und das Lösen mathematischer Probleme. Code Interpreter kann beispielsweise verwendet werden, um: + Generieren Sie Finanzberichte auf der Grundlage hochgeladener Daten + Vollständige statistische Analysen oder Algorithmussimulationen + Führen Sie Datenbankmigrationsskripten in isolierten Umgebungen aus + Führen Sie Komponententests für neu generierten Code aus Hier ist ein Beispiel dafür, wie Sie den Code Interpreter mit der Converse-API aktivieren: ``` { "messages": [ { "role": "user", "content": [{"text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82")}] } ], "toolConfig": { "tools": [ { "systemTool": { "name": "nova_code_interpreter" } } ] }, ``` In diesem Fall stellt das Modell fest, dass die Anforderung berechnet werden muss, sodass es den erforderlichen Python-Code generiert und das Codeinterpreter-Tool aufruft. ``` { "toolUse": { "input": { "code": "'''Calculate the average of the given numbers.'''\nnumbers = [10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82]\nsum_numbers = sum(numbers)\ncount = len(numbers)\naverage = sum_numbers / count\n(sum_numbers, count, average)" }, "name": "nova_code_interpreter", "toolUseId": "tooluse_WytfF0g1S5qUeEPm0ptOdQ", "type": "server_tool_use" } }, ``` Der Interpreter führt diesen Code in einer Sandbox aus und erfasst das Ergebnis, das in einem Standardschema ausgegeben wird: ``` { "stdOut": String, "stdErr": String, "exitCode": int, "isError": boolean } ``` In diesem Fall würden Sie Folgendes zurückerhalten: ``` { "toolResult": { "content": [ { "text": "{\"stdOut\":\"(1212, 12, 101.0)\",\"stdErr\":\"\",\"exitCode\":0,\"isError\":false}" } ], "status": "success", "toolUseId": "tooluse_WytfF0g1S5qUeEPm0ptOdQ", "type": "nova_code_interpreter_result" } } ``` ## Modellkontext-Protokoll Das Model Context Protocol (MCP) ist ein offener Standard, der es Entwicklern ermöglicht, sichere, bidirektionale Verbindungen zwischen ihren Datenquellen und KI-gestützten Tools aufzubauen. Anstatt benutzerdefinierte Adapter für jede API oder jeden Dienst zu schreiben, können Sie einen MCP-Server ausführen und Nova seine Tools automatisch über eine Client-Bridge erkennen lassen. Sobald die Verbindung hergestellt ist, behandelt Nova diese Tools wie jede andere externe Integration: Es entscheidet, wann sie aufgerufen werden, sendet die erforderlichen Parameter und bezieht die Ergebnisse in seine Antwort ein. # Einen Fehler melden In einigen Fällen können die von Amazon Nova ausgewählten Parameter zu einem externen Fehler führen. Es kann daher sinnvoll sein, dies an Amazon Nova zurückzumelden, damit die Anfrage geändert und erneut versucht werden kann. Um Fehler zu melden, geben Sie weiterhin ein Tool-Ergebnis zurück, ändern Sie jedoch den Status, um den Fehler zu melden, und geben Sie die Ausnahmemeldung weiter. Im Folgenden finden Sie ein Beispiel, das eine Fehlerstatusmeldung meldet: ``` tool_result_message = { "role": "user", "content": [ { "toolResult": { "toolUseId": tool["toolUseId"], "content": [{"text": "A validation exception occured on field: sample.field"}], "status": "error" } } ] } ``` ## Zusätzliche Verweise 1. [Ein Tool verwenden, um eine Modellantwort zu vervollständigen](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html) 1. [KI-Agenten mit Amazon Nova erstellen](agents.md) 1. [Bewährte Methoden zu Textverständnis-Prompts](prompting-text-understanding.md) 1. [Fehlerbehebung für Toolaufrufe](prompting-tool-troubleshooting.md)