Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
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 el Converse API. Para ver el código de ejemplo, consulte Converse Ejemplos de uso de herramientas API.
Temas
Paso 1: envío del 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 las llamadas a herramientas basadas en JSON
La definición de la herramienta es un esquema JSON en el que se pasa el parámetro de solicitud toolConfig (ToolConfiguration) a la Converse operación. Para obtener más información acerca del esquema, consulte JSON schema
{ "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 Mantén una conversación con el Converse Operaciones de la API.
Paso 2: obtención de 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 popular en la emisora 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 respuesta stopReason en tool_use. La respuesta también identifica la herramienta (top_song) que el modelo quiere que usted ejecute y la emisora de radio (WZPZ) que quiere que usted 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). Específicamente, 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: envío del 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: 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: obtención de 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. A continuación, el modelo generará una respuesta que responde al mensaje original (¿Cuál es la canción más popular en la emisora WZPZ?) con la información que ha proporcionado en el campo toolResult del mensaje.
{ "output": { "message": { "role": "assistant", "content": [ { "text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike." } ] } }, "stopReason": "end_turn"
