Uso paralelo de herramientas

ConstruirHerramientas

Uso paralelo de herramientas

Habilita y formatea llamadas de herramientas paralelas, con orientación del historial de mensajes y solución de problemas.

Esta página cubre llamadas de herramientas paralelas: cuando Claude llama a múltiples herramientas en un turno, cómo formatear el historial de mensajes para que el paralelismo siga funcionando, y cómo deshabilitarlo. Para el flujo de una sola llamada, consulta Manejar llamadas de herramientas.

Por defecto, Claude puede usar múltiples herramientas para responder a una consulta del usuario. Puedes deshabilitar este comportamiento mediante:

Establecer disable_parallel_tool_use=true cuando el tipo de tool_choice es auto, lo que asegura que Claude use como máximo una herramienta
Establecer disable_parallel_tool_use=true cuando el tipo de tool_choice es any o tool, lo que asegura que Claude use exactamente una herramienta

Ejemplo práctico

Más simple con Tool Runner: El ejemplo a continuación muestra el manejo manual de herramientas paralelas. Para la mayoría de casos de uso, Tool Runner maneja automáticamente la ejecución de herramientas paralelas con mucho menos código.

Aquí hay un script completo y ejecutable para probar y verificar que las llamadas de herramientas paralelas funcionan correctamente:

# Define tools
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York",
                }
            },
            "required": ["timezone"],
        },
    },
]

# Test conversation with parallel tool calls
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?",
    }
]

# Make initial request
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-opus-4-7", max_tokens=1024, messages=messages, tools=tools
)

# Check for parallel tool calls
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude made {len(tool_uses)} tool calls")

if len(tool_uses) > 1:
    print("✓ Parallel tool calls detected!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ No parallel tool calls detected")

# Simulate tool execution and format results correctly
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, partly cloudy"
        else:
            result = "New York: 45°F, clear skies"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM EST"

    tool_results.append(
        {"type": "tool_result", "tool_use_id": tool_use.id, "content": result}
    )

# Continue conversation with tool results
messages.extend(
    [
        {"role": "assistant", "content": response.content},
        {"role": "user", "content": tool_results},  # All results in one message!
    ]
)

# Get final response
print("\nGetting final response...")
final_response = client.messages.create(
    model="claude-opus-4-7", max_tokens=1024, messages=messages, tools=tools
)

print(f"\nClaude's response:\n{final_response.content[0].text}")

# Verify formatting
print("\n--- Verification ---")
print(f"✓ Tool results sent in single user message: {len(tool_results)} results")
print("✓ No text before tool results in content array")
print("✓ Conversation formatted correctly for future parallel tool use")

Este script demuestra:

Cómo formatear correctamente llamadas de herramientas paralelas y resultados
Cómo verificar que se están realizando llamadas paralelas
La estructura de mensaje correcta que fomenta el uso futuro de herramientas paralelas
Errores comunes a evitar (como texto antes de resultados de herramientas)

Ejecuta este script para probar tu implementación y asegurar que Claude está realizando llamadas de herramientas paralelas de manera efectiva.

Maximizar el uso de herramientas paralelas

Aunque los modelos Claude 4 tienen excelentes capacidades de uso de herramientas paralelas por defecto, puedes aumentar la probabilidad de ejecución de herramientas paralelas en todos los modelos con indicaciones dirigidas:

Solución de problemas

Si Claude no está realizando llamadas de herramientas paralelas cuando se espera, verifica estos problemas comunes:

1. Formato incorrecto de resultados de herramientas

El problema más común es formatear incorrectamente los resultados de herramientas en el historial de conversación. Esto "enseña" a Claude a evitar llamadas paralelas.

Específicamente para el uso de herramientas paralelas:

❌ Incorrecto: Enviar mensajes de usuario separados para cada resultado de herramienta
✅ Correcto: Todos los resultados de herramientas deben estar en un único mensaje de usuario

// ❌ Esto reduce el uso de herramientas paralelas
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Mensaje separado
]

// ✅ Esto mantiene el uso de herramientas paralelas
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Mensaje único
]

Consulta Manejar llamadas de herramientas para otras reglas de formato.

2. Indicaciones débiles

Las indicaciones predeterminadas pueden no ser suficientes. Usa la indicación del sistema más fuerte de la sección Maximizar el uso de herramientas paralelas anterior.

3. Medir el uso de herramientas paralelas

Para verificar que las llamadas de herramientas paralelas están funcionando:

# Calculate average tools per tool-calling message
tool_call_messages = [
    msg for msg in messages if any(block.type == "tool_use" for block in msg.content)
]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"]) for msg in tool_call_messages
)
avg_tools_per_message = (
    total_tool_calls / len(tool_call_messages) if tool_call_messages else 0.0
)
print(f"Average tools per message: {avg_tools_per_message}")
# Should be > 1.0 if parallel calls are working

Próximos pasos

