도구 사용 / 함수 호출

중급

도구 사용은 Claude가 여러분이 정의한 함수 — 검색, 계산기, 데이터베이스, 어떤 API든 — 를 호출하고 그 결과를 사용하게 합니다. 모든 에이전트의 토대입니다.

What you'll learn

도구 정의부터 최종 답변까지, 4단계 에이전트 루프가 어떻게 작동하는지
Python에서 이름, 설명, JSON-Schema 입력으로 도구를 정의하는 법
왜 도구 설명이 Claude가 언제 어떻게 호출할지를 형성하는 프롬프트로 작동하는지
입력을 검증하고, 오류를 결과로 반환하고, 서버 측 도구를 안전하게 사용하는 법

루프

도구 사용은 단일 호출이 아니라 대화입니다. 여러분은 Claude에게 도구 메뉴를 건네고; Claude가 하나를 골라 멈추고; 여러분이 그것을 실행해 보고하고; Claude가 그 결과를 답변에 엮습니다 — 필요한 만큼 반복합니다.

Guided walkthrough1 of 4

각각 이름, 설명, JSON-Schema 입력을 가진 도구 정의 목록을 포함합니다.

도구 정의하기 (Python)

도구 정의는 이름, 평이한 언어로 된 설명, 그리고 입력을 위한 JSON-Schema일 뿐입니다. tools에 전달한 뒤, Claude가 언제 행동하고자 하는지 알려면 stop_reason을 확인하세요.

get_weather tool + first call

tools = [{
  "name": "get_weather",
  "description": "Get current weather for a city.",
  "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"],
  },
}]

msg = client.messages.create(
  model="claude-sonnet-5", max_tokens=1024,
  tools=tools,
  messages=[{"role": "user", "content": "What's the weather in Rome?"}],
)
# If msg.stop_reason == "tool_use": run the tool, then send a tool_result back.

팁

도구를 어떻게 정의하고 처리하느냐의 작은 선택들이 신뢰성에 큰 차이를 만듭니다.

설명은 프롬프트입니다. 명확한 도구 description과 파라미터 문서는 Claude가 언제/어떻게 호출할지를 크게 개선합니다.
실행하기 전에 받은 입력을 검증하세요 — 절대 맹목적으로 신뢰하지 마세요.
오류를 결과로 반환하세요. 도구가 실패하면, Claude가 복구할 수 있도록 오류를 설명하는 tool_result를 보내세요.
서버 측 도구. Anthropic은 내장 도구(예: 웹 검색, 코드 실행, 컴퓨터 사용)도 제공합니다 — 현재 메뉴는 문서를 확인하세요.

:::warning 도구 = 행동 = 위험 실제 행동을 하는 도구는 보안 모델을 물려받습니다. 최소 권한을 적용하고 위험한 호출에는 사람을 루프에 두세요 — 에이전트 & 도구 보안을 참고하세요. :::

도구 사용 어휘

Enter 또는 스페이스 키를 눌러 카드를 뒤집습니다. 좌우 화살표 키로 카드를 이동할 수 있습니다.용어가 표시되었습니다.

1 / 4

스스로 점검하기

0/3

Claude가 tool_use 블록을 반환한 후, 누가 도구를 실행하나요?
여러분이 정의한 도구가 실행 중 실패합니다. 권장되는 조치는?
명확한 도구 설명이 왜 그렇게 중요한가요?

Key takeaways

도구 사용은 루프입니다: 도구 정의를 보내면 Claude가 tool_use 블록을 반환하고 멈추며, 여러분이 실행해 tool_result를 반환하면 Claude가 답할 때까지 계속합니다.
도구 정의는 이름, 설명, JSON-Schema 입력입니다 — tools에 전달하고 stop_reason == tool_use를 확인하세요.
설명은 프롬프트입니다; 실행 전에 입력을 검증하고; 실패는 tool_result 오류로 반환해 Claude가 복구하게 하세요.
Anthropic은 서버 측 도구도 제공하며, 실제 행동을 하는 도구는 최소 권한과 사람의 루프 개입이 필요합니다.

루프​

도구 정의하기 (Python)​

get_weather tool + first call

팁​

스스로 점검하기

다음​

루프

도구 정의하기 (Python)

팁

다음