View a markdown version of this page

Konfiguration des Tools - Amazon Nova
Tools definierenParameter für die WerkzeugauswahlEmpfangen und Verarbeiten von Nutzungsereignissen des ToolsBest Practices

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.

Konfiguration des Tools

Amazon Nova 2 Sonic unterstützt die Verwendung von Tools (auch bekannt als Funktionsaufruf), sodass das Modell während Konversationen externe Informationen oder Aktionen anfordern kann, z. B. API-Aufrufe, Datenbankabfragen oder benutzerdefinierte Codefunktionen. Auf diese Weise kann Ihr Sprachassistent auf der Grundlage von Benutzeranfragen Aktionen ergreifen, Informationen abrufen und externe Dienste integrieren.

Nova 2 Sonic bietet asynchrone Werkzeuganrufe, sodass die KI weiterhin auf natürliche Weise kommunizieren kann, während die Tools im Hintergrund ausgeführt werden. Dies sorgt für ein flüssigeres und reaktionsschnelleres Benutzererlebnis.

Im Folgenden finden Sie vereinfachte Schritte zur Verwendung von Tools:

  1. Tools definieren: Geben Sie die verfügbaren Tools mit ihren Parametern im PromptStart-Ereignis an

  2. Der Benutzer spricht: Der Benutzer stellt eine Anfrage, für die ein Tool erforderlich ist (z. B. „Wie ist das Wetter in Seattle?“)

  3. Aufruf des Tools: Nova 2 Sonic erkennt den Bedarf und sendet ein ToolUse-Ereignis

  4. Tool ausführen: Ihre Anwendung führt das Tool aus und gibt Ergebnisse zurück

  5. Generierung von Antworten: Nova 2 Sonic integriert die Ergebnisse in seine gesprochene Antwort

Das folgende Diagramm veranschaulicht, wie die Verwendung des Tools funktioniert:

Tools definieren

Tools werden mithilfe eines JSON-Schemas definiert, das ihren Zweck, ihre Parameter und die erwarteten Eingaben beschreibt.

Im Folgenden finden Sie Komponenten und Erläuterungen zur Tooldefinition:

  • Name: Eindeutiger Bezeichner für das Tool (verwenden Sie snake_case)

  • Beschreibung: Klare Erklärung, was das Tool macht; hilft der KI bei der Entscheidung, wann es verwendet werden soll

  • InputSchema: JSON-Schema, das die Parameter definiert, die das Tool akzeptiert

  • Eigenschaften: Einzelne Parameter mit Typen und Beschreibungen

  • Erforderlich: Array von Parameternamen, die angegeben werden müssen

Hier ist eine einfache Definition eines Wetter-Tools

{
  "toolSpec": {
    "name": "get_weather",
    "description": "Get current weather information for a specific location",
    "inputSchema": {
      "json": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name or zip code"
          },
          "units": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "Temperature units"
          }
        },
        "required": ["location"]
      }
    }
  }
}

Die Werkzeugkonfiguration wird in diesem promptStart Fall zusammen mit den Audio- und Textausgabeeinstellungen an Nova 2 Sonic übergeben:

{
    "event": {
        "promptStart": {
            "promptName": "<prompt-id>",
            "textOutputConfiguration": {
                "mediaType": "text/plain"
            },
            "audioOutputConfiguration": {
                "mediaType": "audio/lpcm",
                "sampleRateHertz": 16000,
                "sampleSizeBits": 16,
                "channelCount": 1,
                "voiceId": "matthew",
                "encoding": "base64",
                "audioType": "SPEECH"
            },
            "toolUseOutputConfiguration": {
                "mediaType": "application/json"
            },
            "toolConfiguration": {
                "tools": [
                    {
                        "toolSpec": {
                            "name": "get_weather",
                            "description": "Get current weather information for a specific location",
                            "inputSchema": {
                                "json": {
                                    "type": "object",
                                    "properties": {
                                        "location": {
                                            "type": "string",
                                            "description": "City name or zip code"
                                        },
                                        "units": {
                                            "type": "string",
                                            "enum": ["celsius", "fahrenheit"],
                                            "description": "Temperature units"
                                        }
                                    },
                                    "required": ["location"]
                                }
                            }
                        }
                    }
                ],
                "toolChoice": {
                    "auto": {}
                }
            }
        }
    }
}