Para el flujo de una sola llamada de herramienta y las reglas de formato de tool_result, consulta Manejar llamadas de herramientas.
Para la abstracción del SDK que maneja la ejecución paralela automáticamente, consulta Tool Runner.
Para el flujo completo de uso de herramientas, consulta Definir herramientas.

Was this page helpful?

ConstruirHerramientas

Uso paralelo de herramientas

Habilita y formatea llamadas de herramientas paralelas, con orientación del historial de mensajes y solución de problemas.

Por defecto, Claude puede usar múltiples herramientas para responder a una consulta del usuario. Puedes deshabilitar este comportamiento mediante:

Establecer disable_parallel_tool_use=true cuando el tipo de tool_choice es auto, lo que asegura que Claude use como máximo una herramienta
Establecer disable_parallel_tool_use=true cuando el tipo de tool_choice es any o tool, lo que asegura que Claude use exactamente una herramienta

Ejemplo práctico

Aquí hay un script completo y ejecutable para probar y verificar que las llamadas de herramientas paralelas funcionan correctamente:

# Define tools
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York",
                }
            },
            "required": ["timezone"],
        },
    },
]

# Test conversation with parallel tool calls
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?",
    }
]

# Make initial request
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-opus-4-7", max_tokens=1024, messages=messages, tools=tools
)

# Check for parallel tool calls
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude made {len(tool_uses)} tool calls")

if len(tool_uses) > 1:
    print("✓ Parallel tool calls detected!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ No parallel tool calls detected")

# Simulate tool execution and format results correctly
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, partly cloudy"
        else:
            result = "New York: 45°F, clear skies"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM EST"

    tool_results.append(
        {"type": "tool_result", "tool_use_id": tool_use.id, "content": result}
    )

# Continue conversation with tool results
messages.extend(
    [
        {"role": "assistant", "content": response.content},
        {"role": "user", "content": tool_results},  # All results in one message!
    ]
)

# Get final response
print("\nGetting final response...")
final_response = client.messages.create(
    model="claude-opus-4-7", max_tokens=1024, messages=messages, tools=tools
)

print(f"\nClaude's response:\n{final_response.content[0].text}")

# Verify formatting
print("\n--- Verification ---")
print(f"✓ Tool results sent in single user message: {len(tool_results)} results")
print("✓ No text before tool results in content array")
print("✓ Conversation formatted correctly for future parallel tool use")

Este script demuestra:

Cómo formatear correctamente llamadas de herramientas paralelas y resultados
Cómo verificar que se están realizando llamadas paralelas
La estructura de mensaje correcta que fomenta el uso futuro de herramientas paralelas
Errores comunes a evitar (como texto antes de resultados de herramientas)

Ejecuta este script para probar tu implementación y asegurar que Claude está realizando llamadas de herramientas paralelas de manera efectiva.

Maximizar el uso de herramientas paralelas

Solución de problemas

Si Claude no está realizando llamadas de herramientas paralelas cuando se espera, verifica estos problemas comunes:

1. Formato incorrecto de resultados de herramientas

El problema más común es formatear incorrectamente los resultados de herramientas en el historial de conversación. Esto "enseña" a Claude a evitar llamadas paralelas.

Específicamente para el uso de herramientas paralelas:

❌ Incorrecto: Enviar mensajes de usuario separados para cada resultado de herramienta
✅ Correcto: Todos los resultados de herramientas deben estar en un único mensaje de usuario

// ❌ Esto reduce el uso de herramientas paralelas
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Mensaje separado
]

// ✅ Esto mantiene el uso de herramientas paralelas
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Mensaje único
]

Consulta Manejar llamadas de herramientas para otras reglas de formato.

2. Indicaciones débiles

Las indicaciones predeterminadas pueden no ser suficientes. Usa la indicación del sistema más fuerte de la sección Maximizar el uso de herramientas paralelas anterior.

3. Medir el uso de herramientas paralelas

Para verificar que las llamadas de herramientas paralelas están funcionando:

# Calculate average tools per tool-calling message
tool_call_messages = [
    msg for msg in messages if any(block.type == "tool_use" for block in msg.content)
]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"]) for msg in tool_call_messages
)
avg_tools_per_message = (
    total_tool_calls / len(tool_call_messages) if tool_call_messages else 0.0
)
print(f"Average tools per message: {avg_tools_per_message}")
# Should be > 1.0 if parallel calls are working

Próximos pasos

Para el flujo de una sola llamada de herramienta y las reglas de formato de tool_result, consulta Manejar llamadas de herramientas.
Para la abstracción del SDK que maneja la ejecución paralela automáticamente, consulta Tool Runner.
Para el flujo completo de uso de herramientas, consulta Definir herramientas.

Was this page helpful?

Ejemplo práctico

Maximizar el uso de herramientas paralelas

Indicaciones del sistema para uso de herramientas paralelas

Indicaciones de mensajes de usuario

Solución de problemas

Próximos pasos

Ejemplo práctico

Maximizar el uso de herramientas paralelas

Indicaciones del sistema para uso de herramientas paralelas

Indicaciones de mensajes de usuario

Solución de problemas

Próximos pasos