Utilisation parallèle des outils

ConstruireOutils

Utilisation parallèle des outils

Activez et formatez les appels d'outils parallèles, avec des conseils sur l'historique des messages et la résolution des problèmes.

Cette page couvre les appels d'outils parallèles : quand Claude appelle plusieurs outils en un seul tour, comment formater l'historique des messages pour que le parallélisme continue de fonctionner, et comment le désactiver. Pour le flux d'appel unique, consultez Gérer les appels d'outils.

Par défaut, Claude peut utiliser plusieurs outils pour répondre à une requête utilisateur. Vous pouvez désactiver ce comportement en :

Définissant disable_parallel_tool_use=true quand le type tool_choice est auto, ce qui garantit que Claude utilise au maximum un outil
Définissant disable_parallel_tool_use=true quand le type tool_choice est any ou tool, ce qui garantit que Claude utilise exactement un outil

Exemple travaillé

Plus simple avec Tool Runner : L'exemple ci-dessous montre la gestion manuelle des outils parallèles. Pour la plupart des cas d'usage, Tool Runner gère automatiquement l'exécution parallèle des outils avec beaucoup moins de code.

Voici un script complet et exécutable pour tester et vérifier que les appels d'outils parallèles fonctionnent correctement :

# 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")

Ce script démontre :

Comment formater correctement les appels d'outils parallèles et les résultats
Comment vérifier que les appels parallèles sont en cours
La structure de message correcte qui encourage l'utilisation future d'outils parallèles
Les erreurs courantes à éviter (comme du texte avant les résultats des outils)

Exécutez ce script pour tester votre implémentation et vous assurer que Claude effectue des appels d'outils parallèles efficacement.

Maximiser l'utilisation parallèle des outils

Bien que les modèles Claude 4 aient d'excellentes capacités d'utilisation parallèle des outils par défaut, vous pouvez augmenter la probabilité d'exécution parallèle des outils sur tous les modèles avec un prompting ciblé :

Résolution des problèmes

Si Claude ne fait pas d'appels d'outils parallèles quand prévu, vérifiez ces problèmes courants :

1. Formatage incorrect des résultats des outils

Le problème le plus courant est de formater incorrectement les résultats des outils dans l'historique de la conversation. Cela « enseigne » à Claude d'éviter les appels parallèles.

Spécifiquement pour l'utilisation parallèle des outils :

❌ Incorrect : Envoyer des messages utilisateur séparés pour chaque résultat d'outil
✅ Correct : Tous les résultats des outils doivent être dans un seul message utilisateur

// ❌ Cela réduit l'utilisation parallèle des outils
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Message séparé
]

// ✅ Cela maintient l'utilisation parallèle des outils
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Message unique
]

Consultez Gérer les appels d'outils pour d'autres règles de formatage.

2. Prompting faible

Le prompting par défaut peut ne pas être suffisant. Utilisez l'invite système plus forte de la section Maximiser l'utilisation parallèle des outils ci-dessus.

3. Mesurer l'utilisation parallèle des outils

Pour vérifier que les appels d'outils parallèles fonctionnent :

# 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

Étapes suivantes

Pour le flux d'appel unique et les règles de formatage tool_result, consultez Gérer les appels d'outils.
Pour l'abstraction SDK qui gère l'exécution parallèle automatiquement, consultez Tool Runner.
Pour le flux de travail complet d'utilisation des outils, consultez Définir les outils.

Was this page helpful?

ConstruireOutils

Utilisation parallèle des outils

Activez et formatez les appels d'outils parallèles, avec des conseils sur l'historique des messages et la résolution des problèmes.

Par défaut, Claude peut utiliser plusieurs outils pour répondre à une requête utilisateur. Vous pouvez désactiver ce comportement en :

Définissant disable_parallel_tool_use=true quand le type tool_choice est auto, ce qui garantit que Claude utilise au maximum un outil
Définissant disable_parallel_tool_use=true quand le type tool_choice est any ou tool, ce qui garantit que Claude utilise exactement un outil

Exemple travaillé

Voici un script complet et exécutable pour tester et vérifier que les appels d'outils parallèles fonctionnent correctement :

# 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")

Ce script démontre :

Comment formater correctement les appels d'outils parallèles et les résultats
Comment vérifier que les appels parallèles sont en cours
La structure de message correcte qui encourage l'utilisation future d'outils parallèles
Les erreurs courantes à éviter (comme du texte avant les résultats des outils)

Exécutez ce script pour tester votre implémentation et vous assurer que Claude effectue des appels d'outils parallèles efficacement.

Maximiser l'utilisation parallèle des outils

Résolution des problèmes

Si Claude ne fait pas d'appels d'outils parallèles quand prévu, vérifiez ces problèmes courants :

1. Formatage incorrect des résultats des outils

Le problème le plus courant est de formater incorrectement les résultats des outils dans l'historique de la conversation. Cela « enseigne » à Claude d'éviter les appels parallèles.

Spécifiquement pour l'utilisation parallèle des outils :

❌ Incorrect : Envoyer des messages utilisateur séparés pour chaque résultat d'outil
✅ Correct : Tous les résultats des outils doivent être dans un seul message utilisateur

// ❌ Cela réduit l'utilisation parallèle des outils
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Message séparé
]

// ✅ Cela maintient l'utilisation parallèle des outils
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Message unique
]

Consultez Gérer les appels d'outils pour d'autres règles de formatage.

2. Prompting faible

Le prompting par défaut peut ne pas être suffisant. Utilisez l'invite système plus forte de la section Maximiser l'utilisation parallèle des outils ci-dessus.

3. Mesurer l'utilisation parallèle des outils

Pour vérifier que les appels d'outils parallèles fonctionnent :

# 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

Étapes suivantes

Pour le flux d'appel unique et les règles de formatage tool_result, consultez Gérer les appels d'outils.
Pour l'abstraction SDK qui gère l'exécution parallèle automatiquement, consultez Tool Runner.
Pour le flux de travail complet d'utilisation des outils, consultez Définir les outils.

Was this page helpful?

Exemple travaillé

Maximiser l'utilisation parallèle des outils

Invites système pour l'utilisation parallèle des outils

Prompting des messages utilisateur

Résolution des problèmes

Étapes suivantes

Exemple travaillé

Maximiser l'utilisation parallèle des outils

Invites système pour l'utilisation parallèle des outils

Prompting des messages utilisateur

Résolution des problèmes

Étapes suivantes