Llama a una herramienta con Converse API

Para permitir que un modelo utilice una herramienta para completar la respuesta a un mensaje, debe enviar el mensaje y las definiciones de una o más herramientas al modelo. Si el modelo determina que una de las herramientas puede ayudar a generar una respuesta, devuelve una solicitud para que utilice la herramienta y envíe los resultados de la herramienta al modelo. A continuación, el modelo utiliza los resultados para generar una respuesta al mensaje original.

Los siguientes pasos muestran cómo utilizar una herramienta con la Converse. API Para ver el código de ejemplo, consulte Ejemplos de uso de la API herramienta Converse.

Paso 1: Enviar el mensaje y la definición de la herramienta

Para enviar el mensaje y la definición de la herramienta, utilice las operaciones Converse o ConverseStream(para transmitir las respuestas).

nota

Meta tiene recomendaciones específicas para crear mensajes que utilicen herramientas con Llama Modelos 3.1 (o posteriores). Para obtener más información, consulte la JSONfunción de llamada a herramientas basada en la Meta .

La definición de la herramienta es un JSON esquema en el que se pasa el parámetro de solicitud toolConfig (ToolConfiguration) a la Converse operación. Para obtener información sobre el esquema, consulte JSONesquema. El siguiente es un ejemplo de esquema de una herramienta que permite reproducir la canción más popular en una emisora de radio.

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

En la misma solicitud, también se pasa un mensaje de usuario en el parámetro de solicitud messages (Mensaje).

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

Si está utilizando un Anthropic Claude En el modelo 3, puede forzar el uso de una herramienta especificando el campo toolChoice (ToolChoice) en el parámetro de toolConfig solicitud. Forzar el uso de una herramienta es útil para probarla durante el desarrollo. El siguiente ejemplo muestra cómo forzar el uso de una herramienta llamada top_song.

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

Para obtener información sobre otros parámetros que puede pasar, consulte. Mantén una conversación con las operaciones de Converse API

Paso 2: Obtenga la solicitud de herramienta del modelo

Al invocar la Converse operación con el mensaje y la definición de la herramienta, el modelo utiliza la definición de la herramienta para determinar si la herramienta es necesaria para responder al mensaje. Por ejemplo, si el usuario de la aplicación de chat envía el mensaje ¿Cuál es la canción más popular? WZPZ , el modelo hace coincidir el mensaje con el esquema de la definición de la herramienta top_song y determina que la herramienta puede ayudar a generar una respuesta.

Cuando el modelo decide que necesita una herramienta para generar una respuesta, establece el campo de stopReason respuesta en. tool_use La respuesta también identifica la herramienta (top_song) que el modelo quiere que ejecute y la emisora de radio (WZPZ) que quiere que consulte con la herramienta. La información sobre la herramienta solicitada se encuentra en el mensaje que el modelo devuelve en el campo output (ConverseOutput). En concreto, el campo toolUse (ToolUseBlock). El toolUseId campo se utiliza para identificar la solicitud de herramienta en llamadas posteriores.

En el siguiente ejemplo, se muestra la respuesta Converse al pasar el mensaje descrito enPaso 1: Enviar el mensaje y la definición de la herramienta.

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

Paso 3: Realice la solicitud de herramienta para el modelo

En el toolUse campo de la respuesta del modelo, utilice el name campo para identificar el nombre de la herramienta. A continuación, llame a su implementación de la herramienta y pase los parámetros de entrada desde el input campo.

A continuación, cree un mensaje de usuario que incluya un bloque de contenido toolResult (ToolResultBlock). En el bloque de contenido, incluye la respuesta de la herramienta y el ID de la solicitud de herramienta que recibiste en el paso anterior.

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

Si se produce un error en la herramienta, como la solicitud de una emisora de radio inexistente, puedes enviar la información del error al modelo en el toolResult campo. Para indicar un error, especifíquelo error en el status campo. El siguiente ejemplo de error se debe a que la herramienta no encuentra la emisora de radio.

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

Paso 4: Obtenga la respuesta del modelo

Continúa la conversación con la modelo incluyendo el mensaje de usuario que creaste en el paso anterior en una llamada aConverse. A continuación, la modelo genera una respuesta que responde al mensaje original (¿Cuál es la canción más popularWZPZ? ) con la información que proporcionaste en el toolResult campo del mensaje.

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