Claude API Tool Use 실전 가이드

문제 상황

필요한 도구

해결 과정

# ============================================
# Python SDK 설치 및 초기화
# ============================================
pip install anthropic

# 환경변수로 API 키 설정 (코드에 하드코딩 금지!)
# Linux/Mac:
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# Windows PowerShell:
$env:ANTHROPIC_API_KEY="sk-ant-api03-..."

# Python 클라이언트 초기화 및 테스트
import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY 환경변수 자동 사용

# 연결 테스트
message = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=100,
    messages=[{"role": "user", "content": "Hello!"}]
)
print(message.content[0].text)  # 응답이 나오면 설정 완료

# ============================================
# TypeScript SDK 설치 및 초기화
# ============================================
# npm install @anthropic-ai/sdk
#
# import Anthropic from "@anthropic-ai/sdk";
# const client = new Anthropic();  // ANTHROPIC_API_KEY 환경변수 자동 사용

import anthropic

client = anthropic.Anthropic()

# ============================================
# 도구 정의 - JSON Schema로 파라미터 명세
# ============================================
tools = [
    {
        "name": "get_weather",
        "description": (
            "지정된 도시의 현재 날씨 정보(기온, 습도, 날씨 상태)를 조회합니다. "
            "도시 이름은 한국어('서울') 또는 영어('Seoul') 모두 가능합니다. "
            "사용자가 날씨, 기온, 온도, 기후 등을 질문할 때 이 도구를 사용합니다."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "날씨를 조회할 도시 이름 (예: '서울', 'Tokyo', '뉴욕')"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "온도 단위. 기본값은 celsius"
                }
            },
            "required": ["city"]
        }
    },
    {
        "name": "manage_schedule",
        "description": (
            "사용자의 일정을 조회(list), 추가(add), 삭제(delete)합니다. "
            "특정 날짜의 일정 확인, 새 일정 등록, 기존 일정 삭제가 가능합니다. "
            "사용자가 일정, 약속, 스케줄, 미팅 등을 언급할 때 이 도구를 사용합니다."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "action": {
                    "type": "string",
                    "enum": ["list", "add", "delete"],
                    "description": "수행할 작업: list(조회), add(추가), delete(삭제)"
                },
                "date": {
                    "type": "string",
                    "description": "대상 날짜 (YYYY-MM-DD 형식). 예: '2025-05-15'"
                },
                "title": {
                    "type": "string",
                    "description": "일정 제목 (action이 'add'일 때 필수)"
                },
                "time": {
                    "type": "string",
                    "description": "일정 시간 (HH:MM 형식, action이 'add'일 때 선택)"
                },
                "schedule_id": {
                    "type": "string",
                    "description": "삭제할 일정 ID (action이 'delete'일 때 필수)"
                }
            },
            "required": ["action", "date"]
        }
    }
]

# ============================================
# 도구를 포함한 API 호출 테스트
# ============================================
response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user", "content": "서울 날씨 어때?"}
    ]
)

# 응답 분석
print(f"stop_reason: {response.stop_reason}")
# -> "tool_use" (Claude가 도구 호출을 요청)

for block in response.content:
    if hasattr(block, "text"):
        print(f"텍스트: {block.text}")
    if block.type == "tool_use":
        print(f"도구 호출: {block.name}")
        print(f"파라미터: {block.input}")
        print(f"tool_use_id: {block.id}")
# -> 도구 호출: get_weather
# -> 파라미터: {"city": "서울"}
# -> tool_use_id: "toolu_01Abc..."

import anthropic
import json

client = anthropic.Anthropic()

