Claude Academy
Cargando

Ejecutando funciones de herramientas

Lección 2510 min

Cuando Claude responde con una solicitud de uso de herramientas, tu servidor necesita ejecutar realmente 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 manera 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.

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

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 diccionarios que contengan 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 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:

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 IDs 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:

Cada uso de herramienta obtiene un ID único (como "ab3" y "po9"), y tus resultados de herramienta deben incluir los IDs correspondientes para que Claude sepa qué resultado corresponde a qué solicitud.

Manejo de errores

Envuelve la ejecución de tu herramienta en bloques try-catch. Claude es inteligente con 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.