Cargando

Ejecutando funciones de herramientas

Lección 2510 min
Cargando

Cuando Claude responde con una solicitud de uso de herramientas, tu servidor necesita realmente ejecutar la herramienta solicitada y enviar los resultados de vuelta. Este paso implica extraer las partes de uso de herramientas de la respuesta de Claude, ejecutar las funciones apropiadas y formatear los resultados correctamente.

Manejo de múltiples solicitudes de herramientas

Claude puede enviar múltiples partes de uso de herramientas en una sola respuesta. Tu código necesita manejar esta posibilidad de forma defensiva. Un mensaje del asistente podría contener una parte de texto seguida de una, dos o incluso más partes de uso de herramientas.

Partes del mensaje del asistente: una parte de "Texto" ofreciendo encontrar la hora actual y una parte de "toolUse" para get_current_datetime.

El flujo funciona así: Claude envía una solicitud con un esquema JSON, recibe una parte de uso de herramienta, luego tu servidor ejecuta la herramienta y envía de vuelta una parte de resultado de herramienta para que Claude proporcione una respuesta final.

Nuestro servidor envía a Claude el mensaje del usuario "¿Qué hora es?", el texto del asistente y la parte de uso de herramienta, luego una parte de resultado de herramienta.

Extracción de partes de uso de herramientas

Primero, crea una función para procesar todas las partes devueltas de una solicitud de chat:

python
def run_tools(parts):
    tool_requests = [part for part in parts if "toolUse" in part]
    tool_result_parts = []
    
    for tool_request in tool_requests:
        tool_use_id = tool_request["toolUse"]["toolUseId"]
        tool_name = tool_request["toolUse"]["name"]
        tool_input = tool_request["toolUse"]["input"]

Esta comprensión filtra la lista de partes para incluir solo los diccionarios que contienen una clave "toolUse", ignorando las partes de texto.

Ejecución de las herramientas reales

Crea una función auxiliar para ejecutar la herramienta solicitada:

python
def run_tool(tool_name, tool_input):
    if tool_name == "get_current_datetime":
        return get_current_datetime(**tool_input)
    else:
        raise Exception(f"Unknown tool name: {tool_name}")

El detalle clave aquí es usar **tool_input para desempaquetar el diccionario de argumentos en tu función de herramienta. Claude siempre devuelve los argumentos como un objeto de diccionario, por lo que necesitas desempaquetarlo correctamente.

Creación de partes de resultado de herramienta

Después de ejecutar una herramienta, necesitas formatear la respuesta como una parte de resultado de herramienta:

Una lista de contenido de mensaje del asistente con una parte de texto y dos partes de "toolUse", para get_current_datetime y other_tool.

Las partes de resultado de herramienta requieren tres propiedades clave:

  • toolUseId - Debe coincidir con el ID de la parte de uso de herramienta original
  • content - La salida de tu herramienta, serializada como una cadena
  • status - Ya sea "success" o "error"

Comprendiendo los ID de uso de herramientas

El sistema de ID de uso de herramientas se vuelve importante cuando Claude solicita múltiples herramientas en paralelo. Por ejemplo, si Claude quiere ejecutar una herramienta de calculadora dos veces:

Claude envía usos de herramienta de calculadora ab3 para 10 + 10 y po9 para 30 + 30; nuestro servidor devuelve po9 salida 60 y ab3 salida 20. Claude envía usos de herramienta de calculadora ab3 para 10 + 10 y po9 para 30 + 30; nuestro servidor devuelve po9 salida 60 y ab3 salida 20.

Cada uso de herramienta recibe un ID único (como "ab3" y "po9"), y los resultados de tus herramientas deben incluir los ID coincidentes para que Claude sepa qué resultado corresponde a cuál solicitud.

Manejo de errores

Envuelve la ejecución de tu herramienta en bloques try-catch. Claude es inteligente respecto a los errores de herramientas y podría ajustar su enfoque si devuelves información de error adecuada:

python
try:
    tool_output = run_tool(tool_name, tool_input)
    tool_result_part = {
        "toolResult": {
            "toolUseId": tool_use_id,
            "content": [{"text": json.dumps(tool_output)}],
            "status": "success"
        }
    }
except Exception as e:
    tool_result_part = {
        "toolResult": {
            "toolUseId": tool_use_id,
            "content": [{"text": f"Error: {e}"}],
            "status": "error"
        }
    }

Implementación completa

Aquí está la función completa que procesa las solicitudes de herramientas y devuelve resultados formateados:

python
def run_tools(parts):
    tool_requests = [part for part in parts if "toolUse" in part]
    tool_result_parts = []
    
    for tool_request in tool_requests:
        tool_use_id = tool_request["toolUse"]["toolUseId"]
        tool_name = tool_request["toolUse"]["name"]
        tool_input = tool_request["toolUse"]["input"]
        
        try:
            tool_output = run_tool(tool_name, tool_input)
            tool_result_part = {
                "toolResult": {
                    "toolUseId": tool_use_id,
                    "content": [{"text": json.dumps(tool_output)}],
                    "status": "success"
                }
            }
        except Exception as e:
            tool_result_part = {
                "toolResult": {
                    "toolUseId": tool_use_id,
                    "content": [{"text": f"Error: {e}"}],
                    "status": "error"
                }
            }
        
        tool_result_parts.append(tool_result_part)
    
    return tool_result_parts

Una vez que tengas las partes de resultado de herramienta, puedes enviarlas de vuelta a Claude en tu siguiente solicitud de chat, completando el ciclo de uso de herramientas.