# ============================================
# 1. 실제 도구 실행 함수 정의
# ============================================
def get_weather(city: str, unit: str = "celsius") -> dict:
    """실제로는 OpenWeatherMap 등 기상 API를 호출합니다."""
    # 예시 데이터 (실제 구현 시 API 호출로 교체)
    weather_data = {
        "서울": {"temp": 22, "humidity": 55, "condition": "맑음", "wind": "3m/s"},
        "도쿄": {"temp": 26, "humidity": 70, "condition": "흐림", "wind": "5m/s"},
        "뉴욕": {"temp": 18, "humidity": 45, "condition": "구름 조금", "wind": "8m/s"},
    }
    data = weather_data.get(city, {"temp": 20, "humidity": 50, "condition": "정보 없음", "wind": "N/A"})
    if unit == "fahrenheit":
        data["temp"] = round(data["temp"] * 9 / 5 + 32, 1)
    data["city"] = city
    data["unit"] = unit
    return data

def manage_schedule(action: str, date: str, **kwargs) -> dict:
    """일정 관리 (실제로는 DB나 Google Calendar API 연동)"""
    if action == "list":
        return {
            "date": date,
            "schedules": [
                {"id": "1", "title": "팀 미팅", "time": "10:00"},
                {"id": "2", "title": "점심 약속", "time": "12:30"},
                {"id": "3", "title": "코드 리뷰", "time": "15:00"},
            ]
        }
    elif action == "add":
        return {
            "status": "success",
            "message": f"{date} {kwargs.get('time', '')} '{kwargs.get('title', '')}' 일정이 추가되었습니다.",
            "id": "4"
        }
    elif action == "delete":
        return {
            "status": "success",
            "message": f"일정 ID {kwargs.get('schedule_id', '')}이(가) 삭제되었습니다."
        }
    return {"status": "error", "message": "알 수 없는 작업입니다."}

# ============================================
# 2. 도구 이름 -> 함수 매핑 (디스패처)
# ============================================
TOOL_FUNCTIONS = {
    "get_weather": get_weather,
    "manage_schedule": manage_schedule,
}

# ============================================
# 3. 에이전트 루프 (핵심 코드)
# ============================================
def run_agent(user_message: str, tools: list, max_turns: int = 10) -> str:
    """Claude가 최종 답변을 줄 때까지 도구 호출을 반복하는 에이전트 루프"""
    messages = [{"role": "user", "content": user_message}]

    for turn in range(max_turns):
        # Claude API 호출
        response = client.messages.create(
            model="claude-sonnet-4-5-20250514",
            max_tokens=4096,
            system="당신은 날씨 확인과 일정 관리를 도와주는 비서입니다. 한국어로 답변합니다.",
            tools=tools,
            messages=messages,
        )

        # [중요] Claude의 응답을 메시지 히스토리에 추가
        messages.append({"role": "assistant", "content": response.content})

        # stop_reason이 "end_turn"이면 최종 답변 완료
        if response.stop_reason == "end_turn":
            return "\n".join(
                block.text for block in response.content
                if hasattr(block, "text")
            )

        # stop_reason이 "tool_use"이면 도구 실행
        if response.stop_reason == "tool_use":
            tool_results = []

            for block in response.content:
                if block.type != "tool_use":
                    continue

                func = TOOL_FUNCTIONS.get(block.name)

                if func is None:
                    # 알 수 없는 도구: is_error=True로 Claude에게 알림
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,  # 반드시 매칭!
                        "content": json.dumps({
                            "error": f"도구 '{block.name}'을(를) 찾을 수 없습니다."
                        }),
                        "is_error": True,
                    })
                    continue

                try:
                    # 도구 실행
                    result = func(**block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": json.dumps(result, ensure_ascii=False),
                    })
                except Exception as e:
                    # 실행 에러: is_error=True + 에러 메시지
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": json.dumps({
                            "error": f"{type(e).__name__}: {str(e)}"
                        }),
                        "is_error": True,
                    })

            # [중요] tool_result를 user 메시지로 추가
            messages.append({"role": "user", "content": tool_results})

    return "최대 대화 턴 수를 초과했습니다. 질문을 더 구체적으로 해주세요."

# ============================================
# 4. 실행 테스트
# ============================================
# 단일 도구 호출
result = run_agent("서울 날씨 알려줘", tools)
print(result)
# -> "서울의 현재 기온은 22도이며 맑은 날씨입니다. 습도는 55%이고..."

