병렬 도구 사용

이 페이지는 병렬 도구 호출을 다룹니다: Claude가 한 번에 여러 도구를 호출할 때, 병렬성이 계속 작동하도록 메시지 히스토리를 포맷하는 방법, 그리고 이를 비활성화하는 방법입니다. 단일 호출 흐름의 경우 도구 호출 처리를 참조하세요.

기본적으로 Claude는 사용자 쿼리에 답하기 위해 여러 도구를 사용할 수 있습니다. 다음을 통해 이 동작을 비활성화할 수 있습니다:

tool_choice 유형이 auto일 때 disable_parallel_tool_use=true를 설정하면 Claude가 최대 하나의 도구를 사용하도록 보장합니다
tool_choice 유형이 any 또는 tool일 때 disable_parallel_tool_use=true를 설정하면 Claude가 정확히 하나의 도구를 사용하도록 보장합니다

작동 예제

Tool Runner로 더 간단하게: 아래 예제는 수동 병렬 도구 처리를 보여줍니다. 대부분의 사용 사례에서 Tool Runner는 훨씬 적은 코드로 병렬 도구 실행을 자동으로 처리합니다.

병렬 도구 호출이 올바르게 작동하는지 테스트하고 확인하는 완전하고 실행 가능한 스크립트입니다:

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

이 스크립트는 다음을 보여줍니다:

병렬 도구 호출 및 결과를 올바르게 포맷하는 방법
병렬 호출이 이루어지고 있는지 확인하는 방법
향후 병렬 도구 사용을 권장하는 올바른 메시지 구조
피해야 할 일반적인 실수 (도구 결과 전의 텍스트 등)

이 스크립트를 실행하여 구현을 테스트하고 Claude가 병렬 도구 호출을 효과적으로 수행하고 있는지 확인하세요.

병렬 도구 사용 최대화

Claude 4 모델은 기본적으로 우수한 병렬 도구 사용 기능을 가지고 있지만, 대상 프롬프팅을 통해 모든 모델에서 병렬 도구 실행의 가능성을 높일 수 있습니다:

문제 해결

Claude가 예상대로 병렬 도구 호출을 하지 않는 경우 다음 일반적인 문제를 확인하세요:

1. 잘못된 도구 결과 포맷

가장 일반적인 문제는 대화 히스토리에서 도구 결과를 잘못 포맷하는 것입니다. 이는 Claude에게 병렬 호출을 피하도록 "가르칩니다".

특히 병렬 도구 사용의 경우:

❌ 잘못됨: 각 도구 결과에 대해 별도의 사용자 메시지 전송
✅ 올바름: 모든 도구 결과는 단일 사용자 메시지에 있어야 함

// ❌ 이것은 병렬 도구 사용을 줄입니다
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // 별도 메시지
]

// ✅ 이것은 병렬 도구 사용을 유지합니다
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // 단일 메시지
]

다른 포맷 규칙은 도구 호출 처리를 참조하세요.

2. 약한 프롬프팅

기본 프롬프팅은 충분하지 않을 수 있습니다. 위의 병렬 도구 사용 최대화 섹션에서 더 강력한 시스템 프롬프트를 사용하세요.

3. 병렬 도구 사용 측정

병렬 도구 호출이 작동하는지 확인하려면:

# 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

다음 단계

단일 도구 호출 흐름 및 tool_result 포맷 규칙의 경우 도구 호출 처리를 참조하세요.
병렬 실행을 자동으로 처리하는 SDK 추상화의 경우 Tool Runner를 참조하세요.
전체 도구 사용 워크플로우의 경우 도구 정의를 참조하세요.

작동 예제

병렬 도구 사용 최대화

병렬 도구 사용을 위한 시스템 프롬프트

사용자 메시지 프롬프팅

문제 해결

다음 단계