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. # Tools verwenden (Funktionsaufruf) Tools erweitern die Funktionen von Amazon Nova, indem sie das Modell mit externen Funktionen wie APIs Datenbanken und Codeausführungsumgebungen verbinden. Die Verwendung von Tools ermöglicht Amazon Nova den Zugriff auf Echtzeitinformationen, die Durchführung von Berechnungen und die Interaktion mit externen Systemen. ## Grundlegendes zum Arbeitsablauf bei der Verwendung von Tools Die Verwendung von Tools mit Amazon Nova umfasst drei Hauptphasen: Benutzerabfrage und Tooldefinition Definieren Sie Tools, indem Sie JSON-Schemas bereitstellen, die die Funktionen und Eingabeanforderungen der einzelnen Tools beschreiben. Die Werkzeugkonfiguration muss explizite Angaben darüber enthalten, wann und wie die einzelnen Tools verwendet werden. Auswahl des Werkzeugs Wenn ein Benutzer eine Nachricht sendet, analysiert Amazon Nova sie, um festzustellen, ob ein Tool erforderlich ist. Diese automatische Toolauswahl untersucht den Kontext und entscheidet, welches Tool (falls vorhanden) aufgerufen werden soll. Wenn Amazon Nova ein geeignetes Tool identifiziert, gibt es den Namen des Tools und die erforderlichen Parameter zurück. Sie sind dafür verantwortlich, das Tool auf der Grundlage der Anfrage des Modells auszuführen. Das bedeutet, Code zu schreiben, der die Funktionalität des Tools aufruft und die vom Modell bereitgestellten Eingabeparameter verarbeitet. Ergebnisse zurückgeben Senden Sie nach der Ausführung des Tools die Ergebnisse in einem strukturierten Format mit JSON oder einer Kombination aus Text und Bildern an Amazon Nova zurück. Amazon Nova bezieht die Ausgabe des Tools in die endgültige Antwort ein. Wenn während der Ausführung Fehler auftreten, geben Sie dies in der Antwort des Tools an, damit Amazon Nova entsprechende Anpassungen vornehmen kann. ## Erstellen Sie ein Tool Definieren Sie Werkzeuge mithilfe einer Werkzeugkonfiguration, die eine Reihe von Werkzeugen und optional einen Werkzeugauswahlparameter umfasst. Jede Werkzeugspezifikation muss Folgendes enthalten: + **Name:** Klare Kennung für das Tool + **Beschreibung:** Prägnante Erläuterung der Funktionen des Tools + **Eingabeschema:** JSON-Schema, das die erforderlichen und optionalen Parameter definiert **Example Beispiel für eine Tool-Konfiguration** ``` tool_config = { "tools": [ { "toolSpec": { "name": "calculator", "description": "A calculator tool that can execute a math equation", "inputSchema": { "json": { "type": "object", "properties": { "equation": { "type": "string", "description": "The full equation to evaluate" } }, "required": ["equation"] } } } } ] } ``` ### Bewährte Methoden für Werkzeugdefinitionen + Achten Sie darauf, dass der Name und die Beschreibung die genaue Funktionalität des Tools explizit wiedergeben. Vermeiden Sie Tools, die sich semantisch zu ähnlich sind + Nehmen Sie wichtige Unterscheidungsmerkmale in die Beschreibung auf, damit das Modell zwischen ähnlichen Tools unterscheiden kann + Beschränken Sie JSON-Schemas auf zwei Verschachtelungsebenen, um eine optimale Leistung zu erzielen + Beschränken Sie Eingaben mithilfe von Schematypen (z. B. enum, int, float), anstatt die Struktur im Klartext zu beschreiben + Geben Sie mithilfe der JSON-Schemanotation erforderliche und optionale Parameter an (z. B. „required“: ["param1", „param2"]) + Validieren Sie Ihr JSON-Schema vor dem Absenden mit einem Standardvalidator + Platzieren Sie lange Zeichenkettenargumente an letzter Stelle im Schema und vermeiden Sie es, sie zu verschachteln ### Strukturierte Ausgabe mit eingeschränkter Dekodierung Amazon Nova-Modelle nutzen eingeschränkte Dekodierung, um eine hohe Zuverlässigkeit der generierten Ausgaben zu gewährleisten. Diese Technik verwendet Grammatik, um mögliche Token bei jedem Generierungsschritt einzuschränken, wodurch ungültige Schlüssel vermieden und korrekte Datentypen auf der Grundlage Ihres definierten Schemas durchgesetzt werden. **Example Beispiel für eine strukturierte Ausgabe** ``` tool_config = { "tools": [ { "toolSpec": { "name": "ProductAnalysis", "description": "Analyze product information from text.", "inputSchema": { "json": { "type": "object", "properties": { "name": { "type": "string", "description": "Product name" }, "rating": { "maximum": 5, "description": "Customer rating 1-5", "type": ["number", "null"], "minimum": 1 }, "features": { "description": "Key product features", "type": "array", "items": {"type": "string"} }, "category": { "type": "string", "description": "Product category" }, "price": { "type": "number", "description": "Price in USD" } }, "required": ["name", "category", "price", "features"] } } } } ], "toolChoice": { "tool": {"name": "ProductAnalysis"} } } ``` ### Optionen zur Werkzeugauswahl Amazon Nova unterstützt drei Parameter für die Werkzeugauswahl: Tool Das angegebene Tool wird einmal aufgerufen, ideal für Anwendungsfälle mit strukturierter Ausgabe Beliebig Eines der bereitgestellten Tools wird mindestens einmal aufgerufen, was für API-Auswahlszenarien nützlich ist Automatisch Das Modell entscheidet, ob und wie viele Tools aufgerufen werden sollen (Standardverhalten) ## Rufen Sie ein Tool auf Wenn Amazon Nova beschließt, ein Tool aufzurufen, gibt es als Teil der Assistentennachricht einen Werkzeugverwendungsblock zurück, wobei stopReason auf „tool\$1use“ gesetzt ist. Der Werkzeugblock enthält den Namen des Tools und seine Eingaben. **Anmerkung** Führen Sie die folgenden Codeabschnitte nacheinander (Werkzeug aufrufen → Werkzeugaufruf verarbeiten → Werkzeugergebnisse zurückgeben) in einer einzigen Python-Sitzung aus. Um die Beispiele erneut auszuführen, starten Sie Ihre Python-Sitzung neu. **Example Ein Tool aufrufen** ``` import boto3 import json # Create Bedrock client bedrock = boto3.client('bedrock-runtime', region_name='us-east-1') # Complex calculation that benefits from precise computation messages = [{ "role": "user", "content": [{ "text": "Calculate the compound interest on $10,000 invested at 4.75% annual rate for 7 years, compounded quarterly. Use the formula A = P(1 + r/n)^(nt) where P=10000, r=0.0475, n=4, t=7" }] }] # Define tool configuration with calculator tool_config = { "tools": [{ "toolSpec": { "name": "calculator", "description": "Perform mathematical calculations", "inputSchema": { "json": { "type": "object", "properties": { "expression": { "type": "string", "description": "Mathematical expression to evaluate" } }, "required": ["expression"] } } } }] } # Invoke Model response = bedrock.converse( modelId="us.amazon.nova-2-lite-v1:0", messages=messages, toolConfig=tool_config ) # Extract tool use from response tool = next( block["toolUse"] for block in response["output"]["message"]["content"] if "toolUse" in block ) print(f"Tool: {tool['name']}") print(f"Expression: {tool['input']['expression']}") ``` ### Tool-Aufrufe werden verarbeitet Extrahieren Sie den Namen und die Argumente des Tools aus der Nachricht und rufen Sie dann das Tool auf: ``` def calculate(expression): """Evaluate mathematical expression""" print(f"Calculating: {expression}") P = 10000 r = 0.0475 n = 4 t = 7 result = P * (1 + r/n) ** (n*t) return result stop_reason = response["stopReason"] if stop_reason == "tool_use": if tool["name"] == "calculator": result = calculate(tool["input"]["expression"]) ``` ### Rückgabe von Tool-Ergebnissen Geben Sie die Werkzeugergebnisse mithilfe des ToolResultBlock Schemas zurück: ``` messages.append(response["output"]["message"]) # Add the tool result messages.append({ "role": "user", "content": [{ "toolResult": { "toolUseId": tool['toolUseId'], "content": [{"json": {"result": result}}], "status": "success" } }] }) # Send the tool result to the model response = bedrock.converse( modelId="us.amazon.nova-2-lite-v1:0", messages=messages, toolConfig=tool_config ) # Extract and display final response final_text = next( block["text"] for block in response["output"]["message"]["content"] if "text" in block ) print(f"\nFinal Response:\n{final_text}") ``` ### Fehlerbehandlung Melden Sie Fehler an Amazon Nova zurück, damit die Anfrage geändert werden kann, und versuchen Sie es erneut: ``` tool_result_message = { "role": "user", "content": [ { "toolResult": { "toolUseId": tool["toolUseId"], "content": [{"text": "A validation exception occurred on field: sample.field"}], "status": "error" } } ] } ``` ### Sicherheitsüberlegungen + Stellen Sie sicher, dass Tools vorhanden sind, bevor Sie sie aufrufen + Stellen Sie sicher, dass die Eingaben korrekt formatiert sind + Stellen Sie vor der Ausführung des Tools sicher, dass die entsprechenden Berechtigungen vorhanden sind + Verlassen Sie sich auf Sitzungsdetails, anstatt Amazon Nova zu erlauben, Benutzerinformationen in Tool-Aufrufe einzufügen + Denken Sie daran, dass dies zu Halluzinationen bei Toolaufrufen führen LLMs kann. Überprüfen Sie immer, bevor Sie sie ausführen ## Integrierte Systemtools Die Modelle von Amazon Nova 2.0 enthalten vollständig verwaltete integrierte Tools, für die keine benutzerdefinierte Implementierung erforderlich ist. Aktivieren Sie diese Tools mit einem einfachen Schalter in der Converse-API. ### Code-Interpreter Mit dem Code Interpreter kann Nova Python-Code in isolierten Sandbox-Umgebungen sicher ausführen. Dieses Tool wurde für mathematische Berechnungen, logische Operationen und iterative Algorithmen entwickelt. **Anmerkung** Der Code Interpreter ist in den Regionen IAD, PDX und NRT verfügbar. AWS Verwenden Sie Global CRIS, um sicherzustellen, dass Ihre Anfragen an eine unterstützte Region weitergeleitet werden. Wenn Sie Bedrock API-Schlüssel verwenden, müssen Sie den Richtliniendefinitionen manuell `InvokeTool` Berechtigungen hinzufügen. Die Bedrock-Standardrolle erlaubt die `InvokeTool` Aktion nicht. Aktivieren Sie den Code Interpreter, indem Sie den SystemTool-Parameter angeben: ``` import boto3 import json bedrock = boto3.client('bedrock-runtime', region_name='us-east-1') tool_config = { "tools": [{ "systemTool": { "name": "nova_code_interpreter" } }] } response = bedrock.converse( modelId="us.amazon.nova-2-lite-v1:0", messages=[{ "role": "user", "content": [{ "text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82" }] }], toolConfig=tool_config, inferenceConfig={"maxTokens": 10000, "temperature": 0} ) # Pretty print the response for block in response["output"]["message"]["content"]: if "toolUse" in block: print("=== Tool Use ===") print(f"Tool: {block['toolUse']['name']}") print(f"Code:\n{block['toolUse']['input']['snippet']}\n") elif "toolResult" in block: print("=== Tool Result ===") result = block['toolResult']['content'][0]['json'] print(f"Output: {result['stdOut']}") if result['stdErr']: print(f"Error: {result['stdErr']}") print(f"Exit Code: {result['exitCode']}\n") elif "text" in block: print("=== Final Answer ===") print(block["text"]) ``` Der Interpreter führt Code in einer Sandbox aus und gibt Ergebnisse in einem Standardschema zurück: ``` { "stdOut": "String", "stdErr": "String", "exitCode": "int", "isError": "boolean" } ``` ### Web Grounding Web Grounding ermöglicht es Amazon Nova, in Echtzeit auf Informationen aus dem Internet zuzugreifen, up-to-date Antworten zu geben und Halluzinationen zu reduzieren. Aktivieren Sie diese Option, indem Sie das Systemtool nova\$1grounding angeben: ``` tool_config = { "tools": [{ "systemTool": {"name": "nova_grounding"} }] } ``` Ausführliche Informationen zu Web Grounding finden Sie unter. [Web Grounding](web-grounding.md) ### Model Context Protocol (MCP) Das Model Context Protocol (MCP) ist ein offener Standard, der sichere, bidirektionale Verbindungen zwischen Datenquellen und KI-gestützten Tools ermöglicht. Anstatt benutzerdefinierte Adapter für jede API oder jeden Service zu schreiben, führen Sie einen MCP-Server aus und lassen Sie Amazon Nova seine Tools automatisch über eine Client-Bridge erkennen. Sobald die Verbindung hergestellt ist, behandelt Amazon Nova MCP-Tools wie jede andere externe Integration: Es entscheidet, wann sie aufgerufen werden, sendet die erforderlichen Parameter und bezieht die Ergebnisse in die Antworten ein. Die Verwendung von Amazon Nova mit Strands erleichtert dies mit einer integrierten MCPClient Lösung, die Erkennung, Verbindung und Ergebniszuordnung automatisch verwaltet.