# 여러 도구 호출 (Claude가 자동으로 판단)
result = run_agent("서울 날씨 알려주고, 오늘 일정도 확인해줘", tools)
print(result)
# -> Claude가 get_weather + manage_schedule 두 도구를 호출

import anthropic
import json
import asyncio
from concurrent.futures import ThreadPoolExecutor

client = anthropic.Anthropic()

# ============================================
# 병렬 도구 실행 (asyncio + ThreadPoolExecutor)
# ============================================
async def execute_tools_parallel(
    tool_blocks: list,
    tool_functions: dict,
    timeout_seconds: float = 30.0,
) -> list:
    """여러 도구를 병렬로 실행하고 결과를 수집합니다."""
    loop = asyncio.get_event_loop()
    executor = ThreadPoolExecutor(max_workers=5)

    async def run_single_tool(block):
        func = tool_functions.get(block.name)

        # 1. 알 수 없는 도구
        if not func:
            return {
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps({
                    "error": f"도구 '{block.name}'을(를) 찾을 수 없습니다."
                }),
                "is_error": True,
            }

        try:
            # 2. 타임아웃 설정 + 스레드풀에서 실행
            result = await asyncio.wait_for(
                loop.run_in_executor(
                    executor, lambda: func(**block.input)
                ),
                timeout=timeout_seconds,
            )
            return {
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps(result, ensure_ascii=False),
            }

        # 3. 타임아웃
        except asyncio.TimeoutError:
            return {
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps({
                    "error": f"도구 실행 시간이 {timeout_seconds}초를 초과했습니다."
                }),
                "is_error": True,
            }

        # 4. 기타 에러 (민감 정보 필터링)
        except Exception as e:
            return {
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps({
                    "error": f"도구 실행 중 오류가 발생했습니다: {type(e).__name__}"
                    # str(e)에 민감 정보가 포함될 수 있으므로 타입만 전달
                }),
                "is_error": True,
            }

    # 모든 도구를 병렬로 실행
    tasks = [
        run_single_tool(b)
        for b in tool_blocks
        if b.type == "tool_use"
    ]
    results = await asyncio.gather(*tasks)
    return list(results)

# ============================================
# API 에러 처리를 포함한 프로덕션 에이전트
# ============================================
import time

def run_agent_production(
    user_message: str,
    tools: list,
    max_turns: int = 10,
    max_api_retries: int = 3,
) -> str:
    """프로덕션 수준의 에이전트 (에러 처리 + 병렬 실행 + 재시도)"""
    messages = [{"role": "user", "content": user_message}]

    for turn in range(max_turns):
        # API 호출 (재시도 로직 포함)
        response = None
        for retry in range(max_api_retries):
            try:
                response = client.messages.create(
                    model="claude-sonnet-4-5-20250514",
                    max_tokens=4096,
                    system="날씨 확인과 일정 관리를 도와주는 비서입니다. 한국어로 답변합니다.",
                    tools=tools,
                    messages=messages,
                )
                break  # 성공 시 루프 탈출

            except anthropic.RateLimitError:
                # 429: 대기 후 재시도
                wait_time = 2 ** retry  # 1초, 2초, 4초 (exponential backoff)
                print(f"Rate limit 초과. {wait_time}초 대기 후 재시도...")
                time.sleep(wait_time)

            except anthropic.APIStatusError as e:
                if e.status_code >= 500:
                    # 5xx: 서버 에러, 재시도
                    print(f"서버 에러({e.status_code}). 재시도 {retry + 1}/{max_api_retries}")
                    time.sleep(1)
                else:
                    # 4xx (401, 403 등): 재시도 불가
                    return f"API 에러: {e.status_code}. API 키와 설정을 확인하세요."

            except anthropic.APIConnectionError:
                print(f"네트워크 연결 실패. 재시도 {retry + 1}/{max_api_retries}")
                time.sleep(2)

        if response is None:
            return "API 호출에 실패했습니다. 네트워크 연결과 API 키를 확인하세요."

        # 응답 처리
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason == "end_turn":
            return "\n".join(
                block.text for block in response.content
                if hasattr(block, "text")
            )

        if response.stop_reason == "tool_use":
            tool_blocks = [b for b in response.content if b.type == "tool_use"]
            # 병렬 실행
            tool_results = asyncio.run(
                execute_tools_parallel(tool_blocks, TOOL_FUNCTIONS)
            )
            messages.append({"role": "user", "content": tool_results})

    return "최대 대화 턴 수를 초과했습니다."

