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.

Aufrufen eines Tools über die Converse-API

Damit ein Modell ein Tool verwenden kann, um eine Antwort auf eine Nachricht zu vervollständigen, senden Sie die Nachricht und die Definitionen für ein oder mehrere Tools an das Modell. Wenn das Modell feststellt, dass mit einem der Tools eine Antwort generiert werden kann, wird eine Aufforderung zurückgegeben, das Werkzeug zu verwenden und die Werkzeugergebnisse an das Modell zurückzusenden. Das Modell verwendet dann die Ergebnisse, um eine Antwort auf die ursprüngliche Nachricht zu generieren.

Nachfolgend wird beschrieben, wie ein Tool mit der Converse-API verwendet wird. Einen Beispielcode finden Sie unter Beispiele für die Verwendung von Converse-API-Tools.

Schritt 1: Senden der Nachricht und Definition des Tools

Verwenden Sie die Vorgänge Converse oder ConverseStream (für Streaming-Antworten), um die Nachricht oder die Tool-Definition zu senden.

Die Definition des Tools ist ein JSON-Schema, das Sie im Anforderungsparameter toolConfig (ToolConfiguration) an den Converse-Vorgang übergeben. Weitere Informationen zum neuen Schema finden Sie unter JSON-Schema. Nachfolgend finden Sie ein Beispielschema für ein Tool, das den beliebtesten Song eines Radiosenders ermittelt.

{
    "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"
                        ]
                    }
                }
            }
        }
    ]
}

In derselben Anforderung übergeben Sie auch eine Benutzernachricht im Anforderungsparameter messages (Nachricht).

[
    {
        "role": "user",
        "content": [
            {
                "text": "What is the most popular song on WZPZ?"
            }
        ]
    }
]

Wenn Sie ein Anthropic Claude-3-Modell verwenden, können Sie die Verwendung eines Werkzeugs erzwingen, indem Sie das Feld toolChoice (ToolChoice) im toolConfig Anforderungsparameter angeben. Die Verwendung eines Tools zu erzwingen ist hilfreich, um Ihr Tool während der Entwicklung zu testen. Das folgende Beispiel zeigt, wie Sie die Verwendung eines Tools namens top_song erzwingen können.

{"tool" : {"name" : "top_song"}}

Weitere Informationen zu anderen Parameter, die Sie verwenden können, finden Sie unter Führen einer Konversation mit den Converse-API-Operationen.

Schritt 2: Abrufen der Tool-Anfrage vom Modell

Wenn Sie den Converse-Vorgang mit der Meldung und der Werkzeugdefinition aufrufen, ermittelt das Modell anhand der Werkzeugdefinition, ob das Werkzeug zur Beantwortung der Nachricht benötigt wird. Wenn Ihr Chat-App-Benutzer beispielsweise die Nachricht „Was ist das beliebteste Lied auf WZPZ?“ sendet, gleicht das Modell die Nachricht mit dem Schema in der top_song-Tool-Definition ab und stellt fest, dass eine Antwort mit dem Tool generiert werden kann.

Wenn das Modell entscheidet, dass es ein Werkzeug zum Generieren einer Antwort benötigt, legt das Modell das Antwortfeld stopReason auf tool_use fest. Die Antwort identifiziert auch das Tool (top_song), dessen Ausführung das Modell erfordert, und den Radiosender (WZPZ), den Sie mit dem Tool abfragen sollen. Informationen zum angeforderten Tool finden Sie in der Meldung, die das Modell im Feld output (ConverseOutput) zurückgibt. Insbesondere das Feld toolUse (ToolUseBlock). Sie verwenden das Feld toolUseId, um die Tool-Anfrage bei späteren Aufrufen zu identifizieren.

Das folgende Beispiel zeigt die Antwort von Converse nach der Übergabe der unter Schritt 1: Senden der Nachricht und Definition des Tools beschriebenen Meldung.

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "toolUse": {
                        "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                        "name": "top_song",
                        "input": {
                            "sign": "WZPZ"
                        }
                    }
                }
            ]
        }
    },
    "stopReason": "tool_use"
}

Schritt 3: Abrufen der Tool-Anfrage für das Modell

Verwenden Sie das Feld name aus dem Feld toolUse in der Modellantwort, um den Namen des Tools zu identifizieren. Rufen Sie dann Ihre Implementierung des Tools auf und übergeben Sie die Eingabeparameter aus dem Feld input.

Erstellen Sie als Nächstes eine Benutzernachricht, die den Inhaltsblock toolResult (ToolResultBlock) enthält. Fügen Sie in den Inhaltsblock die Antwort des Tools und die ID für die Tool-Anfrage ein, die Sie im vorherigen Schritt erhalten haben.

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "json": {
                            "song": "Elemental Hotel",
                            "artist": "8 Storey Hike"
                        }
                    }
                ]
            }
        }
    ]
}

Sollte im Tool ein Fehler auftreten, z. B. eine Anforderung für einen nicht vorhandenen Radiosender, können Sie Fehlerinformationen an das Modell im Feld toolResult senden. Um auf einen Fehler hinzuweisen, geben Sie error in das Feld status ein. Der folgende Beispielfehler bezieht sich auf den Fall, dass das Tool den Radiosender nicht finden kann.

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "text": "Station WZPA not found."
                    }
                ],
                "status": "error"
            }
        }
    ]
}

Schritt 4: Abrufen der Modellantwort

Setzen Sie die Konversation mit dem Modell fort, indem Sie die Benutzernachricht, die Sie im vorherigen Schritt erstellt haben, in einen Aufruf anConverse aufnehmen. Das Modell generiert dann eine Antwort, die die ursprüngliche Nachricht beantwortet (Was ist das beliebteste Lied auf WZPZ?) mit den Informationen, die Sie im Feld toolResult der Nachricht angegeben haben.

{
     "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike."
                }
            ]
        }
    },
    "stopReason": "end_turn"