Llame a una herramienta con el 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. En su respuesta, el modelo utiliza los resultados para generar una respuesta para el mensaje original.

En los pasos siguientes se muestra cómo utilizar una herramienta con Converse API. Para ver un código de ejemplo, consulteConverse APIejemplos de uso de herramientas.

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 esquema de ejemplo para una herramienta que obtiene la canción más popular de 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 pasa un mensaje de usuario en el parámetro de solicitud messages (Message).

[
    {
        "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 más información acerca de otros parámetros que puede pasar, consulte Mantenga una conversación con el Converse Operaciones de API.

Paso 2: obtener la solicitud de herramienta del modelo

Al invocar la operación Converse 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 popularWZPZ? , 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 respuesta stopReason 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 campo toolUseId se utiliza para identificar la solicitud de herramienta en llamadas posteriores.

En el siguiente ejemplo se muestra la respuesta de Converse al pasar el mensaje descrito en Paso 1: enviar el mensaje y la definición de la herramienta.

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

Paso 3: realizar la solicitud de la herramienta para el modelo

En el campo toolUse de la respuesta del modelo, utilice el campo name 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 campo input.

A continuación, cree un mensaje de usuario que incluya un bloque de contenido toolResult (ToolResultBlock). En el bloque de contenido, incluya la respuesta de la herramienta y el ID de la solicitud de herramienta que ha recibido 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 que no existe, puede enviar la información del error al modelo en el campo toolResult. Para indicar un error, especifique error en el campo status. 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: obtener la respuesta del modelo

Continúe la conversación con el modelo e incluya el mensaje de usuario creado en el paso anterior en una llamada a Converse. Luego, el 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"