# ============================================
# 실행 테스트: 병렬 호출이 발생하는 케이스
# ============================================
result = run_agent_production(
    "서울과 도쿄 날씨를 비교해주고, 내일 일정도 확인해줘",
    tools,
)
print(result)
# Claude가 get_weather("서울"), get_weather("도쿄"),
# manage_schedule("list", "2025-05-16") 세 개를 병렬로 호출

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// ============================================
// 1. 도구 정의 (TypeScript 타입 적용)
// ============================================
const tools: Anthropic.Tool[] = [
  {
    name: "get_weather",
    description:
      "지정된 도시의 현재 날씨(기온, 습도, 상태)를 조회합니다. " +
      "도시 이름은 한국어 또는 영어 모두 가능합니다.",
    input_schema: {
      type: "object" as const,
      properties: {
        city: {
          type: "string",
          description: "도시 이름 (예: '서울', 'Tokyo')",
        },
        unit: {
          type: "string",
          enum: ["celsius", "fahrenheit"],
          description: "온도 단위 (기본값: celsius)",
        },
      },
      required: ["city"],
    },
  },
  {
    name: "manage_schedule",
    description:
      "사용자의 일정을 조회(list), 추가(add), 삭제(delete)합니다.",
    input_schema: {
      type: "object" as const,
      properties: {
        action: {
          type: "string",
          enum: ["list", "add", "delete"],
          description: "수행할 작업",
        },
        date: {
          type: "string",
          description: "날짜 (YYYY-MM-DD)",
        },
        title: {
          type: "string",
          description: "일정 제목 (add 시)",
        },
        time: {
          type: "string",
          description: "시간 (HH:MM, add 시)",
        },
        schedule_id: {
          type: "string",
          description: "일정 ID (delete 시)",
        },
      },
      required: ["action", "date"],
    },
  },
];

// ============================================
// 2. 도구 실행 함수 (타입 안전)
// ============================================
type ToolInput = Record<string, string>;

function executeTool(name: string, input: ToolInput): string {
  switch (name) {
    case "get_weather":
      // 실제 구현에서는 기상 API 호출
      return JSON.stringify({
        city: input.city,
        temp: 23,
        humidity: 60,
        condition: "맑음",
        wind: "4m/s",
        unit: input.unit || "celsius",
      });

    case "manage_schedule":
      if (input.action === "list") {
        return JSON.stringify({
          date: input.date,
          schedules: [
            { id: "1", title: "팀 스탠드업", time: "09:30" },
            { id: "2", title: "코드 리뷰", time: "14:00" },
            { id: "3", title: "1:1 미팅", time: "16:00" },
          ],
        });
      }
      if (input.action === "add") {
        return JSON.stringify({
          status: "success",
          message: `${input.date} ${input.time || ""} '${input.title}' 추가 완료`,
          id: "4",
        });
      }
      if (input.action === "delete") {
        return JSON.stringify({
          status: "success",
          message: `일정 ${input.schedule_id} 삭제 완료`,
        });
      }
      return JSON.stringify({ error: "알 수 없는 작업" });

    default:
      return JSON.stringify({ error: `알 수 없는 도구: ${name}` });
  }
}

