---
title: 중지 이유와 폴백
url: https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons
description: 각 stop_reason 값의 의미와 애플리케이션에서 잘림, 도구 사용, 일시 중지된 턴, 거부를 처리하는 방법을 알아보세요.
---
모든 Messages API 응답에는 Claude가 생성을 중지한 이유를 알려주는 `stop_reason` 필드가 포함되어 있습니다. 이 필드를 확인하여 응답을 그대로 사용할지, 대화를 계속할지, 재시도할지, 아니면 다른 모델로 폴백할지 결정하세요.
전체 응답 스키마는 [Messages API 레퍼런스](https://platform.claude.com/docs/ko/api/messages/create)를 참조하세요.
## 빠른 참조
| 값 | 발생 시점 | 해야 할 일 |
| -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [`end_turn`](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#end-turn) | Claude가 응답을 자연스럽게 마쳤습니다. | 응답을 사용하세요. |
| [`max_tokens`](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#max-tokens) | 응답이 `max_tokens` 한도에 도달했습니다. | `max_tokens`를 늘리거나 [응답을 이어서 생성하세요](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#ensuring-complete-responses). |
| [`stop_sequence`](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#stop-sequence) | Claude가 `stop_sequences` 중 하나를 출력했습니다. | `stop_sequence`를 읽어 어느 것이 발동했는지 확인하세요. |
| [`tool_use`](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#tool-use) | Claude가 도구를 호출하고 있습니다. | 도구를 실행하고 결과를 반환하세요. 결과 블록이 아직 없는 서버 도구 호출은 이후 응답에서 완료됩니다. |
| [`pause_turn`](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#pause-turn) | 서버 도구 루프가 반복 한도에 도달했습니다. | 어시스턴트 콘텐츠를 다시 보내 계속하세요. |
| [`refusal`](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#refusal) | Claude가 응답을 거부했습니다. | `stop_details`를 읽고 [폴백 모델에서 재시도하세요](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback). |
| [`model_context_window_exceeded`](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#model-context-window-exceeded) | 응답이 모델의 컨텍스트 윈도우를 가득 채웠습니다. | 응답을 잘린 것으로 처리하세요. |
## stop\_reason 필드
`stop_reason` 필드는 모든 성공적인 Messages API 응답의 일부입니다. 요청 처리 실패를 나타내는 오류와 달리, `stop_reason`은 Claude가 응답 생성을 완료한 이유를 알려줍니다.
```json Example response
{
"id": "msg_01234",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Here's the answer to your question..."
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"stop_details": null,
"usage": {
"input_tokens": 100,
"output_tokens": 50
}
}
```
## 중지 이유 값
### end\_turn
가장 흔한 중지 이유입니다. Claude가 응답을 자연스럽게 마쳤음을 나타냅니다.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello!"}]
}' | jq 'if .stop_reason == "end_turn" then (.content[] | select(.type == "text") | .text) else . end'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello!"}' \
--format json | jq 'if .stop_reason == "end_turn" then (.content[] | select(.type == "text") | .text) else . end'
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
if response.stop_reason == "end_turn":
# 전체 응답을 처리합니다
for block in response.content:
if block.type == "text":
print(block.text)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
});
if (response.stop_reason === "end_turn") {
// 전체 응답을 처리합니다
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
}
```
```csharp C#
AnthropicClient client = new();
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello!" }]
});
if (response.StopReason == "end_turn")
{
// 전체 응답을 처리합니다
foreach (var block in response.Content)
{
if (block.TryPickText(out var textBlock))
{
Console.WriteLine(textBlock.Text);
}
}
}
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "end_turn" {
// 전체 응답을 처리합니다
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("Hello!")
.build()
);
if (response.stopReason().map(StopReason.END_TURN::equals).orElse(false)) {
// 전체 응답을 처리합니다
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello!']],
model: 'claude-opus-5-5',
);
if ($response->stopReason === 'end_turn') {
// 전체 응답을 처리합니다
foreach ($response->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
}
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
)
if response.stop_reason == :end_turn
# 전체 응답을 처리합니다
response.content.each do |block|
puts block.text if block.type == :text
end
end
```
때때로 Claude는 `stop_reason: "end_turn"`과 함께 빈 응답(콘텐츠 없이 정확히 2–3개의 토큰)을 반환합니다. 이는 일반적으로 Claude가 어시스턴트 턴이 완료되었다고 해석할 때, 특히 도구 결과 이후에 발생합니다.
**일반적인 원인:**
* 도구 결과 바로 뒤에 텍스트 블록을 추가하는 경우 (Claude는 사용자가 도구 결과 뒤에 항상 텍스트를 삽입한다고 기대하도록 학습하므로, 그 패턴을 따르기 위해 턴을 종료합니다)
* Claude의 완료된 응답을 아무것도 추가하지 않고 다시 보내는 경우 (Claude는 이미 완료되었다고 판단했으므로 계속 완료 상태로 남습니다)
**빈 응답을 방지하는 방법:**
```python Python
# 잘못된 예: tool_result 바로 뒤에 텍스트 추가
messages = [
{"role": "user", "content": "Calculate the sum of 1234 and 5678"},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_123",
"name": "calculator",
"input": {"operation": "add", "a": 1234, "b": 5678},
}
],
},
{
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": "toolu_123", "content": "6912"},
{
"type": "text",
"text": "Here's the result", # Don't add text after tool_result
},
],
},
]
# 올바른 예: 추가 텍스트 없이 도구 결과를 직접 전송
messages = [
{"role": "user", "content": "Calculate the sum of 1234 and 5678"},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_123",
"name": "calculator",
"input": {"operation": "add", "a": 1234, "b": 5678},
}
],
},
{
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": "toolu_123", "content": "6912"}
],
}, # Just the tool_result, no additional text
]
```
```typescript TypeScript
// 잘못된 예: tool_result 바로 뒤에 텍스트 추가
let messages: Anthropic.MessageParam[] = [
{ role: "user", content: "Calculate the sum of 1234 and 5678" },
{
role: "assistant",
content: [
{
type: "tool_use",
id: "toolu_123",
name: "calculator",
input: { operation: "add", a: 1234, b: 5678 }
}
]
},
{
role: "user",
content: [
{ type: "tool_result", tool_use_id: "toolu_123", content: "6912" },
{ type: "text", text: "Here's the result" } // Don't add text after tool_result
]
}
];
// 올바른 예: 추가 텍스트 없이 도구 결과를 직접 전송
messages = [
{ role: "user", content: "Calculate the sum of 1234 and 5678" },
{
role: "assistant",
content: [
{
type: "tool_use",
id: "toolu_123",
name: "calculator",
input: { operation: "add", a: 1234, b: 5678 }
}
]
},
{
role: "user",
// tool_result만 포함, 추가 텍스트 없음
content: [{ type: "tool_result", tool_use_id: "toolu_123", content: "6912" }]
}
];
```
```csharp C#
using System.Text.Json;
using Anthropic.Models.Messages;
var input = JsonSerializer.Deserialize>(
"""{"operation":"add","a":1234,"b":5678}"""
)!;
// 잘못된 예: tool_result 바로 뒤에 텍스트 추가
List messages =
[
new() { Role = Role.User, Content = "Calculate the sum of 1234 and 5678" },
new()
{
Role = Role.Assistant,
Content = new List
{
new ToolUseBlockParam { ID = "toolu_123", Name = "calculator", Input = input }
}
},
new()
{
Role = Role.User,
Content = new List
{
new ToolResultBlockParam { ToolUseID = "toolu_123", Content = "6912" },
new TextBlockParam { Text = "Here's the result" } // Don't add text after tool_result
}
}
];
// 올바른 예: 추가 텍스트 없이 도구 결과를 직접 전송
messages =
[
new() { Role = Role.User, Content = "Calculate the sum of 1234 and 5678" },
new()
{
Role = Role.Assistant,
Content = new List
{
new ToolUseBlockParam { ID = "toolu_123", Name = "calculator", Input = input }
}
},
new()
{
Role = Role.User,
// tool_result만 포함, 추가 텍스트 없음
Content = new List
{
new ToolResultBlockParam { ToolUseID = "toolu_123", Content = "6912" }
}
}
];
```
```go Go
input := map[string]any{"operation": "add", "a": 1234, "b": 5678}
// 잘못된 예: tool_result 바로 뒤에 텍스트 추가
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Calculate the sum of 1234 and 5678")),
anthropic.NewAssistantMessage(
anthropic.NewToolUseBlock("toolu_123", input, "calculator"),
),
anthropic.NewUserMessage(
anthropic.NewToolResultBlock("toolu_123", "6912", false),
anthropic.NewTextBlock("Here's the result"), // Don't add text after tool_result
),
}
// 올바른 예: 추가 텍스트 없이 도구 결과를 직접 전송
messages = []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Calculate the sum of 1234 and 5678")),
anthropic.NewAssistantMessage(
anthropic.NewToolUseBlock("toolu_123", input, "calculator"),
),
// tool_result만 포함, 추가 텍스트 없음
anthropic.NewUserMessage(
anthropic.NewToolResultBlock("toolu_123", "6912", false),
),
}
```
```java Java
ToolUseBlockParam toolUse = ToolUseBlockParam.builder()
.id("toolu_123")
.name("calculator")
.input(ToolUseBlockParam.Input.builder()
.putAdditionalProperty("operation", JsonValue.from("add"))
.putAdditionalProperty("a", JsonValue.from(1234))
.putAdditionalProperty("b", JsonValue.from(5678))
.build())
.build();
// 잘못된 예: tool_result 바로 뒤에 텍스트를 추가함
List messages = List.of(
MessageParam.builder().role(MessageParam.Role.USER)
.content("Calculate the sum of 1234 and 5678").build(),
MessageParam.builder().role(MessageParam.Role.ASSISTANT)
.contentOfBlockParams(List.of(ContentBlockParam.ofToolUse(toolUse))).build(),
MessageParam.builder().role(MessageParam.Role.USER)
.contentOfBlockParams(List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder().toolUseId("toolu_123").content("6912").build()),
// tool_result 뒤에 텍스트를 추가하지 마세요
ContentBlockParam.ofText(TextBlockParam.builder().text("Here's the result").build())
)).build()
);
// 올바른 예: 추가 텍스트 없이 도구 결과를 직접 전송함
messages = List.of(
MessageParam.builder().role(MessageParam.Role.USER)
.content("Calculate the sum of 1234 and 5678").build(),
MessageParam.builder().role(MessageParam.Role.ASSISTANT)
.contentOfBlockParams(List.of(ContentBlockParam.ofToolUse(toolUse))).build(),
// tool_result만 포함하고 추가 텍스트는 없음
MessageParam.builder().role(MessageParam.Role.USER)
.contentOfBlockParams(List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder().toolUseId("toolu_123").content("6912").build())
)).build()
);
```
```php PHP
// 잘못된 예: tool_result 바로 뒤에 텍스트를 추가함
$messages = [
['role' => 'user', 'content' => 'Calculate the sum of 1234 and 5678'],
[
'role' => 'assistant',
'content' => [
[
'type' => 'tool_use',
'id' => 'toolu_123',
'name' => 'calculator',
'input' => ['operation' => 'add', 'a' => 1234, 'b' => 5678],
],
],
],
[
'role' => 'user',
'content' => [
['type' => 'tool_result', 'tool_use_id' => 'toolu_123', 'content' => '6912'],
// tool_result 뒤에 텍스트를 추가하지 마세요
['type' => 'text', 'text' => "Here's the result"],
],
],
];
// 올바른 예: 추가 텍스트 없이 도구 결과를 직접 전송함
$messages = [
['role' => 'user', 'content' => 'Calculate the sum of 1234 and 5678'],
[
'role' => 'assistant',
'content' => [
[
'type' => 'tool_use',
'id' => 'toolu_123',
'name' => 'calculator',
'input' => ['operation' => 'add', 'a' => 1234, 'b' => 5678],
],
],
],
[
'role' => 'user',
// tool_result만 포함하고 추가 텍스트는 없음
'content' => [
['type' => 'tool_result', 'tool_use_id' => 'toolu_123', 'content' => '6912'],
],
],
];
```
```ruby Ruby
# 잘못된 예: tool_result 바로 뒤에 텍스트를 추가함
messages = [
{ role: "user", content: "Calculate the sum of 1234 and 5678" },
{
role: "assistant",
content: [
{
type: "tool_use",
id: "toolu_123",
name: "calculator",
input: { operation: "add", a: 1234, b: 5678 }
}
]
},
{
role: "user",
content: [
{ type: "tool_result", tool_use_id: "toolu_123", content: "6912" },
# tool_result 뒤에 텍스트를 추가하지 마세요
{ type: "text", text: "Here's the result" }
]
}
]
# 올바른 예: 추가 텍스트 없이 도구 결과를 직접 전송
messages = [
{ role: "user", content: "Calculate the sum of 1234 and 5678" },
{
role: "assistant",
content: [
{
type: "tool_use",
id: "toolu_123",
name: "calculator",
input: { operation: "add", a: 1234, b: 5678 }
}
]
},
{
role: "user",
# tool_result만 포함하고 추가 텍스트는 없음
content: [
{ type: "tool_result", tool_use_id: "toolu_123", content: "6912" }
]
}
]
```
메시지 구조를 수정한 후에도 여전히 빈 응답을 받는다면, 빈 응답으로 재시도하는 대신 새 사용자 메시지에 계속 진행 프롬프트를 추가하세요:
```python Python
def handle_empty_response(client, messages):
response = client.messages.create(
model="claude-opus-5-5", max_tokens=1024, messages=messages
)
# 응답이 비어 있는지 확인합니다
if response.stop_reason == "end_turn" and not response.content:
# 잘못된 방법: 빈 응답을 그대로 두고 재시도하지 마세요
# Claude가 이미 완료했다고 판단했으므로 이 방법은 작동하지 않습니다
# 올바른 방법: 새 user 메시지에 계속 진행하라는 프롬프트를 추가하세요
messages.append({"role": "user", "content": "Please continue"})
response = client.messages.create(
model="claude-opus-5-5", max_tokens=1024, messages=messages
)
return response
```
```typescript TypeScript
async function handleEmptyResponse(
client: Anthropic,
messages: Anthropic.MessageParam[]
): Promise {
let response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages
});
// 응답이 비어 있는지 확인합니다
if (response.stop_reason === "end_turn" && response.content.length === 0) {
// 잘못된 예: 빈 응답을 그대로 두고 재시도하지 마세요
// Claude가 이미 완료했다고 판단했으므로 이 방법은 작동하지 않습니다
// 올바른 예: 새 사용자 메시지에 계속 진행하라는 프롬프트를 추가하세요
messages.push({ role: "user", content: "Please continue" });
response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages
});
}
return response;
}
```
```csharp C#
static async Task HandleEmptyResponse(AnthropicClient client, List messages)
{
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = messages
});
// 응답이 비어 있는지 확인합니다
if (response.StopReason == "end_turn" && response.Content.Count == 0)
{
// 올바른 방법: 새 사용자 메시지에 이어서 작성하도록 요청하는 프롬프트를 추가합니다
messages.Add(new() { Role = Role.User, Content = "Please continue" });
response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = messages
});
}
return response;
}
```
```go Go
func handleEmptyResponse(client anthropic.Client, messages []anthropic.MessageParam) (*anthropic.Message, error) {
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
})
if err != nil {
return nil, err
}
// 응답이 비어 있는지 확인합니다
if response.StopReason == "end_turn" && len(response.Content) == 0 {
// 올바른 방법: 새 user 메시지에 계속 진행을 요청하는 프롬프트를 추가합니다
messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Please continue")))
response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
})
if err != nil {
return nil, err
}
}
return response, nil
}
```
```java Java
static Message handleEmptyResponse(AnthropicClient client, List messages) {
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.messages(messages)
.build()
);
// 응답이 비어 있는지 확인합니다
boolean isEndTurn = response.stopReason().map(StopReason.END_TURN::equals).orElse(false);
if (isEndTurn && response.content().isEmpty()) {
// 올바른 방법: 새 user 메시지에 계속 진행 프롬프트를 추가합니다
List extended = new ArrayList<>(messages);
extended.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.content("Please continue")
.build());
response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.messages(extended)
.build()
);
}
return response;
}
```
```php PHP
function handle_empty_response(Client $client, array $messages)
{
$response = $client->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-opus-5-5',
);
// 응답이 비어 있는지 확인합니다
if ($response->stopReason === 'end_turn' && count($response->content) === 0) {
// 올바른 방법: 새 user 메시지에 계속 진행 프롬프트를 추가합니다
$messages[] = ['role' => 'user', 'content' => 'Please continue'];
$response = $client->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-opus-5-5',
);
}
return $response;
}
```
```ruby Ruby
def handle_empty_response(client, messages)
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: messages
)
# 응답이 비어 있는지 확인합니다
if response.stop_reason == :end_turn && response.content.empty?
# 올바른 방법: 새 user 메시지에 계속 진행 프롬프트를 추가합니다
messages << { role: "user", content: "Please continue" }
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: messages
)
end
response
end
```
**모범 사례:**
1. **도구 결과 바로 뒤에 텍스트 블록을 절대 추가하지 마세요:** 이는 Claude가 모든 도구 사용 후에 사용자 입력을 기대하도록 학습시킵니다.
2. **빈 응답을 수정 없이 재시도하지 마세요:** 빈 응답을 다시 보내는 것은 도움이 되지 않습니다.
3. **계속 진행 프롬프트는 최후의 수단으로 사용하세요:** 위의 수정 사항으로 문제가 해결되지 않는 경우에만 사용하세요.
### max\_tokens
Claude가 요청에 지정된 `max_tokens` 한도에 도달하여 중지했습니다.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 10,
"messages": [{"role": "user", "content": "Explain quantum physics"}]
}' | jq '.stop_reason'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 10 \
--message '{role: user, content: "Explain quantum physics"}' \
--format json | jq '.stop_reason'
```
```python Python
client = anthropic.Anthropic()
# 제한된 토큰으로 요청합니다
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=10,
messages=[{"role": "user", "content": "Explain quantum physics"}],
)
if response.stop_reason == "max_tokens":
# 응답이 잘렸습니다
print("Response was cut off at token limit")
# 이어서 받으려면 추가 요청을 보내는 것을 고려하세요
```
```typescript TypeScript
const client = new Anthropic();
// 제한된 토큰으로 요청합니다
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 10,
messages: [{ role: "user", content: "Explain quantum physics" }]
});
if (response.stop_reason === "max_tokens") {
// 응답이 잘렸습니다
console.log("Response was cut off at token limit");
// 계속하려면 추가 요청을 보내는 것을 고려하세요
}
```
```csharp C#
AnthropicClient client = new();
// 제한된 토큰으로 요청합니다
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 10,
Messages = [new() { Role = Role.User, Content = "Explain quantum physics" }]
});
if (response.StopReason == "max_tokens")
{
// 응답이 잘렸습니다
Console.WriteLine("Response was cut off at token limit");
// 이어서 받으려면 추가 요청을 보내는 것을 고려하세요
}
```
```go Go
client := anthropic.NewClient()
// 제한된 토큰으로 요청합니다
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 10,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Explain quantum physics")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "max_tokens" {
// 응답이 잘렸습니다
fmt.Println("Response was cut off at token limit")
// 이어서 생성하려면 추가 요청을 보내는 것을 고려하세요
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// 제한된 토큰으로 요청합니다
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(10L)
.addUserMessage("Explain quantum physics")
.build()
);
if (response.stopReason().map(StopReason.MAX_TOKENS::equals).orElse(false)) {
// 응답이 잘렸습니다
IO.println("Response was cut off at token limit");
// 계속하려면 추가 요청을 보내는 것을 고려하세요
}
```
```php PHP
$client = new Client();
// 제한된 토큰으로 요청합니다
$response = $client->messages->create(
maxTokens: 10,
messages: [['role' => 'user', 'content' => 'Explain quantum physics']],
model: 'claude-opus-5-5',
);
if ($response->stopReason === 'max_tokens') {
// 응답이 잘렸습니다
echo 'Response was cut off at token limit', PHP_EOL;
// 이어서 생성하려면 추가 요청을 보내는 것을 고려하세요
}
```
```ruby Ruby
client = Anthropic::Client.new
# 제한된 토큰으로 요청합니다
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 10,
messages: [{ role: "user", content: "Explain quantum physics" }]
)
if response.stop_reason == :max_tokens
# 응답이 잘렸습니다
puts "Response was cut off at token limit"
# 계속하려면 추가 요청을 보내는 것을 고려하세요
end
```
Claude의 응답이 `max_tokens` 한도에 도달하여 잘렸고, 잘린 응답에 불완전한 도구 사용 블록이 포함되어 있다면, 전체 도구 사용을 얻기 위해 더 높은 `max_tokens` 값으로 요청을 재시도해야 합니다.
```bash CLI
RESPONSE=$(ant messages create --max-tokens 1024 --format jsonl <<'YAML'
model: claude-opus-5-5
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
required:
- location
messages:
- role: user
content: What is the weather in San Francisco?
YAML
)
# 응답이 도구 사용 도중에 잘렸는지 확인합니다
STOP_REASON=$(jq -r '.stop_reason' <<<"$RESPONSE")
LAST_TYPE=$(jq -r '.content[-1].type' <<<"$RESPONSE")
if [ "$STOP_REASON" = "max_tokens" ] && [ "$LAST_TYPE" = "tool_use" ]; then
# 더 높은 max_tokens 값으로 다시 시도합니다
ant messages create --max-tokens 4096 <<'YAML'
model: claude-opus-5-5
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
required:
- location
messages:
- role: user
content: What is the weather in San Francisco?
YAML
fi
```
```python Python
# 도구 사용 중 응답이 잘렸는지 확인합니다
if response.stop_reason == "max_tokens":
# 마지막 콘텐츠 블록이 불완전한 tool_use인지 확인합니다
last_block = response.content[-1]
if last_block.type == "tool_use":
# 더 높은 max_tokens 값으로 요청을 보냅니다
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096, # Increased limit
messages=messages,
tools=tools,
)
```
```typescript TypeScript
// 도구 사용 중 응답이 잘렸는지 확인합니다
if (response.stop_reason === "max_tokens") {
// 마지막 콘텐츠 블록이 불완전한 tool_use인지 확인합니다
const lastBlock = response.content[response.content.length - 1];
if (lastBlock.type === "tool_use") {
// 더 높은 max_tokens 값으로 요청을 보냅니다
response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096, // Increased limit
messages: messages,
tools: tools
});
}
}
```
```csharp C#
using System.Linq;
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = messages,
Tools = tools
};
var response = await client.Messages.Create(parameters);
if (response.StopReason == "max_tokens")
{
var lastBlock = response.Content.Last();
if (lastBlock.TryPickToolUse(out _))
{
response = await client.Messages.Create(parameters with { MaxTokens = 4096 });
}
}
```
```go Go
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
Tools: tools,
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "max_tokens" {
lastBlock := response.Content[len(response.Content)-1]
switch lastBlock.AsAny().(type) {
case anthropic.ToolUseBlock:
response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: messages,
Tools: tools,
})
if err != nil {
log.Fatal(err)
}
}
}
```
```java Java
// 도구 사용 중에 응답이 잘렸는지 확인합니다
if (response.stopReason().isPresent() && response.stopReason().get().equals(StopReason.MAX_TOKENS)) {
ContentBlock lastBlock = response.content().get(response.content().size() - 1);
if (lastBlock.toolUse().isPresent()) {
// 더 높은 max_tokens 값으로 요청을 보냅니다
response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L) // Increased limit
.messages(messages)
.tools(tools)
.build()
);
}
}
```
```php PHP
$response = $client->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-opus-5-5',
tools: $tools,
);
if ($response->stopReason === 'max_tokens') {
$lastBlock = end($response->content);
if ($lastBlock->type === 'tool_use') {
$response = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
tools: $tools,
);
}
}
```
```ruby Ruby
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: messages,
tools: tools
)
if response.stop_reason == :max_tokens
last_block = response.content.last
if last_block.type == :tool_use
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
messages: messages,
tools: tools
)
end
end
```
### stop\_sequence
Claude가 사용자 지정 중지 시퀀스 중 하나를 만났습니다.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"stop_sequences": ["END", "STOP"],
"messages": [{"role": "user", "content": "Generate text until you say END"}]
}' | jq '{stop_reason, stop_sequence}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 1024 \
--stop-sequence END --stop-sequence STOP \
--message '{role: user, content: "Generate text until you say END"}' \
--format json | jq '{stop_reason, stop_sequence}'
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
stop_sequences=["END", "STOP"],
messages=[{"role": "user", "content": "Generate text until you say END"}],
)
if response.stop_reason == "stop_sequence":
print(f"Stopped at sequence: {response.stop_sequence}")
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
stop_sequences: ["END", "STOP"],
messages: [{ role: "user", content: "Generate text until you say END" }]
});
if (response.stop_reason === "stop_sequence") {
console.log(`Stopped at sequence: ${response.stop_sequence}`);
}
```
```csharp C#
AnthropicClient client = new();
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
StopSequences = ["END", "STOP"],
Messages = [new() { Role = Role.User, Content = "Generate text until you say END" }]
});
if (response.StopReason == "stop_sequence")
{
Console.WriteLine($"Stopped at sequence: {response.StopSequence}");
}
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
StopSequences: []string{"END", "STOP"},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Generate text until you say END")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "stop_sequence" {
fmt.Printf("Stopped at sequence: %s\n", response.StopSequence)
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addStopSequence("END")
.addStopSequence("STOP")
.addUserMessage("Generate text until you say END")
.build()
);
if (response.stopReason().map(StopReason.STOP_SEQUENCE::equals).orElse(false)) {
IO.println("Stopped at sequence: " + response.stopSequence().orElse(""));
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Generate text until you say END']],
model: 'claude-opus-5-5',
stopSequences: ['END', 'STOP'],
);
if ($response->stopReason === 'stop_sequence') {
echo "Stopped at sequence: {$response->stopSequence}", PHP_EOL;
}
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
stop_sequences: ["END", "STOP"],
messages: [{ role: "user", content: "Generate text until you say END" }]
)
if response.stop_reason == :stop_sequence
puts "Stopped at sequence: #{response.stop_sequence}"
end
```
### tool\_use
Claude가 도구를 호출하고 있으며 사용자가 이를 실행하기를 기대합니다.
대부분의 도구 사용 구현에서는 도구 실행, 결과 포맷팅, 대화 관리를 자동으로 처리하는 [tool runner](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-runner)를 사용하세요.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {"location": {"type": "string", "description": "City and state"}},
"required": ["location"]
}
}],
"messages": [{"role": "user", "content": "What is the weather in San Francisco?"}]
}' | jq '.stop_reason, (.content[] | select(.type == "tool_use"))'
```
```bash CLI
ant messages create --format json <<'YAML' | jq '.stop_reason, (.content[] | select(.type == "tool_use"))'
model: claude-opus-5-5
max_tokens: 1024
messages:
- role: user
content: What is the weather in San Francisco?
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location: {type: string, description: City and state}
required: [location]
YAML
```
```python Python
client = anthropic.Anthropic()
weather_tool = {
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City and state"},
},
"required": ["location"],
},
}
def execute_tool(name, tool_input):
"""Execute a tool and return the result."""
return f"Weather in {tool_input.get('location', 'unknown')}: 72°F"
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[weather_tool],
messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
)
if response.stop_reason == "tool_use":
# 도구를 추출하고 실행합니다
for block in response.content:
if block.type == "tool_use":
result = execute_tool(block.name, block.input)
# 최종 응답을 위해 결과를 Claude에 반환합니다
```
```typescript TypeScript
const client = new Anthropic();
const weatherTool: Anthropic.Tool = {
name: "get_weather",
description: "Get the current weather in a given location",
input_schema: {
type: "object",
properties: {
location: { type: "string", description: "City and state" }
},
required: ["location"]
}
};
function executeTool(name: string, input: Record): string {
return `Weather in ${input.location ?? "unknown"}: 72°F`;
}
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools: [weatherTool],
messages: [{ role: "user", content: "What is the weather in San Francisco?" }]
});
if (response.stop_reason === "tool_use") {
// 도구를 추출하고 실행합니다
for (const block of response.content) {
if (block.type === "tool_use") {
const result = executeTool(block.name, block.input as Record);
// 최종 응답을 위해 결과를 Claude에 반환합니다
}
}
}
```
```csharp C#
AnthropicClient client = new();
var weatherTool = new Tool
{
Name = "get_weather",
Description = "Get the current weather in a given location",
InputSchema = new InputSchema
{
Properties = new Dictionary
{
["location"] = JsonSerializer.SerializeToElement(
new { type = "string", description = "City and state" }
),
},
Required = ["location"]
}
};
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools = [weatherTool],
Messages = [new() { Role = Role.User, Content = "What is the weather in San Francisco?" }]
});
if (response.StopReason == "tool_use")
{
// 도구를 추출하고 실행합니다
foreach (var block in response.Content)
{
if (block.TryPickToolUse(out var toolUse))
{
// toolUse.Input으로 toolUse.Name을 실행하고 결과를 Claude에 반환합니다
}
}
}
```
```go Go
client := anthropic.NewClient()
weatherTool := anthropic.ToolParam{
Name: "get_weather",
Description: anthropic.String("Get the current weather in a given location"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"location": map[string]string{"type": "string", "description": "City and state"},
},
Required: []string{"location"},
},
}
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{{OfTool: &weatherTool}},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather in San Francisco?")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "tool_use" {
// 도구를 추출하고 실행합니다
for _, block := range response.Content {
if toolUse, ok := block.AsAny().(anthropic.ToolUseBlock); ok {
fmt.Println(toolUse.Name, toolUse.Input)
// 최종 응답을 위해 결과를 Claude에 반환합니다
}
}
}
```
```java Java
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Tool weatherTool = Tool.builder()
.name("get_weather")
.description("Get the current weather in a given location")
.inputSchema(Tool.InputSchema.builder()
.properties(JsonValue.from(Map.of(
"location", Map.of("type", "string", "description", "City and state")
)))
.putAdditionalProperty("required", JsonValue.from(List.of("location")))
.build())
.build();
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(weatherTool)
.addUserMessage("What is the weather in San Francisco?")
.build()
);
if (response.stopReason().map(StopReason.TOOL_USE::equals).orElse(false)) {
// 도구를 추출하고 실행합니다
for (ContentBlock block : response.content()) {
block.toolUse().ifPresent(toolUse -> {
// toolUse.input()으로 toolUse.name()을 실행하고 결과를 Claude에 반환합니다
});
}
}
```
```php PHP
$client = new Client();
$weatherTool = [
'name' => 'get_weather',
'description' => 'Get the current weather in a given location',
'input_schema' => [
'type' => 'object',
'properties' => [
'location' => ['type' => 'string', 'description' => 'City and state'],
],
'required' => ['location'],
],
];
$response = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'What is the weather in San Francisco?']],
model: 'claude-opus-5-5',
tools: [$weatherTool],
);
if ($response->stopReason === 'tool_use') {
// 도구를 추출하고 실행합니다
foreach ($response->content as $block) {
if ($block->type === 'tool_use') {
// $block->input으로 $block->name을 실행하고 결과를 Claude에 반환합니다
}
}
}
```
```ruby Ruby
client = Anthropic::Client.new
weather_tool = {
name: "get_weather",
description: "Get the current weather in a given location",
input_schema: {
type: "object",
properties: {
location: { type: "string", description: "City and state" }
},
required: ["location"]
}
}
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: [weather_tool],
messages: [{ role: "user", content: "What is the weather in San Francisco?" }]
)
if response.stop_reason == :tool_use
# 도구를 추출하고 실행합니다
response.content.each do |block|
next unless block.type == :tool_use
# block.input으로 block.name을 실행하고 결과를 Claude에 반환합니다
end
end
```
`tool_use` 응답에는 `id`에 대응하는 결과 블록이 없는 `server_tool_use` 블록이 포함될 수도 있습니다. 해당 서버 도구 호출은 완료되지 않은 것이며, 이 응답에는 그 결과가 담겨 있지 않습니다. 일반적인 경우는 Claude가 동일한 병렬 도구 호출 그룹에서 [서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools)와 클라이언트 도구 중 하나를 함께 호출하는 경우입니다. API는 사용자가 클라이언트 도구를 먼저 실행할 수 있도록 서버 도구를 실행하지 않고 반환합니다. 이 상태를 나타내는 다른 표시는 없으며, 각 `server_tool_use` 또는 `mcp_tool_use` 블록의 `id`에 대응하는 결과 블록이 있는지 확인하여 감지하세요.
[프로그래매틱 도구 호출](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/programmatic-tool-calling)을 사용하는 경우, 동일한 응답 형태가 다른 의미를 가집니다. 클라이언트 `tool_use` 블록은 Claude가 직접 생성한 것이 아니라 `code_execution` 도구에서 실행 중인 코드에서 나온 것이며, 그 `caller` 필드는 이를 호출한 `code_execution` 블록을 가리킵니다. 해당 코드는 이미 시작된 상태입니다. 사용자의 `tool_result` 블록을 기다리며 일시 중지되어 있고, 이를 보내면 지연된 도구를 시작하는 대신 실행이 재개됩니다. `code_execution` 블록 자체의 결과 블록은 코드가 완료되면 도착하며, 이는 한 번 이상의 도구 결과 라운드가 걸릴 수 있습니다. 후속 사용자 메시지 자체는 두 경우 모두 동일합니다. 프로그래매틱 도구 호출의 경우, 해당 페이지에서 보여주는 것처럼 응답의 `container` 필드에 있는 `id`도 함께 다시 전달하세요.
```json A mixed tool_use response
{
"stop_reason": "tool_use",
"content": [
{
"type": "server_tool_use",
"id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
"name": "web_search",
"input": { "query": "example article" }
},
{
"type": "tool_use",
"id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
"name": "run_command",
"input": { "command": "uname -a" }
}
]
}
```
계속 진행은 응답의 모든 `tool_use` 블록마다 하나씩 `tool_result` 블록으로 구성된 사용자 메시지입니다([도구 호출 처리](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/handle-tool-calls) 참조). 여기에 두 가지 추가 규칙이 있습니다. 해당 메시지에는 `tool_result` 블록 외에 아무것도 포함되어서는 안 되며, 요청은 동일한 `tools` 배열을 유지해야 합니다. 대기 중인 서버 도구를 더 이상 정의하지 않는 재개 요청은 메시지가 ``but no `web_search` tool was provided``로 끝나는 400 오류로 실패합니다. API는 사용자의 결과를 아직 열려 있는 어시스턴트 턴에 첨부하고, 지연된 서버 도구를 실행하며(일시 중지된 코드 실행의 경우 재개하며), 턴을 계속합니다. Claude가 직접 호출한 서버 도구의 경우, 다음 응답의 `content`는 이전 응답의 `server_tool_use` `id`에 응답하는 결과 블록으로 시작합니다.
```json The follow-up user message
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
"content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
}
]
}
```
해당 사용자 메시지에서 `tool_result` 블록 뒤에 텍스트 등 무언가를 추가하면 어시스턴트 턴이 종료됩니다. Claude가 직접 호출한 서버 도구의 경우, 요청은 해결되지 않은 서버 도구의 이름을 명시하는 400 `invalid_request_error`로 실패합니다:
```text wrap
`web_search` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_search_tool_result` block
```
`tool_result`를 빠뜨리거나 다른 콘텐츠 뒤에 배치하면, 대신 표준 `tool_use ids were found without tool_result blocks immediately after` 오류로 더 일찍 실패합니다. Claude에게 추가 입력을 제공하려면 턴이 완료된 후 별도의 사용자 메시지로 보내세요.
### pause\_turn
웹 검색과 같은 [서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools)를 실행하는 동안 서버 측 샘플링 루프가 반복 한도에 도달하면 반환됩니다. 기본 한도는 요청당 10회 반복입니다.
이 경우 응답에는 대응하는 결과 블록이 없는 `server_tool_use` 블록이 포함될 수 있습니다. Claude가 처리를 마칠 수 있도록 응답을 그대로 다시 보내 대화를 계속하세요. 클라이언트 `tool_use` 블록이 사용자를 기다리는 상태로 남겨진 응답은 `stop_reason`이 `pause_turn`인 경우가 절대 없습니다. Claude가 사용자의 도구를 호출하기 위해 중지할 때 `stop_reason`은 [`tool_use`](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#tool-use)이며, 응답 자체 대신 클라이언트 `tool_result` 블록을 보내 계속 진행합니다.
```bash cURL
# SDK는 이어서 생성하기를 직접 처리합니다. cURL을 사용하는 경우 응답의 stop_reason을
# 확인하고, assistant 콘텐츠를 추가하여 다시 POST 요청을 보내세요.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"tools": [{"type": "web_search_20250305", "name": "web_search"}],
"messages": [{"role": "user", "content": "Search for latest AI news"}]
}' | jq '{stop_reason, content}'
```
```bash CLI
# stop_reason 을 확인하세요. pause_turn 이면 assistant
# 응답을 --message 에 추가하여 다시 실행하세요.
ant messages create --format json <<'YAML' | jq '{stop_reason, content}'
model: claude-opus-5-5
max_tokens: 4096
tools:
- {type: web_search_20250305, name: web_search}
messages:
- {role: user, content: "Search for latest AI news"}
YAML
```
```python Python
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
tools=[{"type": "web_search_20250305", "name": "web_search"}],
messages=[{"role": "user", "content": "Search for latest AI news"}],
)
if response.stop_reason == "pause_turn":
# 응답을 다시 보내 대화를 이어 갑니다
messages = [
{"role": "user", "content": "Search for latest AI news"},
{"role": "assistant", "content": response.content},
]
continuation = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=messages,
tools=[{"type": "web_search_20250305", "name": "web_search"}],
)
```
```typescript TypeScript
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
tools: [{ type: "web_search_20250305", name: "web_search" }],
messages: [{ role: "user", content: "Search for latest AI news" }]
});
if (response.stop_reason === "pause_turn") {
// 응답을 다시 보내 대화를 이어 갑니다
const continuation = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
tools: [{ type: "web_search_20250305", name: "web_search" }],
messages: [
{ role: "user", content: "Search for latest AI news" },
{ role: "assistant", content: response.content }
]
});
}
```
```csharp C#
List tools = [new ToolUnion(new WebSearchTool20250305())];
MessageParam userMessage = new() { Role = Role.User, Content = "Search for latest AI news" };
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Tools = tools,
Messages = [userMessage]
});
if (response.StopReason == "pause_turn")
{
// 응답을 다시 보내 대화를 이어 갑니다
var continuation = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Tools = tools,
Messages =
[
userMessage,
new()
{
Role = Role.Assistant,
Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
}
]
});
}
```
```go Go
tools := []anthropic.ToolUnionParam{
{OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{}},
}
userMessage := anthropic.NewUserMessage(anthropic.NewTextBlock("Search for latest AI news"))
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Tools: tools,
Messages: []anthropic.MessageParam{userMessage},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "pause_turn" {
// 응답을 다시 보내 대화를 이어 갑니다
var contentParams []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
contentParams = append(contentParams, block.ToParam())
}
continuation, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Tools: tools,
Messages: []anthropic.MessageParam{userMessage, anthropic.NewAssistantMessage(contentParams...)},
})
if err != nil {
log.Fatal(err)
}
_ = continuation
}
```
```java Java
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addTool(WebSearchTool20250305.builder().build())
.addUserMessage("Search for latest AI news")
.build()
);
if (response.stopReason().map(StopReason.PAUSE_TURN::equals).orElse(false)) {
// 응답을 다시 보내 대화를 이어 갑니다
Message continuation = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addTool(WebSearchTool20250305.builder().build())
.addUserMessage("Search for latest AI news")
.addMessage(response)
.build()
);
}
```
```php PHP
$tools = [['type' => 'web_search_20250305', 'name' => 'web_search']];
$userMessage = ['role' => 'user', 'content' => 'Search for latest AI news'];
$response = $client->messages->create(
maxTokens: 4096,
messages: [$userMessage],
model: 'claude-opus-5-5',
tools: $tools,
);
if ($response->stopReason === 'pause_turn') {
// 응답을 다시 전송하여 대화를 이어 갑니다
$continuation = $client->messages->create(
maxTokens: 4096,
messages: [
$userMessage,
['role' => 'assistant', 'content' => $response->content],
],
model: 'claude-opus-5-5',
tools: $tools,
);
}
```
```ruby Ruby
tools = [{ type: "web_search_20250305", name: "web_search" }]
user_message = { role: "user", content: "Search for latest AI news" }
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
tools: tools,
messages: [user_message]
)
if response.stop_reason == :pause_turn
# 응답을 다시 보내 대화를 이어 갑니다
continuation = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
tools: tools,
messages: [user_message, { role: "assistant", content: response.content }]
)
end
```
애플리케이션은 서버 도구를 사용하는 모든 에이전트 루프에서 `pause_turn`을 처리해야 합니다. 어시스턴트의 응답을 messages 배열에 추가하고 Claude가 계속할 수 있도록 또 다른 API 요청을 보내세요.
### refusal
Claude가 응답 생성을 거부했습니다. 안전 분류기는 이 중지 이유를 오류가 아닌 정상적인 HTTP 200 응답으로 반환합니다.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "[Unsafe request]"}]
}' | jq '{stop_reason, stop_details}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "[Unsafe request]"}' \
--format json | jq '{stop_reason, stop_details}'
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "[Unsafe request]"}],
)
if response.stop_reason == "refusal":
# Claude가 응답을 거부했습니다
print("Claude was unable to process this request")
# 요청을 다른 표현으로 바꾸거나 수정해 보세요
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "[Unsafe request]" }]
});
if (response.stop_reason === "refusal") {
// Claude가 응답을 거부했습니다
console.log("Claude was unable to process this request");
// 요청을 다른 표현으로 바꾸거나 수정해 보세요
}
```
```csharp C#
AnthropicClient client = new();
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "[Unsafe request]" }]
});
if (response.StopReason == "refusal")
{
// Claude가 응답을 거부했습니다
Console.WriteLine("Claude was unable to process this request");
// 요청을 다른 표현으로 바꾸거나 수정해 보세요
}
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("[Unsafe request]")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "refusal" {
// Claude가 응답을 거부했습니다
fmt.Println("Claude was unable to process this request")
// 요청을 다른 표현으로 바꾸거나 수정해 보세요
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("[Unsafe request]")
.build()
);
if (response.stopReason().map(StopReason.REFUSAL::equals).orElse(false)) {
// Claude가 응답을 거부했습니다
IO.println("Claude was unable to process this request");
// 요청을 다른 표현으로 바꾸거나 수정해 보세요
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => '[Unsafe request]']],
model: 'claude-opus-5-5',
);
if ($response->stopReason === 'refusal') {
// Claude가 응답을 거부했습니다
echo 'Claude was unable to process this request', PHP_EOL;
// 요청을 다른 표현으로 바꾸거나 수정해 보세요
}
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "[Unsafe request]" }]
)
if response.stop_reason == :refusal
# Claude가 응답을 거부했습니다
puts "Claude was unable to process this request"
# 요청을 다른 표현으로 바꾸거나 수정해 보세요
end
```
Claude Sonnet 4.5([지원 중단](https://platform.claude.com/docs/ko/about-claude/model-deprecations)) 또는 Claude Opus 4.1(후자는 [Bedrock 및 Google Cloud를 제외하고 종료](https://platform.claude.com/docs/ko/about-claude/model-deprecations))을 사용하는 동안 `refusal` 중지 이유가 자주 발생한다면, 사용 제한이 다른 Haiku 4.5(`claude-haiku-4-5-20251001`)를 사용하도록 API 호출을 업데이트해 볼 수 있습니다. [Sonnet 4.5의 API 안전 필터 이해하기](https://support.claude.com/en/articles/12449294-understanding-sonnet-4-5-s-api-safety-filters)에서 자세히 알아보세요.
거부 시 `stop_details` 객체는 이를 유발한 정책 카테고리를 식별합니다. 카테고리와 전체 거부 응답 형태는 [거부와 폴백](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback#refusal-response)에서 다룹니다. `stop_details`는 `refusal` 이외의 모든 중지 이유에 대해 `null`입니다.
Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 또는 Claude Haiku 5.5에서 거부된 요청은 일반적으로 다른 Claude 모델로 재시도하여 처리할 수 있습니다. [거부와 폴백](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback)에서는 서버 측 또는 클라이언트에서 해당 재시도를 설정하는 방법을 보여줍니다. Claude Haiku 5.5에는 서버 측 폴백이 없으므로 재시도를 [클라이언트에서](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback#client-side-fallback) 설정하세요. Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5 또는 Claude Sonnet 5.5에서 재시도를 직접 구축하는 경우, [폴백 크레딧](https://platform.claude.com/docs/ko/build-with-claude/fallback-credit)에서 프롬프트 캐시 비용을 두 번 지불하지 않는 방법을 다룹니다.
### model\_context\_window\_exceeded
Claude가 모델의 컨텍스트 윈도우 한도에 도달하여 중지했습니다. 이를 통해 정확한 입력 크기를 알지 못해도 가능한 최대 토큰을 요청할 수 있습니다.
이 중지 이유는 현재 SDK의 `beta` (csharp, go: `Beta`; java: `beta()`) 네임스페이스에서만 타입이 정의되어 있으므로, 다음 예제는 `client.beta.messages` (csharp, go: `client.Beta.Messages`; java: `client.beta().messages()`; php: `$client->beta->messages`)를 호출하고 `Beta` 접두사가 붙은 타입을 사용합니다. Sonnet 4.5(지원 중단) 및 이후 모델에서는 API가 베타 헤더 없이 이 값을 반환합니다. 이전 모델의 경우 이를 활성화하려면 `model-context-window-exceeded-2025-08-26` 베타 헤더를 추가하세요.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 20000,
"messages": [{"role": "user", "content": "Large input that uses most of context window..."}]
}' | jq '.stop_reason'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 20000 \
--message '{role: user, content: "Large input that uses most of context window..."}' \
--format json | jq '.stop_reason'
```
```python Python
# 가능한 한 많은 출력을 얻기 위해 최대 토큰으로 요청합니다
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=20000, # Python SDK requires streaming for max_tokens above ~21k
messages=[
{"role": "user", "content": "Large input that uses most of context window..."}
],
)
if response.stop_reason == "model_context_window_exceeded":
# 응답이 max_tokens에 도달하기 전에 "context window"(컨텍스트 윈도우) 한도에 도달했습니다
print("Response reached model's context window limit")
# 응답은 여전히 유효하지만 컨텍스트 윈도우에 의해 제한되었습니다
```
```typescript TypeScript
// 가능한 한 많은 출력을 얻기 위해 최대 토큰 수로 요청합니다
const response = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 20000,
messages: [{ role: "user", content: "Large input that uses most of context window..." }]
});
if (response.stop_reason === "model_context_window_exceeded") {
// 응답이 max_tokens에 도달하기 전에 "context window"(컨텍스트 윈도우) 한도에 도달했습니다
console.log("Response reached model's context window limit");
// 응답은 여전히 유효하지만 컨텍스트 윈도우에 의해 제한되었습니다
}
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Model = Anthropic.Models.Messages.Model;
// 가능한 한 많이 받기 위해 최대 토큰 수로 요청합니다
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 20000,
Messages = [new() { Role = Role.User, Content = "Large input that uses most of context window..." }]
});
if (response.StopReason?.Value() == BetaStopReason.ModelContextWindowExceeded)
{
// 응답이 max_tokens에 도달하기 전에 "context window"(컨텍스트 윈도우) 한도에 도달했습니다
Console.WriteLine("Response reached model's context window limit");
// 응답은 여전히 유효하지만 컨텍스트 윈도우에 의해 제한되었습니다
}
```
```go Go
// 가능한 한 많은 출력을 얻기 위해 최대 토큰 수로 요청합니다
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 20000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Large input that uses most of context window...")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == anthropic.BetaStopReasonModelContextWindowExceeded {
// 응답이 max_tokens에 도달하기 전에 "context window"(컨텍스트 윈도우) 한도에 도달했습니다
fmt.Println("Response reached model's context window limit")
// 응답은 여전히 유효하지만 컨텍스트 윈도우에 의해 제한되었습니다
}
```
```java Java
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaStopReason;
import com.anthropic.models.beta.messages.MessageCreateParams;
// 가능한 한 많은 출력을 얻기 위해 최대 토큰으로 요청합니다
BetaMessage response = client.beta().messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(20000L)
.addUserMessage("Large input that uses most of context window...")
.build()
);
if (response.stopReason().map(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED::equals).orElse(false)) {
// 응답이 max_tokens에 도달하기 전에 "context window"(컨텍스트 윈도우) 한도에 도달했습니다
IO.println("Response reached model's context window limit");
// 응답은 여전히 유효하지만 컨텍스트 윈도우에 의해 제한되었습니다
}
```
```php PHP
// 가능한 한 많은 출력을 얻기 위해 최대 토큰 수로 요청합니다
$response = $client->beta->messages->create(
maxTokens: 20000,
messages: [['role' => 'user', 'content' => 'Large input that uses most of context window...']],
model: 'claude-opus-5-5',
);
if ($response->stopReason === 'model_context_window_exceeded') {
// 응답이 max_tokens에 도달하기 전에 컨텍스트 윈도우 한도에 도달했습니다
echo 'Response reached model\'s context window limit', PHP_EOL;
// 응답은 여전히 유효하지만 컨텍스트 윈도우에 의해 제한되었습니다
}
```
```ruby Ruby
# 가능한 한 많은 출력을 얻기 위해 최대 토큰으로 요청합니다
response = client.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 20000,
messages: [{ role: "user", content: "Large input that uses most of context window..." }]
)
if response.stop_reason == :model_context_window_exceeded
# 응답이 max_tokens에 도달하기 전에 "context window"(컨텍스트 윈도우) 한도에 도달했습니다
puts "Response reached model's context window limit"
# 응답은 여전히 유효하지만 컨텍스트 윈도우에 의해 제한되었습니다
end
```
## 중지 이유 처리를 위한 모범 사례
### 항상 stop\_reason을 확인하세요
응답 처리 로직에서 `stop_reason`을 확인하는 것을 습관화하세요:
```python Python
def handle_response(response):
match response.stop_reason:
case "tool_use":
return handle_tool_use(response)
case "max_tokens":
return handle_truncation(response)
case "model_context_window_exceeded":
return handle_context_limit(response)
case "pause_turn":
return handle_pause(response)
case "refusal":
return handle_refusal(response)
case _:
# end_turn 및 기타 경우를 처리합니다
return next(
(block.text for block in response.content if block.type == "text"),
"",
)
```
```typescript TypeScript
function handleResponse(response: Anthropic.Beta.BetaMessage): string {
switch (response.stop_reason) {
case "tool_use":
return handleToolUse(response);
case "max_tokens":
return handleTruncation(response);
case "model_context_window_exceeded":
return handleContextLimit(response);
case "pause_turn":
return handlePause(response);
case "refusal":
return handleRefusal(response);
default: {
// end_turn 및 기타 경우 처리
const textBlock = response.content.find(
(block): block is Anthropic.Beta.BetaTextBlock => block.type === "text"
);
return textBlock?.text ?? "";
}
}
}
```
```csharp C#
static string HandleResponse(BetaMessage response)
{
return response.StopReason?.Value() switch
{
BetaStopReason.ToolUse => HandleToolUse(response),
BetaStopReason.MaxTokens => HandleTruncation(response),
BetaStopReason.ModelContextWindowExceeded => HandleContextLimit(response),
BetaStopReason.PauseTurn => HandlePause(response),
BetaStopReason.Refusal => HandleRefusal(response),
// end_turn 및 기타 경우 처리
_ => response.Content.Select(b => b.Value).OfType().FirstOrDefault()?.Text ?? "",
};
}
```
```go Go
func handleResponse(response *anthropic.BetaMessage) string {
switch response.StopReason {
case anthropic.BetaStopReasonToolUse:
return handleToolUse(response)
case anthropic.BetaStopReasonMaxTokens:
return handleTruncation(response)
case anthropic.BetaStopReasonModelContextWindowExceeded:
return handleContextLimit(response)
case anthropic.BetaStopReasonPauseTurn:
return handlePause(response)
case anthropic.BetaStopReasonRefusal:
return handleRefusal(response)
default:
// end_turn 및 기타 경우 처리
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
return textBlock.Text
}
}
return ""
}
}
```
```java Java
static String handleResponse(BetaMessage response) {
BetaStopReason reason = response.stopReason().orElse(BetaStopReason.END_TURN);
if (reason.equals(BetaStopReason.TOOL_USE)) {
return handleToolUse(response);
} else if (reason.equals(BetaStopReason.MAX_TOKENS)) {
return handleTruncation(response);
} else if (reason.equals(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED)) {
return handleContextLimit(response);
} else if (reason.equals(BetaStopReason.PAUSE_TURN)) {
return handlePause(response);
} else if (reason.equals(BetaStopReason.REFUSAL)) {
return handleRefusal(response);
}
// end_turn 및 기타 경우 처리
return response.content().stream()
.filter(BetaContentBlock::isText)
.findFirst()
.map(block -> block.asText().text())
.orElse("");
}
```
```php PHP
function handle_response($response): string
{
return match ($response->stopReason) {
'tool_use' => handle_tool_use($response),
'max_tokens' => handle_truncation($response),
'model_context_window_exceeded' => handle_context_limit($response),
'pause_turn' => handle_pause($response),
'refusal' => handle_refusal($response),
// end_turn 및 기타 경우 처리
default => array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '',
};
}
```
```ruby Ruby
def handle_response(response)
case response.stop_reason
when :tool_use then handle_tool_use(response)
when :max_tokens then handle_truncation(response)
when :model_context_window_exceeded then handle_context_limit(response)
when :pause_turn then handle_pause(response)
when :refusal then handle_refusal(response)
else
# end_turn 및 기타 경우 처리
response.content.find { it.type == :text }&.text
end
end
```
### 잘린 응답을 우아하게 처리하세요
토큰 한도나 컨텍스트 윈도우 때문에 응답이 잘린 경우, 독자가 출력이 불완전하다는 것을 알 수 있도록 안내 문구를 덧붙이세요. 대신 응답이 끊긴 지점부터 계속 생성하려면 [완전한 응답 보장하기](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#ensuring-complete-responses)를 참조하세요.
```python Python
def handle_truncated_response(response):
text = next((block.text for block in response.content if block.type == "text"), "")
if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
if response.stop_reason == "max_tokens":
note = "[Response truncated due to max_tokens limit]"
else:
note = "[Response truncated due to context window limit]"
return f"{text}\n\n{note}"
return text
```
```typescript TypeScript
function handleTruncatedResponse(response: Anthropic.Beta.BetaMessage): string {
const textBlock = response.content.find(
(block): block is Anthropic.Beta.BetaTextBlock => block.type === "text"
);
const text = textBlock?.text ?? "";
if (
response.stop_reason === "max_tokens" ||
response.stop_reason === "model_context_window_exceeded"
) {
const note =
response.stop_reason === "max_tokens"
? "[Response truncated due to max_tokens limit]"
: "[Response truncated due to context window limit]";
return `${text}\n\n${note}`;
}
return text;
}
```
```csharp C#
static string HandleTruncatedResponse(BetaMessage response)
{
var text = response.Content.Select(b => b.Value).OfType().FirstOrDefault()?.Text ?? "";
var reason = response.StopReason?.Value();
if (reason is BetaStopReason.MaxTokens or BetaStopReason.ModelContextWindowExceeded)
{
var note = reason == BetaStopReason.MaxTokens
? "[Response truncated due to max_tokens limit]"
: "[Response truncated due to context window limit]";
return $"{text}\n\n{note}";
}
return text;
}
```
```go Go
func handleTruncatedResponse(response *anthropic.BetaMessage) string {
text := ""
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
text = textBlock.Text
break
}
}
if response.StopReason == anthropic.BetaStopReasonMaxTokens ||
response.StopReason == anthropic.BetaStopReasonModelContextWindowExceeded {
note := "[Response truncated due to context window limit]"
if response.StopReason == anthropic.BetaStopReasonMaxTokens {
note = "[Response truncated due to max_tokens limit]"
}
return text + "\n\n" + note
}
return text
}
```
```java Java
static String handleTruncatedResponse(BetaMessage response) {
String text = response.content().stream()
.filter(BetaContentBlock::isText)
.findFirst()
.map(block -> block.asText().text())
.orElse("");
BetaStopReason reason = response.stopReason().orElse(BetaStopReason.END_TURN);
if (reason.equals(BetaStopReason.MAX_TOKENS)
|| reason.equals(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED)) {
String note = reason.equals(BetaStopReason.MAX_TOKENS)
? "[Response truncated due to max_tokens limit]"
: "[Response truncated due to context window limit]";
return text + "\n\n" + note;
}
return text;
}
```
```php PHP
function handle_truncated_response($response): string
{
$text = array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '';
if (in_array($response->stopReason, ['max_tokens', 'model_context_window_exceeded'], true)) {
$note = $response->stopReason === 'max_tokens'
? '[Response truncated due to max_tokens limit]'
: '[Response truncated due to context window limit]';
return "{$text}\n\n{$note}";
}
return $text;
}
```
```ruby Ruby
def handle_truncated_response(response)
text = response.content.find { it.type == :text }&.text
if [:max_tokens, :model_context_window_exceeded].include?(response.stop_reason)
note = if response.stop_reason == :max_tokens
"[Response truncated due to max_tokens limit]"
else
"[Response truncated due to context window limit]"
end
return "#{text}\n\n#{note}"
end
text
end
```
### pause\_turn에 대한 재시도 로직을 구현하세요
[서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools)를 사용할 때, 서버 측 샘플링 루프가 반복 한도(기본값 10)에 도달하면 API가 `pause_turn`을 반환할 수 있습니다. 대화를 계속하여 이를 처리하세요:
```python Python
def handle_server_tool_conversation(client, user_query, tools, max_continuations=5):
"""
Handle server tool conversations that may require multiple continuations.
The server runs a sampling loop when executing server tools. If the loop
reaches its iteration limit, the API returns pause_turn. Continue the
conversation by sending the response back to let Claude finish.
"""
messages = [{"role": "user", "content": user_query}]
for _ in range(max_continuations):
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=messages,
tools=tools,
)
if response.stop_reason != "pause_turn":
# Claude가 처리를 완료했습니다 - 최종 응답을 반환합니다
return response
# pause_turn: 역할이 번갈아 나타나도록 전체 메시지 목록을 교체합니다
messages = [
{"role": "user", "content": user_query},
{"role": "assistant", "content": response.content},
]
# 최대 연속 횟수에 도달했습니다 - 마지막 응답을 반환합니다
return response
```
```typescript TypeScript
async function handleServerToolConversation(
client: Anthropic,
userQuery: string,
tools: Anthropic.ToolUnion[],
maxContinuations = 5
): Promise {
let messages: Anthropic.MessageParam[] = [{ role: "user", content: userQuery }];
let response: Anthropic.Message;
for (let i = 0; i < maxContinuations; i++) {
response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
messages,
tools
});
if (response.stop_reason !== "pause_turn") {
// Claude가 처리를 완료했습니다 - 최종 응답을 반환합니다
return response;
}
// pause_turn: 역할이 번갈아 나타나도록 전체 메시지 목록을 교체합니다
messages = [
{ role: "user", content: userQuery },
{ role: "assistant", content: response.content }
];
}
// 최대 연속 횟수에 도달했습니다 - 마지막 응답을 반환합니다
return response!;
}
```
```csharp C#
static async Task HandleServerToolConversation(
AnthropicClient client,
string userQuery,
List tools,
int maxContinuations = 5)
{
List messages = [new() { Role = Role.User, Content = userQuery }];
Message response = null!;
for (var i = 0; i < maxContinuations; i++)
{
response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = messages,
Tools = tools
});
if (response.StopReason != "pause_turn")
{
// Claude가 처리를 완료했습니다 - 최종 응답을 반환합니다
return response;
}
// pause_turn: 역할이 번갈아 나타나도록 전체 메시지 목록을 교체합니다
messages =
[
new() { Role = Role.User, Content = userQuery },
new()
{
Role = Role.Assistant,
Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
}
];
}
// 최대 연속 횟수에 도달했습니다 - 마지막 응답을 반환합니다
return response;
}
```
```go Go
func handleServerToolConversation(
client anthropic.Client,
userQuery string,
tools []anthropic.ToolUnionParam,
maxContinuations int,
) (*anthropic.Message, error) {
messages := []anthropic.MessageParam{anthropic.NewUserMessage(anthropic.NewTextBlock(userQuery))}
var response *anthropic.Message
var err error
for range maxContinuations {
response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: messages,
Tools: tools,
})
if err != nil {
return nil, err
}
if response.StopReason != "pause_turn" {
// Claude가 처리를 완료했습니다 - 최종 응답을 반환합니다
return response, nil
}
// pause_turn: 역할이 번갈아 나타나도록 전체 메시지 목록을 교체합니다
var contentParams []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
contentParams = append(contentParams, block.ToParam())
}
messages = []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(userQuery)),
anthropic.NewAssistantMessage(contentParams...),
}
}
// 최대 연속 횟수에 도달했습니다 - 마지막 응답을 반환합니다
return response, nil
}
```
```java Java
static Message handleServerToolConversation(
AnthropicClient client,
String userQuery,
List tools,
int maxContinuations
) {
Message response = null;
for (int i = 0; i < maxContinuations; i++) {
// 메시지가 누적되지 않도록 반복할 때마다 params를 다시 구성합니다
MessageCreateParams.Builder params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addUserMessage(userQuery);
tools.forEach(params::addTool);
if (response != null) {
params.addMessage(response);
}
response = client.messages().create(params.build());
if (!response.stopReason().map(StopReason.PAUSE_TURN::equals).orElse(false)) {
// Claude가 처리를 완료했습니다 - 최종 응답을 반환합니다
return response;
}
// pause_turn: 루프를 다시 실행하고 응답을 다시 전송합니다
}
// 최대 연속 횟수에 도달했습니다 - 마지막 응답을 반환합니다
return response;
}
```
```php PHP
function handle_server_tool_conversation(
Client $client,
string $userQuery,
array $tools,
int $maxContinuations = 5
) {
$messages = [['role' => 'user', 'content' => $userQuery]];
$response = null;
for ($i = 0; $i < $maxContinuations; $i++) {
$response = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
tools: $tools,
);
if ($response->stopReason !== 'pause_turn') {
// Claude가 처리를 완료했습니다 - 최종 응답을 반환합니다
return $response;
}
// pause_turn: 역할이 번갈아 나타나도록 전체 메시지 목록을 교체합니다
$messages = [
['role' => 'user', 'content' => $userQuery],
['role' => 'assistant', 'content' => $response->content],
];
}
// 최대 연속 횟수에 도달했습니다 - 마지막 응답을 반환합니다
return $response;
}
```
```ruby Ruby
def handle_server_tool_conversation(client, user_query, tools, max_continuations: 5)
messages = [{ role: "user", content: user_query }]
response = nil
max_continuations.times do
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
messages: messages,
tools: tools
)
# Claude가 처리를 완료했습니다 - 최종 응답을 반환합니다
return response unless response.stop_reason == :pause_turn
# pause_turn: 역할이 번갈아 나타나도록 전체 메시지 목록을 교체합니다
messages = [
{ role: "user", content: user_query },
{ role: "assistant", content: response.content }
]
end
# 최대 연속 횟수에 도달했습니다 - 마지막 응답을 반환합니다
response
end
```
## 중지 이유 vs. 오류
`stop_reason` 값과 실제 오류를 구분하는 것이 중요합니다:
### 중지 이유 (성공적인 응답)
* 응답 본문의 일부
* 생성이 정상적으로 중지된 이유를 나타냄
* 응답에 유효한 콘텐츠가 포함됨
### 오류 (실패한 요청)
* HTTP 상태 코드 4xx 또는 5xx
* 요청 처리 실패를 나타냄
* 응답에 오류 세부 정보가 포함됨
```bash cURL
# `--fail-with-body` 옵션을 사용하면 cURL은 HTTP 오류 시 0이 아닌 코드로 종료됩니다. 따라서
# 오류는 $? 값을, 성공한 응답은 stop_reason 값을 확인하세요.
curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello!"}]
}' | jq '.stop_reason'
```
```bash CLI
# CLI는 API 오류 시 0이 아닌 코드로 종료되며, 성공 시에는 stop_reason이 표시됩니다.
ant messages create \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello!"}' \
--format json | jq '.stop_reason'
```
```python Python
client = anthropic.Anthropic()
try:
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
# stop_reason이 포함된 성공 응답을 처리합니다
if response.stop_reason == "max_tokens":
print("Response was truncated")
except anthropic.APIStatusError as e:
# 실제 오류를 처리합니다
match e.status_code:
case 429:
print("Rate limit exceeded")
case 500:
print("Server error")
```
```typescript TypeScript
const client = new Anthropic();
try {
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
});
// stop_reason이 포함된 성공 응답을 처리합니다
if (response.stop_reason === "max_tokens") {
console.log("Response was truncated");
}
} catch (err) {
// 실제 오류를 처리합니다
if (err instanceof Anthropic.APIError) {
switch (err.status) {
case 429:
console.log("Rate limit exceeded");
break;
case 500:
console.log("Server error");
break;
}
} else {
throw err;
}
}
```
```csharp C#
AnthropicClient client = new();
try
{
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello!" }]
});
// stop_reason이 포함된 성공 응답을 처리합니다
if (response.StopReason == "max_tokens")
{
Console.WriteLine("Response was truncated");
}
}
catch (AnthropicRateLimitException)
{
// 실제 오류를 처리합니다
Console.WriteLine("Rate limit exceeded");
}
catch (Anthropic5xxException)
{
Console.WriteLine("Server error");
}
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
},
})
if err != nil {
// 실제 오류를 처리합니다
var apiErr *anthropic.Error
if errors.As(err, &apiErr) {
switch apiErr.StatusCode {
case 429:
fmt.Println("Rate limit exceeded")
case 500:
fmt.Println("Server error")
}
}
log.Fatal(err)
}
// stop_reason이 포함된 성공 응답을 처리합니다
if response.StopReason == "max_tokens" {
fmt.Println("Response was truncated")
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
try {
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("Hello!")
.build()
);
// stop_reason이 포함된 성공 응답을 처리합니다
if (response.stopReason().map(StopReason.MAX_TOKENS::equals).orElse(false)) {
IO.println("Response was truncated");
}
} catch (RateLimitException e) {
// 실제 오류를 처리합니다
IO.println("Rate limit exceeded");
} catch (AnthropicServiceException e) {
if (e.statusCode() == 500) {
IO.println("Server error");
}
}
```
```php PHP
$client = new Client();
try {
$response = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello!']],
model: 'claude-opus-5-5',
);
// stop_reason이 포함된 성공 응답을 처리합니다
if ($response->stopReason === 'max_tokens') {
echo 'Response was truncated', PHP_EOL;
}
} catch (RateLimitException $e) {
// 실제 오류를 처리합니다
echo 'Rate limit exceeded', PHP_EOL;
} catch (InternalServerException $e) {
echo 'Server error', PHP_EOL;
}
```
```ruby Ruby
client = Anthropic::Client.new
begin
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
)
# stop_reason이 포함된 성공 응답을 처리합니다
if response.stop_reason == :max_tokens
puts "Response was truncated"
end
rescue Anthropic::Errors::RateLimitError
# 실제 오류를 처리합니다
puts "Rate limit exceeded"
rescue Anthropic::Errors::APIStatusError => e
puts "Server error" if e.status == 500
end
```
## 스트리밍 고려 사항
스트리밍을 사용할 때 `stop_reason`은:
* 초기 `message_start` 이벤트에서는 `null`
* `message_delta` 이벤트에서 제공됨
* 다른 어떤 이벤트에서도 제공되지 않음
```bash cURL
# SSE 스트림의 message_delta 이벤트에 stop_reason이 포함됩니다.
curl --no-buffer https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"stream": true,
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```bash CLI
# stop_reason 은 message_delta 이벤트에 나타납니다.
ant messages create --stream --format jsonl \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello!"}' |
jq -c 'select(.type == "message_delta") | .delta.stop_reason'
```
```python Python
client = anthropic.Anthropic()
with client.messages.stream(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
) as stream:
for event in stream:
if event.type == "message_delta":
stop_reason = event.delta.stop_reason
if stop_reason:
print(f"Stream ended with: {stop_reason}")
```
```typescript TypeScript
const client = new Anthropic();
const stream = client.messages.stream({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
});
for await (const event of stream) {
if (event.type === "message_delta" && event.delta.stop_reason) {
console.log(`Stream ended with: ${event.delta.stop_reason}`);
}
}
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello!" }]
};
await foreach (var streamEvent in client.Messages.CreateStreaming(parameters))
{
switch (streamEvent.Value)
{
case RawMessageDeltaEvent deltaEvent when deltaEvent.Delta.StopReason is not null:
Console.WriteLine($"Stream ended with: {deltaEvent.Delta.StopReason}");
break;
}
}
```
```go Go
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
},
})
// 이벤트를 누적하여 stop_reason을 포함하는 최종 Message를 만듭니다.
message := anthropic.Message{}
for stream.Next() {
if err := message.Accumulate(stream.Current()); err != nil {
log.Fatal(err)
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
if message.StopReason != "" {
fmt.Printf("Stream ended with: %s\n", message.StopReason)
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("Hello!")
.build();
// 이벤트를 누적하여 stop_reason을 포함하는 최종 Message를 만듭니다.
MessageAccumulator accumulator = MessageAccumulator.create();
try (StreamResponse streamResponse =
client.messages().createStreaming(params)) {
streamResponse.stream().forEach(accumulator::accumulate);
}
accumulator.message().stopReason().ifPresent(stopReason ->
IO.println("Stream ended with: " + stopReason)
);
```
```php PHP
$client = new Client();
$stream = $client->messages->createStream(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello!']],
model: 'claude-opus-5-5',
);
foreach ($stream as $event) {
if ($event instanceof \Anthropic\Messages\RawMessageDeltaEvent && $event->delta->stopReason !== null) {
echo "Stream ended with: {$event->delta->stopReason}", PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
stream = client.messages.stream(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
)
stream.each do |event|
next unless event.type == :message_delta
stop_reason = event.delta.stop_reason
puts "Stream ended with: #{stop_reason}" if stop_reason
end
```
## 일반적인 패턴
### 도구 사용 워크플로 처리하기
**tool runner로 더 간단하게:** 다음 예제는 수동 도구 처리를 보여줍니다. 대부분의 사용 사례에서는 [tool runner](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-runner)가 훨씬 적은 코드로 도구 실행을 자동으로 처리합니다.
```python Python
def complete_tool_workflow(client, user_query, tools):
messages = [{"role": "user", "content": user_query}]
while True:
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=messages,
tools=tools,
)
if response.stop_reason == "tool_use":
# 도구를 실행하고 계속 진행합니다
tool_results = execute_tools(response.content)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
else:
# 최종 응답
return response
```
```typescript TypeScript
async function completeToolWorkflow(
client: Anthropic,
userQuery: string,
tools: Anthropic.ToolUnion[]
): Promise {
const messages: Anthropic.MessageParam[] = [{ role: "user", content: userQuery }];
while (true) {
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages,
tools
});
if (response.stop_reason === "tool_use") {
// 도구를 실행하고 계속 진행합니다
const toolResults = executeTools(response.content);
messages.push({ role: "assistant", content: response.content });
messages.push({ role: "user", content: toolResults });
} else {
// 최종 응답
return response;
}
}
}
```
```csharp C#
static async Task CompleteToolWorkflow(
AnthropicClient client,
string userQuery,
List tools)
{
List messages = [new() { Role = Role.User, Content = userQuery }];
while (true)
{
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = messages,
Tools = tools
});
if (response.StopReason == "tool_use")
{
// 도구를 실행하고 계속 진행합니다
var toolResults = ExecuteTools(response.Content);
messages.Add(new()
{
Role = Role.Assistant,
Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
});
messages.Add(new() { Role = Role.User, Content = toolResults });
}
else
{
// 최종 응답
return response;
}
}
}
```
```go Go
func completeToolWorkflow(
client anthropic.Client,
userQuery string,
tools []anthropic.ToolUnionParam,
) (*anthropic.Message, error) {
messages := []anthropic.MessageParam{anthropic.NewUserMessage(anthropic.NewTextBlock(userQuery))}
for {
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
Tools: tools,
})
if err != nil {
return nil, err
}
if response.StopReason != "tool_use" {
// 최종 응답
return response, nil
}
// 도구를 실행하고 계속 진행합니다
toolResults := executeTools(response.Content)
var contentParams []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
contentParams = append(contentParams, block.ToParam())
}
messages = append(messages, anthropic.NewAssistantMessage(contentParams...))
messages = append(messages, anthropic.NewUserMessage(toolResults...))
}
}
```
```java Java
static Message completeToolWorkflow(
AnthropicClient client,
String userQuery,
List tools
) {
List messages = new ArrayList<>();
messages.add(MessageParam.builder().role(MessageParam.Role.USER).content(userQuery).build());
while (true) {
MessageCreateParams.Builder params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.messages(messages);
tools.forEach(params::addTool);
Message response = client.messages().create(params.build());
if (!response.stopReason().map(StopReason.TOOL_USE::equals).orElse(false)) {
// 최종 응답
return response;
}
// 도구를 실행하고 계속 진행합니다
List toolResults = executeTools(response.content());
messages.add(response.toParam());
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(toolResults.stream().map(ContentBlockParam::ofToolResult).toList())
.build());
}
}
```
```php PHP
function complete_tool_workflow(Client $client, string $userQuery, array $tools)
{
$messages = [['role' => 'user', 'content' => $userQuery]];
while (true) {
$response = $client->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-opus-5-5',
tools: $tools,
);
if ($response->stopReason !== 'tool_use') {
// 최종 응답
return $response;
}
// 도구를 실행하고 계속 진행합니다
$toolResults = execute_tools($response->content);
$messages[] = ['role' => 'assistant', 'content' => $response->content];
$messages[] = ['role' => 'user', 'content' => $toolResults];
}
}
```
```ruby Ruby
def complete_tool_workflow(client, user_query, tools)
messages = [{ role: "user", content: user_query }]
loop do
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: messages,
tools: tools
)
# 최종 응답
return response unless response.stop_reason == :tool_use
# 도구를 실행하고 계속 진행합니다
tool_results = execute_tools(response.content)
messages << { role: "assistant", content: response.content }
messages << { role: "user", content: tool_results }
end
end
```
### 완전한 응답 보장하기
```python Python
def get_complete_response(client, prompt, max_attempts=3):
messages = [{"role": "user", "content": prompt}]
full_response = ""
for _ in range(max_attempts):
response = client.messages.create(
model="claude-opus-5-5", messages=messages, max_tokens=4096
)
full_response += next(
(block.text for block in response.content if block.type == "text"), ""
)
if response.stop_reason != "max_tokens":
break
# 중단된 지점부터 이어서 계속합니다
messages = [
{"role": "user", "content": prompt},
{"role": "assistant", "content": full_response},
{"role": "user", "content": "Please continue from where you left off."},
]
return full_response
```
```typescript TypeScript
async function getCompleteResponse(
client: Anthropic,
prompt: string,
maxAttempts = 3
): Promise {
let messages: Anthropic.MessageParam[] = [{ role: "user", content: prompt }];
let fullResponse = "";
for (let i = 0; i < maxAttempts; i++) {
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
messages
});
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
fullResponse += textBlock?.text ?? "";
if (response.stop_reason !== "max_tokens") {
break;
}
// 중단된 지점부터 이어서 진행합니다
messages = [
{ role: "user", content: prompt },
{ role: "assistant", content: fullResponse },
{ role: "user", content: "Please continue from where you left off." }
];
}
return fullResponse;
}
```
```csharp C#
static async Task GetCompleteResponse(AnthropicClient client, string prompt, int maxAttempts = 3)
{
List messages = [new() { Role = Role.User, Content = prompt }];
var fullResponse = "";
for (var i = 0; i < maxAttempts; i++)
{
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = messages
});
foreach (var block in response.Content)
{
if (block.TryPickText(out var textBlock))
{
fullResponse += textBlock.Text;
break;
}
}
if (response.StopReason != "max_tokens")
{
break;
}
// 중단된 지점부터 계속합니다
messages =
[
new() { Role = Role.User, Content = prompt },
new() { Role = Role.Assistant, Content = fullResponse },
new() { Role = Role.User, Content = "Please continue from where you left off." }
];
}
return fullResponse;
}
```
```go Go
func getCompleteResponse(client anthropic.Client, prompt string, maxAttempts int) (string, error) {
messages := []anthropic.MessageParam{anthropic.NewUserMessage(anthropic.NewTextBlock(prompt))}
fullResponse := ""
for range maxAttempts {
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: messages,
})
if err != nil {
return "", err
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fullResponse += textBlock.Text
break
}
}
if response.StopReason != "max_tokens" {
break
}
// 중단된 지점부터 이어서 진행합니다
messages = []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(prompt)),
anthropic.NewAssistantMessage(anthropic.NewTextBlock(fullResponse)),
anthropic.NewUserMessage(anthropic.NewTextBlock("Please continue from where you left off.")),
}
}
return fullResponse, nil
}
```
```java Java
static String getCompleteResponse(AnthropicClient client, String prompt, int maxAttempts) {
List messages = List.of(
MessageParam.builder().role(MessageParam.Role.USER).content(prompt).build()
);
StringBuilder fullResponse = new StringBuilder();
for (int i = 0; i < maxAttempts; i++) {
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.messages(messages)
.build()
);
response.content().stream()
.filter(ContentBlock::isText)
.findFirst()
.ifPresent(block -> fullResponse.append(block.asText().text()));
if (!response.stopReason().map(StopReason.MAX_TOKENS::equals).orElse(false)) {
break;
}
// 중단된 지점부터 이어서 진행합니다
messages = List.of(
MessageParam.builder().role(MessageParam.Role.USER).content(prompt).build(),
MessageParam.builder().role(MessageParam.Role.ASSISTANT).content(fullResponse.toString()).build(),
MessageParam.builder().role(MessageParam.Role.USER).content("Please continue from where you left off.").build()
);
}
return fullResponse.toString();
}
```
```php PHP
function get_complete_response(Client $client, string $prompt, int $maxAttempts = 3): string
{
$messages = [['role' => 'user', 'content' => $prompt]];
$fullResponse = '';
for ($i = 0; $i < $maxAttempts; $i++) {
$response = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
);
$fullResponse .= array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '';
if ($response->stopReason !== 'max_tokens') {
break;
}
// 중단된 지점부터 계속합니다
$messages = [
['role' => 'user', 'content' => $prompt],
['role' => 'assistant', 'content' => $fullResponse],
['role' => 'user', 'content' => 'Please continue from where you left off.'],
];
}
return $fullResponse;
}
```
```ruby Ruby
def get_complete_response(client, prompt, max_attempts: 3)
messages = [{ role: "user", content: prompt }]
full_response = +""
max_attempts.times do
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
messages: messages
)
full_response << response.content.find { it.type == :text }&.text.to_s
break unless response.stop_reason == :max_tokens
# 중단된 지점부터 이어서 계속합니다
messages = [
{ role: "user", content: prompt },
{ role: "assistant", content: full_response },
{ role: "user", content: "Please continue from where you left off." }
]
end
full_response
end
```
### 입력 크기를 모르는 상태에서 최대 토큰 얻기
`model_context_window_exceeded` 중지 이유를 사용하면 입력 크기를 계산하지 않고도 가능한 최대 토큰을 요청할 수 있습니다:
```python Python
def get_max_possible_tokens(client, prompt):
"""
Get as many tokens as possible within the model's context window
without needing to calculate input token count
"""
response = client.beta.messages.create(
model="claude-opus-5-5",
messages=[{"role": "user", "content": prompt}],
max_tokens=20000, # Python SDK requires streaming for max_tokens above ~21k
)
match response.stop_reason:
case "model_context_window_exceeded":
# 입력 크기를 고려해 가능한 최대 토큰 수를 받았습니다
print(
f"Generated {response.usage.output_tokens} tokens (context limit reached)"
)
case "max_tokens":
# 요청한 토큰 수를 정확히 받았습니다
print(
f"Generated {response.usage.output_tokens} tokens (max_tokens reached)"
)
case _:
# 자연스러운 완료
print(
f"Generated {response.usage.output_tokens} tokens (natural completion)"
)
return next((block.text for block in response.content if block.type == "text"), "")
```
```typescript TypeScript
async function getMaxPossibleTokens(client: Anthropic, prompt: string): Promise {
const response = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 20000,
messages: [{ role: "user", content: prompt }]
});
const tokens = response.usage.output_tokens;
switch (response.stop_reason) {
case "model_context_window_exceeded":
// 입력 크기를 고려해 가능한 최대 토큰 수를 받았습니다
console.log(`Generated ${tokens} tokens (context limit reached)`);
break;
case "max_tokens":
// 요청한 토큰 수를 정확히 받았습니다
console.log(`Generated ${tokens} tokens (max_tokens reached)`);
break;
default:
// 자연스럽게 완료되었습니다
console.log(`Generated ${tokens} tokens (natural completion)`);
}
const textBlock = response.content.find(
(block): block is Anthropic.Beta.BetaTextBlock => block.type === "text"
);
return textBlock?.text ?? "";
}
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Model = Anthropic.Models.Messages.Model;
static async Task GetMaxPossibleTokens(AnthropicClient client, string prompt)
{
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 20000,
Messages = [new() { Role = Role.User, Content = prompt }]
});
var tokens = response.Usage.OutputTokens;
var reason = response.StopReason?.Value();
if (reason == BetaStopReason.ModelContextWindowExceeded)
{
// 입력 크기를 고려할 때 가능한 최대 토큰 수를 받았습니다
Console.WriteLine($"Generated {tokens} tokens (context limit reached)");
}
else if (reason == BetaStopReason.MaxTokens)
{
// 요청한 토큰 수를 정확히 받았습니다
Console.WriteLine($"Generated {tokens} tokens (max_tokens reached)");
}
else
{
// 자연스러운 완료
Console.WriteLine($"Generated {tokens} tokens (natural completion)");
}
return response.Content.Select(b => b.Value).OfType().FirstOrDefault()?.Text ?? "";
}
```
```go Go
func getMaxPossibleTokens(client anthropic.Client, prompt string) (string, error) {
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 20000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(prompt)),
},
})
if err != nil {
return "", err
}
tokens := response.Usage.OutputTokens
switch response.StopReason {
case anthropic.BetaStopReasonModelContextWindowExceeded:
// 입력 크기를 고려해 가능한 최대 토큰 수를 받았습니다
fmt.Printf("Generated %d tokens (context limit reached)\n", tokens)
case anthropic.BetaStopReasonMaxTokens:
// 요청한 토큰 수를 정확히 받았습니다
fmt.Printf("Generated %d tokens (max_tokens reached)\n", tokens)
default:
// 자연스럽게 완료되었습니다
fmt.Printf("Generated %d tokens (natural completion)\n", tokens)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
return textBlock.Text, nil
}
}
return "", nil
}
```
```java Java
import com.anthropic.models.beta.messages.BetaContentBlock;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaStopReason;
import com.anthropic.models.beta.messages.MessageCreateParams;
static String getMaxPossibleTokens(AnthropicClient client, String prompt) {
BetaMessage response = client.beta().messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(20000L)
.addUserMessage(prompt)
.build()
);
long tokens = response.usage().outputTokens();
BetaStopReason reason = response.stopReason().orElse(BetaStopReason.END_TURN);
if (reason.equals(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED)) {
// 입력 크기를 고려할 때 가능한 최대 토큰 수를 받았습니다
IO.println("Generated " + tokens + " tokens (context limit reached)");
} else if (reason.equals(BetaStopReason.MAX_TOKENS)) {
// 요청한 토큰 수를 정확히 받았습니다
IO.println("Generated " + tokens + " tokens (max_tokens reached)");
} else {
// 자연스러운 완료
IO.println("Generated " + tokens + " tokens (natural completion)");
}
return response.content().stream()
.filter(BetaContentBlock::isText)
.findFirst()
.map(block -> block.asText().text())
.orElse("");
}
```
```php PHP
function get_max_possible_tokens(Client $client, string $prompt): string
{
$response = $client->beta->messages->create(
maxTokens: 20000,
messages: [['role' => 'user', 'content' => $prompt]],
model: 'claude-opus-5-5',
);
$tokens = $response->usage->outputTokens;
echo match ($response->stopReason) {
// 입력 크기를 고려해 가능한 최대 토큰 수를 받았습니다
'model_context_window_exceeded' => "Generated {$tokens} tokens (context limit reached)",
// 요청한 토큰 수를 정확히 받았습니다
'max_tokens' => "Generated {$tokens} tokens (max_tokens reached)",
// 자연스러운 완료
default => "Generated {$tokens} tokens (natural completion)",
}, PHP_EOL;
return array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '';
}
```
```ruby Ruby
def get_max_possible_tokens(client, prompt)
response = client.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 20000,
messages: [{ role: "user", content: prompt }]
)
tokens = response.usage.output_tokens
case response.stop_reason
when :model_context_window_exceeded
# 입력 크기를 고려해 가능한 최대 토큰 수를 받았습니다
puts "Generated #{tokens} tokens (context limit reached)"
when :max_tokens
# 요청한 토큰 수를 정확히 받았습니다
puts "Generated #{tokens} tokens (max_tokens reached)"
else
# 자연스러운 완료
puts "Generated #{tokens} tokens (natural completion)"
end
response.content.find { it.type == :text }.text
end
```
## 다음 단계
거부된 요청을 서버 측 또는 클라이언트에서 폴백 모델로 재시도하세요.
SDK가 `tool_use` 루프, 결과 포맷팅, 재시도를 대신 관리하도록 하세요.
스트리밍 시 `message_delta` 이벤트에서 `stop_reason`을 읽으세요.
중지 이유와는 구별되는 4xx 및 5xx HTTP 오류를 처리하세요.