5. Python으로 병렬 도구 호출(Parallel Tool Use) 구현하기

저번 4편 글에서는 파이썬(Python)으로 Claude API와 주고받는 기본적인 Tool Use(도구 사용) 루프를 구현해보았다.

 

이번에는 한 단계 더 나아가, 사용자가 단일 질문 안에서 복수의 정보나 처리를 요구할 때 Claude가 한 턴에 여러 도구를 동시에 호출하는 병렬 도구 호출(Parallel Tool Use) 기능을 추가하고 테스트해보았다.

 

1. 병렬 도구 호출(Parallel Tool Use)이란?

실제 게임 테스트 에이전트를 운용하다 보면 "현재 캐릭터 위치를 확인하고, 3미터 앞 장애물로 이동해라"와 같이 한 번에 여러 액션이나 조회가 필요한 상황이 빈번하게 발생한다.

Claude API는 한 턴의 stop_reason="tool_use" 응답 내에 여러 개의 tool_use 블록을 배열로 동시에 전달할 수 있다.

따라서 우리의 루프는 이를 순회하며 각 도구를 실행하고, 결과 tool_result 블록들을 하나의 user 메시지에 모아 다시 전달해주면 된다.

 

2. 인자가 있는 신규 도구 추가 (add_numbers)

기존의 인자가 없는 get_time 외에, 인자(Parameter)를 요구하는 계산 도구 add_numbers(a, b)를 추가하여 agent/loop.py를 업데이트했다.

 

# agent/loop.py

# [1] 도구 스펙 (input_schema 에 인자 정의 추가)
TOOLS = [
    {
        "name": "get_time",
        "description": "현재 시각을 ISO 형식 문자열로 반환한다. 사용자가 시간이나 날짜를 물으면 사용.",
        "input_schema": {
            "type": "object",
            "properties": {},
            "required": [],
        },
    },
    {
        "name": "add_numbers",
        "description": "두 숫자를 더한 결과를 문자열로 반환한다. 사용자가 두 수의 합을 물으면 사용.",
        "input_schema": {
            "type": "object",
            "properties": {
                "a": {"type": "number", "description": "첫 번째 숫자"},
                "b": {"type": "number", "description": "두 번째 숫자"}
            },
            "required": ["a", "b"],
        },
    }
]

# [2] 실제 도구 구현 및 레지스트리 등록
def get_time(**kwargs) -> str:
    return datetime.now().isoformat(timespec="seconds")

def add_numbers(a, b, **kwargs) -> str:
    return str(a + b)

TOOL_FUNCS = {
    "get_time": get_time,
    "add_numbers": add_numbers
}

# [3] 병렬 도구 실행 루프 처리
for block in data["content"]:
    if block.get("type") != "tool_use":
        continue

    name = block["name"]
    tool_input = block.get("input", {})
    output, is_error = execute_tool(name, tool_input)

    results.append({
        "type": "tool_result",
        "tool_use_id": block["id"],
        "content": output,
    })

 

3. 실행 및 결과 확인

터미널에서 python agent/loop.py "지금 몇 시고, 3 더하기 5는?" 명령을 입력하여 복수 도구가 한 턴에 정상적으로 병렬 호출되는지 테스트했다.

 

 

실행 결과를 분석해보면:

• [턴 1] 단일 턴에서 2개 도구 동시 실행: Claude가 질문을 분석하고 get_time({})과 add_numbers({'a': 3, 'b': 5}) 두 도구를 하나의 턴에서 한꺼번에 호출했다.
• 결과 일괄 반환: 파이썬 루프에서 두 결과를 2026-07-25T17:38:56과 8로 처리한 후 Claude에게 전달했다.
• [턴 2] 최종 응답 완성: Claude가 두 실행 결과를 종합하여 현재 시각과 계산 결과(8)를 자연스럽게 한 번에 답변하고 stop_reason=end_turn으로 마무리했다.

 

마무리하며

단일 도구 실행뿐만 아니라 복수 도구의 병렬 호출(Parallel Tool Calling)까지 안정적으로 처리할 수 있는 에이전트 루프 구조가 갖춰졌다.

다음 편에서는 이러한 도구 사용 구조를 바탕으로 언리얼 엔진과 실제 통신할 소켓/HTTP 커넥터를 연동하는 Phase 2 작업으로 진입할 예정이다.