// ============================================
// 3. 에이전트 메인 루프
// ============================================
async function runAgent(userMessage: string): Promise<string> {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  const MAX_TURNS = 10;

  for (let turn = 0; turn < MAX_TURNS; turn++) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-5-20250514",
      max_tokens: 4096,
      system:
        "당신은 날씨 확인과 일정 관리를 도와주는 비서입니다. " +
        "항상 한국어로 자연스럽게 답변하세요. " +
        "도구 결과를 그대로 나열하지 말고 자연스러운 문장으로 요약해 주세요.",
      tools,
      messages,
    });

    // assistant 응답을 히스토리에 추가
    messages.push({ role: "assistant", content: response.content });

    // 최종 답변이면 텍스트 추출 후 반환
    if (response.stop_reason === "end_turn") {
      return response.content
        .filter((b): b is Anthropic.TextBlock => b.type === "text")
        .map((b) => b.text)
        .join("\n");
    }

    // 도구 호출 처리
    if (response.stop_reason === "tool_use") {
      const toolResults: Anthropic.ToolResultBlockParam[] =
        response.content
          .filter(
            (b): b is Anthropic.ToolUseBlock => b.type === "tool_use"
          )
          .map((block) => {
            try {
              const result = executeTool(
                block.name,
                block.input as ToolInput
              );
              return {
                type: "tool_result" as const,
                tool_use_id: block.id,
                content: result,
              };
            } catch (e) {
              return {
                type: "tool_result" as const,
                tool_use_id: block.id,
                content: JSON.stringify({
                  error:
                    e instanceof Error
                      ? e.message
                      : "알 수 없는 실행 오류",
                }),
                is_error: true,
              };
            }
          });

      messages.push({ role: "user", content: toolResults });
    }
  }

  return "최대 대화 턴을 초과했습니다.";
}

// ============================================
// 4. 실행 (다단계 도구 호출 시나리오)
// ============================================
(async () => {
  const answer = await runAgent(
    "서울 날씨 어떤지 알려주고, 오늘 일정도 확인해줘. " +
    "날씨가 좋으면 오후 3시에 산책 일정도 추가해줘."
  );
  console.log(answer);
  // Claude가 3단계로 처리:
  // 1. get_weather("서울") + manage_schedule("list", "오늘")
  // 2. 날씨 확인 -> 좋으면 manage_schedule("add", "오늘", "산책", "15:00")
  // 3. 최종 요약 답변
})();

import anthropic
import json

client = anthropic.Anthropic()

# ============================================
# [패턴 1] 도구 결과 크기 관리
# ============================================
def search_database(query: str, limit: int = 10) -> dict:
    """DB 검색 결과가 크면 요약하여 반환"""
    # 실제 DB 쿼리 실행
    all_results = [{"id": i, "name": f"항목 {i}"} for i in range(100)]

    return {
        "total_count": len(all_results),
        "returned_count": min(limit, len(all_results)),
        "results": all_results[:limit],
        "message": f"총 {len(all_results)}개 중 상위 {limit}개를 반환합니다."
    }

# ============================================
# [패턴 2] 도구 입력 검증 (보안)
# ============================================
import re

def safe_file_read(filepath: str) -> dict:
    """파일 경로 검증 후 읽기"""
    # 허용 경로 목록
    ALLOWED_DIRS = ["/data/reports/", "/data/exports/"]

    # 경로 탐색 공격 방지
    normalized = filepath.replace("\\", "/")
    if ".." in normalized:
        return {"error": "잘못된 파일 경로입니다."}

    if not any(normalized.startswith(d) for d in ALLOWED_DIRS):
        return {"error": "접근이 허용되지 않은 경로입니다."}

    # 실제 파일 읽기 (생략)
    return {"content": "파일 내용...", "size": "1.2KB"}

# ============================================
# [패턴 3] tool_choice로 도구 선택 제어
# ============================================

# 기본: Claude가 도구 사용 여부를 자동 판단
response_auto = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto"},  # 기본값
    messages=[{"role": "user", "content": "안녕하세요!"}],
)
# -> Claude가 도구 없이 직접 답변 (날씨/일정 관련 아니므로)

# 특정 도구 강제 호출
response_forced = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "좋은 아침이에요"}],
)
# -> 반드시 get_weather를 호출 (질문과 무관하게)

# 반드시 하나 이상의 도구 사용
response_any = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "오늘 뭐 하면 좋을까?"}],
)
# -> 날씨 또는 일정 중 하나를 반드시 호출