Parameter für die Werkzeugauswahl

Nova 2 Sonic unterstützt drei Werkzeugauswahlparameter, mit denen Sie steuern können, wann und welche Werkzeuge verwendet werden. Geben Sie den ToolChoice-Parameter in Ihrer Werkzeugkonfiguration an:

  • Auto (Standard): Das Modell entscheidet, ob Werkzeuge benötigt werden, und kann bei Bedarf mehrere Tools aufrufen. Bietet maximale Flexibilität.

  • Beliebig: Stellt sicher, dass zu Beginn der Antwort mindestens eines der verfügbaren Tools aufgerufen wird, wobei das Modell das geeignetste auswählt. Nützlich, wenn Sie über mehrere Wissensdatenbanken oder Tools verfügen und sicherstellen möchten, dass eine verwendet wird.

  • Tool: Erzwingt, dass ein bestimmtes benanntes Tool zu Beginn der Antwort genau einmal aufgerufen wird. Wenn Sie beispielsweise ein Knowledge-Base-Tool angeben, fragt das Modell es ab, bevor es antwortet, unabhängig davon, ob es das Tool für erforderlich hält.

Beispiele für die Werkzeugauswahl

Auto (Standard)

"toolChoice": { 
    "auto": {} 
}

Beliebig:

"toolChoice": {
    "any": {}
}

Spezifisches Tool:

"toolChoice": {
    "tool": {
        "name": "get_weather"
    }
}

Empfangen und Verarbeiten von Nutzungsereignissen des Tools

Wenn Amazon Nova 2 Sonic feststellt, dass ein Tool benötigt wird, sendet es ein toolUse Ereignis, das Folgendes enthält:

  1. toolUseID: eindeutiger Bezeichner für diesen Tool-Aufruf

  2. ToolName: der Name des auszuführenden Tools

  3. Inhalt: JSON-Zeichenfolge mit Parametern, die aus der Anfrage des Benutzers extrahiert wurden

  4. sessionId: Aktuelle Sitzungs-ID

  5. Rolle: für Ereignisse zur Verwendung von Tools auf „TOOL“ gesetzt

Beispiel für ein Ereignis zur Verwendung eines Tools

{
    "event": {
        "toolUse": {
            "completionId": "<completion-id>",
            "content": "{\"location\": \"Seattle\", \"units\": \"fahrenheit\"}",
            "contentId": "<content-id>",
            "promptName": "<prompt-id>",
            "role": "TOOL",
            "sessionId": "<session-id>",
            "toolName": "get_weather",
            "toolUseId": "<tool-use-id>"
        }
    }
}

Schritte der Verarbeitung

  1. Erhalte das ToolUse-Event von Nova 2 Sonic

  2. Extrahieren Sie den Namen und die Parameter des Tools aus dem Ereignis

  3. Führen Sie Ihre Toollogik aus (API-Aufruf, Datenbankabfrage usw.)

  4. Geben Sie das Ergebnis mithilfe eines ToolResult-Ereignisses zurück

Beispiel für ein Ereignis ToolResult 

{
    "event": {
        "toolResult": {
            "promptName": "<prompt-id>",
            "contentName": "<content-id>",
            "content": "{\"temperature\": 72, \"condition\": \"sunny\", \"humidity\": 45}"
        }
    }
}

Best Practices

  • Klare Beschreibungen: Schreiben Sie detaillierte Werkzeugbeschreibungen, damit Nova 2 Sonic versteht, wann die einzelnen Tools verwendet werden müssen.

  • Parameter validieren: Überprüfen Sie die Werkzeugparameter immer vor der Ausführung, um Fehler zu vermeiden. Definieren Sie Werkzeugparameter, wann immer möglich, mithilfe eines geeigneten JSON-Schemas mit strukturierten Datentypen (wie Aufzählungen, Zahlen oder Booleschen Werten) anstelle von Zeichenketten mit offenen Enden.

  • Fehlerbehandlung: Gibt aussagekräftige Fehlermeldungen in ToolResult-Ereignissen zurück, wenn Tools fehlschlagen.

  • Asynchrone Ausführung: Nutzen Sie asynchrone Tool-Aufrufe, um den Konversationsfluss aufrechtzuerhalten.

  • Benennung von Tools: Verwenden Sie beschreibende, aktionsorientierte Namen (wie get_weather, search_database, send_email).