Rufen Sie mit dem Converse ein Tool auf API

Damit ein Modell ein Werkzeug verwenden kann, um eine Antwort auf eine Nachricht zu vervollständigen, senden Sie die Nachricht und die Definitionen für ein oder mehrere Werkzeuge an das Modell. Wenn das Modell feststellt, dass eines der Tools beim Generieren einer Antwort helfen 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.

Die folgenden Schritte zeigen, wie Sie ein Tool mit dem Converse API verwenden. Beispielcode finden Sie unter Anwendungsbeispiele für API Converse-Tools.

Schritt 1: Senden Sie die Nachricht und die Tooldefinition

Um die Nachricht und die Tooldefinition zu senden, verwenden Sie die Operationen Converse oder ConverseStream(für Streaming-Antworten).

Anmerkung

Meta enthält spezifische Empfehlungen für die Erstellung von Eingabeaufforderungen, bei denen Tools mit verwendet werden Llama 3.1 (oder neuere) Modelle. Weitere Informationen finden Sie unter JSONBased Tool Calling im Meta -Dokumentation.

Die Definition des Tools ist ein JSON Schema, das Sie im Anforderungsparameter toolConfig (ToolConfiguration) an den Converse Vorgang übergeben. Informationen zum Schema finden Sie unter JSONSchema. Im Folgenden finden Sie ein Beispielschema für ein Tool, mit dem das beliebteste Lied abgerufen wird, das auf einem Radiosender abgespielt wurde.

{
    "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 Anfrage übergeben Sie auch eine Benutzernachricht im Anforderungsparameter messages (Message).

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

Wenn Sie eine verwenden Anthropic Claude Modell 3, Sie können die Verwendung eines Werkzeugs erzwingen, indem Sie das Feld toolChoice (ToolChoice) im toolConfig Anforderungsparameter angeben. Die Verwendung eines Tools zu erzwingen ist nützlich, 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"}}

Hinweise zu anderen Parametern, die Sie übergeben können, finden Sie unter. Führen Sie ein Gespräch mit den Converse-Betrieben API

Schritt 2: Rufen Sie die Werkzeuganforderung vom Modell ab

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 „Welcher Song ist der beliebteste Song?“ sendet WZPZ , gleicht das Modell die Nachricht mit dem Schema in der top_song-Tooldefinition ab und stellt fest, dass das Tool bei der Generierung einer Antwort helfen kann.

Wenn das Modell entscheidet, dass es ein Werkzeug zum Generieren einer Antwort benötigt, setzt das Modell das stopReason Antwortfeld auf. tool_use Die Antwort identifiziert auch das Tool (top_song), das Sie nach dem Modell ausführen sollen, und den Radiosender (WZPZ), den Sie mit dem Werkzeug abfragen sollen. Informationen über das angeforderte Werkzeug finden Sie in der Meldung, die das Modell im Feld output (ConverseOutput) zurückgibt. Insbesondere das Feld toolUse (ToolUseBlock). Sie verwenden das toolUseId Feld, um die Werkzeuganforderung bei späteren Aufrufen zu identifizieren.

Das folgende Beispiel zeigt die AntwortConverse, wenn Sie die unter beschriebene Nachricht weiterleitenSchritt 1: Senden Sie die Nachricht und die Tooldefinition.

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

Schritt 3: Stellen Sie die Werkzeuganforderung für das Modell

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

Konstruieren Sie als Nächstes eine Benutzernachricht, die einen 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 Anfrage für einen Radiosender, der nicht existiert, können Sie Fehlerinformationen an das Modell vor toolResult Ort senden. Um auf einen Fehler hinzuweisen, geben Sie diesen error in das status Feld 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: Holen Sie sich die Antwort des Modells

Setzen Sie die Konversation mit dem Modell fort, indem Sie die Benutzernachricht, die Sie im vorherigen Schritt erstellt haben, in einen Call to aufnehmenConverse. Das Modell generiert dann eine Antwort, die die ursprüngliche Nachricht beantwortet (Was ist das beliebteste Lied vonWZPZ? ) mit den Informationen, die Sie im toolResult Feld 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"