# ============================================
# [패턴 4] 도구 결과 캐싱 (비용 절감)
# ============================================
from functools import lru_cache
from datetime import datetime

@lru_cache(maxsize=100)
def get_weather_cached(city: str, date: str) -> str:
    """같은 도시+날짜 조합은 캐싱하여 중복 API 호출 방지"""
    # 실제 기상 API 호출 (비용 발생)
    result = {"city": city, "temp": 22, "condition": "맑음"}
    return json.dumps(result, ensure_ascii=False)

# 사용: 같은 날 같은 도시를 여러 번 조회해도 API는 1번만 호출
today = datetime.now().strftime("%Y-%m-%d")
get_weather_cached("서울", today)  # API 호출
get_weather_cached("서울", today)  # 캐시에서 반환 (API 호출 없음)

# ============================================
# [패턴 5] 로깅 및 모니터링
# ============================================
import logging

logger = logging.getLogger("agent")

def run_agent_with_logging(user_message: str, tools: list) -> str:
    """모든 도구 호출을 로깅하는 에이전트"""
    messages = [{"role": "user", "content": user_message}]
    total_input_tokens = 0
    total_output_tokens = 0

    for turn in range(10):
        response = client.messages.create(
            model="claude-sonnet-4-5-20250514",
            max_tokens=4096,
            tools=tools,
            messages=messages,
        )

        # 토큰 사용량 추적
        total_input_tokens += response.usage.input_tokens
        total_output_tokens += response.usage.output_tokens

        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason == "end_turn":
            logger.info(
                f"완료 | 턴: {turn + 1} | "
                f"입력 토큰: {total_input_tokens} | "
                f"출력 토큰: {total_output_tokens} | "
                f"예상 비용: $" + f"{(total_input_tokens * 3 + total_output_tokens * 15) / 1_000_000:.4f}"
            )
            return "\n".join(
                b.text for b in response.content if hasattr(b, "text")
            )

        if response.stop_reason == "tool_use":
            for b in response.content:
                if b.type == "tool_use":
                    logger.info(f"도구 호출: {b.name}({json.dumps(b.input)})")

            # 도구 실행 및 결과 반환 (생략)
            tool_results = []
            for b in response.content:
                if b.type == "tool_use":
                    func = TOOL_FUNCTIONS.get(b.name)
                    if func:
                        result = func(**b.input)
                        tool_results.append({
                            "type": "tool_result",
                            "tool_use_id": b.id,
                            "content": json.dumps(result, ensure_ascii=False),
                        })

            messages.append({"role": "user", "content": tool_results})

    return "최대 턴 초과"

핵심 코드

Claude Tool Use 에이전트 루프의 핵심 패턴: (1) 도구를 JSON Schema로 정의, (2) API 호출 시 tools 파라미터에 포함, (3) stop_reason이 "tool_use"이면 함수 실행, (4) tool_result를 tool_use_id와 정확히 매칭하여 반환, (5) "end_turn"이 될 때까지 반복.

import anthropic, json

client = anthropic.Anthropic()

# 1. 도구 정의 (JSON Schema)
tools = [{
    "name": "get_weather",
    "description": "도시의 현재 날씨를 조회합니다",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "도시 이름"}
        },
        "required": ["city"]
    }
}]

# 2. 에이전트 루프 (핵심 패턴)
messages = [{"role": "user", "content": "서울 날씨 알려줘"}]

while True:
    response = client.messages.create(
        model="claude-sonnet-4-5-20250514",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )

    # [필수] assistant 응답을 히스토리에 추가
    messages.append({"role": "assistant", "content": response.content})

    # 최종 답변이면 종료
    if response.stop_reason == "end_turn":
        print([b.text for b in response.content if hasattr(b, "text")])
        break

    # tool_use -> 함수 실행 -> tool_result 반환
    if response.stop_reason == "tool_use":
        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = execute_tool(block.name, block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,  # 반드시 매칭!
                    "content": json.dumps(output, ensure_ascii=False),
                })
        messages.append({"role": "user", "content": results})

자주 하는 실수

관련 liminfo 서비스