Messages도구
도구 사용 문제 해결
증상별 해결 방법 진단 표를 통해 가장 흔한 도구 사용 오류를 해결합니다.
증상이나 오류를 찾은 다음, 해당 항목에 나열된 해결 방법을 적용하세요.
Claude가 잘못된 도구를 호출함
| 증상 | 가능한 원인 | 해결 방법 |
|---|---|---|
| 도구 B를 원했는데 Claude가 도구 A를 호출함 | 설명의 모호성 | 설명을 더 명확하게 다듬으세요. 도구가 무엇을 하는지(WHAT)뿐만 아니라 언제 사용하는지(WHEN)로 도구를 구분하세요. 도구 정의를 참조하세요. |
| Claude가 도구를 전혀 호출하지 않음 | 도구 이름 충돌 또는 지나치게 일반적인 스키마 | 도구 목록 전체에서 중복된 이름이 있는지 확인하세요. 의도한 사용 방식을 구체화하려면 input_examples를 추가하세요. |
| Claude가 잘못된 매개변수 타입으로 호출함 | 모호한 스키마 | strict: true를 추가하거나(스키마가 지원되는 하위 집합에 속하는 경우) input_examples를 추가하세요. |
Claude가 도구 매개변수를 지어냄
| 증상 | 가능한 원인 | 해결 방법 |
|---|---|---|
| 스키마에 존재하지 않는 매개변수 | strict 모드 없이 모델이 과도하게 생성함 | 스키마가 지원되는 하위 집합에 속하는 경우 strict: true를 추가하세요. |
| enum 범위를 벗어난 매개변수 값 | strict 모드 누락 또는 너무 큰 enum | enum을 줄이거나 유효한 선택지를 보여주는 input_examples를 추가하세요. |
병렬 도구 호출이 작동하지 않음
| 증상 | 가능한 원인 | 해결 방법 |
|---|---|---|
| 병렬이 더 나은 상황에서 Claude가 도구를 순차적으로 호출함 | 메시지 기록 형식 | 여러 tool_result 블록을 턴마다 하나씩이 아니라 하나의 user 메시지에 담아 보내세요. 병렬 도구 사용을 참조하세요. |
disable_parallel_tool_use가 무시되는 것처럼 보임 | 대화에서 너무 늦게 설정됨 | tool_use를 반환하는 요청에 설정하세요. 이후 요청에 설정하면 이전 도구 호출에는 영향을 주지 않습니다. |
캐시가 계속 무효화됨
| 증상 | 가능한 원인 | 해결 방법 |
|---|---|---|
| 모든 요청이 캐시 미스임 | tool_choice, 사고 구성 또는 output_config.effort가 요청마다 달라짐 | tool_choice를 일정하게 유지하거나 cache_control 중단점을 변동 지점 앞에 배치하세요. 캐시된 대화가 유지되는 동안 사고 구성과 effort 수준을 일정하게 유지하세요. 프롬프트 캐싱과 함께 도구 사용 및 사고와 프롬프트 캐싱을 참조하세요. |
| 대화 중간에 도구를 추가하면 캐시가 깨짐 | 도구가 tools 배열 앞쪽에 추가됨 | 나중에 배열에 도구를 추가하는 대신, 첫 번째 요청부터 defer_loading: true로 도구를 선언하고 도구 검색이 도구를 인라인으로 로드하도록 하세요. |
요청 시점의 오류
오류 열에는 각 메시지의 일부가 표시되며, ...는 달라지는 텍스트를 나타냅니다.
| 오류 | 원인 | 해결 방법 |
|---|---|---|
tool_use ids were found without tool_result blocks immediately after | 일부 tool_use ID에 대한 tool_result가 누락되었거나, tool_result가 사용자 메시지의 첫 번째 콘텐츠 블록이 아님 | 어시스턴트 응답의 모든 tool_use 블록마다 하나의 tool_result를 반환하세요. tool_result 블록은 모든 텍스트보다 앞에 두세요. 도구 호출 처리 및 병렬 도구 사용을 참조하세요. |
was found without a corresponding ... block | 후속 요청이 대기 중인 서버 도구의 실행을 막음 | 서버 도구 호출에 결과 블록이 없음을 참조하세요. |
Unsupported regex feature in pattern field: ... | strict 도구의 pattern이 역참조, 단어 경계 또는 큰 {n,m} 범위와 같이 strict 모드에서 컴파일할 수 없는 정규식 기능을 사용함 | 패턴을 단순화하세요. JSON Schema 제한 사항을 참조하세요. |
Invalid regex in pattern field: ... | strict 도구의 pattern에 전방 탐색(lookahead), 후방 탐색(lookbehind) 또는 구문 오류가 있음 | 전방 탐색이나 후방 탐색을 제거하고 구문 오류를 수정하세요. JSON Schema 제한 사항을 참조하세요. |
All tools have defer_loading: true | 모델에 보이는 도구가 없음 | 최소 하나의 도구는 즉시 로드되어야 합니다. 도구 검색 도구 자체에는 절대 defer_loading: true를 설정하면 안 됩니다. |
서버 도구 호출에 결과 블록이 없음
서버 도구의 server_tool_use 또는 mcp_tool_use 블록에 결과 블록이 없으면 해당 도구는 아직 실행을 기다리고 있는 것입니다. was found without a corresponding ... block 오류는 후속 요청이 대기 중인 도구의 실행을 막고 있다는 의미입니다. 오류 메시지와 이전 stop_reason을 보면 그 이유를 알 수 있습니다. 일치하는 첫 번째 경우를 사용하세요:
- 메시지가
but no `<name>` tool was provided또는is not available after the last message로 끝나는 경우: 여기서<name>은web_search와 같은 도구의 이름입니다. 요청에서 더 이상 해당 도구를 정의하지 않습니다. 이전과 동일한tools배열을 보내고, MCP 도구의 경우 동일한mcp_servers도 보내세요. - 이전
stop_reason이tool_use였던 경우: 사용자 메시지에서tool_result블록 뒤에 콘텐츠가 있었습니다. 각 클라이언트tool_use블록마다 하나씩,tool_result블록만 보내세요. - 이전
stop_reason이pause_turn이었던 경우: 사용자 메시지를 추가했습니다. 요청이 일시 중지된 응답을assistant메시지로 하여 끝나도록 해당 메시지를 제거하세요.
전체 단계는 서버 도구가 아직 대기 중인 경우 및 pause_turn 중지 이유를 참조하세요.
오류: 사고 블록은 수정할 수 없음
도구 호출 후 대화를 이어갈 때 요청이 400 invalid_request_error로 실패하고 그 메시지에 `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified가 포함되어 있다면, 애플리케이션이 어시스턴트의 사고 블록을 다시 보내기 전에 변경하고 있는 것입니다. 어시스턴트 메시지 전체를 변경 없이 그대로 다시 보낸 다음 tool_result를 덧붙이세요.
전체 오류와 해결 단계는 사고 블록은 수정할 수 없음을 참조하세요.
Claude가 도구 결과를 프롬프트 인젝션으로 표시함
| 증상 | 가능한 원인 | 해결 방법 |
|---|---|---|
| Claude가 도구 결과에 따라 행동하기를 거부하거나, 도구 결과에서 나온 지시 사항을 사용자에게 확인해 달라고 요청함 | 사용자 자신의 지시 사항이 tool_result 콘텐츠 안에 담겨 전달되고 있음 | Claude는 도구 결과 안의 지시 사항을 잠재적으로 신뢰할 수 없는 제3자 콘텐츠로 취급하도록 학습되어 있습니다. 지시 사항을 도구 결과 밖으로 옮기세요. tool_result 블록 뒤의 user 턴에서 보내거나, 지원되는 모델에서는 대화 중간 시스템 메시지로 보내세요. 도구 결과에는 데이터만 담으세요. 탈옥 및 프롬프트 인젝션 완화를 참조하세요. |
모델 버전 간 JSON 이스케이프 차이
| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 최신 모델에서 도구 입력에 대한 문자열 비교가 실패함 | 유니코드 및 슬래시(/) 이스케이프 방식이 모델 버전마다 다름 | json.loads() 또는 JSON.parse()로 파싱하세요. 직렬화된 입력에 대해 원시 문자열 매칭을 절대 하지 마세요. |
다음 단계
이 페이지가 도움이 되었나요?