---
title: 세션 이벤트 스트림
url: https://platform.claude.com/docs/ko/managed-agents/events-and-streaming
description: 이벤트를 전송하고, 응답을 스트리밍하며, 실행 중인 세션을 중단하거나 방향을 바꿉니다.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: 자체 호스팅 Managed Agents를 제외하고 ZDR 적격 대상이 아닙니다. 세션은 상태를 유지하는 리소스이며, 트랜스크립트는 삭제할 때까지 유지됩니다.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
    Claude Models on Google Cloud (Anthropic managed): beta
---

Claude Managed Agents와의 통신은 이벤트 기반입니다. 세션을 추적하려면 스트림을 열고, 세션을 지시하려면 이벤트를 전송하며, 세션이 입력을 기다리며 일시 중지되면 응답합니다.

## 이벤트 유형

이벤트는 두 방향으로 흐릅니다. 사용자가 에이전트에 이벤트를 전송하고, 세션은 사용자에게 이벤트를 다시 전송합니다.

* **전송하는 이벤트:** `user.*` 이벤트는 세션을 시작하고 진행 중인 세션을 조정합니다. [`system.message`](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#send-system-messages) 이벤트는 시스템 수준 컨텍스트를 추가합니다.
* **수신하는 이벤트:** 세션 이벤트, span 이벤트, 에이전트 이벤트는 세션의 상태와 에이전트의 진행 상황을 보고합니다.

이러한 이벤트 유형 문자열은 `{domain}.{action}` 명명 규칙을 따릅니다. 전체 목록은 레퍼런스의 [이벤트 유형](https://platform.claude.com/docs/ko/managed-agents/reference#event-types)을 참조하세요.

[Webhook 이벤트 유형](https://platform.claude.com/docs/ko/managed-agents/webhooks#supported-event-types)은 별개이며, 일부 이름은 스트림의 이름과 다릅니다. 예를 들어 webhook은 `session.status_idle` 대신 `session.status_idled`를 사용합니다.

## 이벤트 스트리밍

에이전트가 작업하는 동안 실시간 업데이트를 받으려면 세션에서 이벤트를 스트리밍하세요. 스트림은 열린 이후에 발생한 이벤트만 전달하므로, 경쟁 조건(race condition)을 피하려면 이벤트를 전송하기 전에 스트림을 여세요.

<CodeGroup>
  ```bash cURL
  # 첫 이벤트를 전송하기 전에 스트림을 여세요. 이후 이벤트만 전달됩니다.
  curl --fail-with-body -sS -N \
    "https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "accept: text/event-stream"
  ```

  ```bash CLI
  # 첫 이벤트를 전송하기 전에 스트림을 여세요. 이후 이벤트만 전달됩니다.
  ant beta:sessions:events stream --session-id "$SESSION_ID"
  ```

  ```python Python
  # 먼저 스트림을 연 다음 사용자 메시지를 보냅니다
  with client.beta.sessions.events.stream(session.id) as stream:
      client.beta.sessions.events.send(
          session.id,
          events=[
              {
                  "type": "user.message",
                  "content": [{"type": "text", "text": "Summarize the repo README"}],
              },
          ],
      )

      for event in stream:
          match event.type:
              case "agent.message":
                  for block in event.content:
                      if block.type == "text":
                          print(block.text, end="")
              case "session.status_idle":
                  break
              case "session.error":
                  error_message = event.error.message if event.error else "unknown"
                  print(f"\n[Error: {error_message}]")
                  break
  ```

  ```typescript TypeScript
  // 먼저 스트림을 연 다음 사용자 메시지를 보냅니다
  const stream = await client.beta.sessions.events.stream(session.id);
  await client.beta.sessions.events.send(session.id, {
    events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "Summarize the repo README" }]
      }
    ]
  });

  events: for await (const event of stream) {
    switch (event.type) {
      case "agent.message":
        for (const block of event.content) {
          if (block.type === "text") {
            process.stdout.write(block.text);
          }
        }
        break;
      case "session.status_idle":
        break events;
      case "session.error":
        console.log(`\n[Error: ${event.error?.message ?? "unknown"}]`);
        break events;
    }
  }
  ```

  ```csharp C#
  // 먼저 스트림을 연 다음 사용자 메시지를 보냅니다
  using var stream = await client.Beta.Sessions.Events.WithRawResponse.StreamStreaming(session.ID);
  await client.Beta.Sessions.Events.Send(session.ID, new()
  {
      Events =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Content = [new BetaManagedAgentsTextBlock { Text = "Summarize the repo README" }],
          },
      ],
  });

  await foreach (var streamEvent in stream.Enumerate())
  {
      if (streamEvent.Value is BetaManagedAgentsAgentMessageEvent message)
      {
          foreach (var block in message.Content)
          {
              if (block.Value is BetaManagedAgentsTextBlock textBlock)
              {
                  Console.Write(textBlock.Text);
              }
          }
      }
      else if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent)
      {
          break;
      }
      else if (streamEvent.Value is BetaManagedAgentsSessionErrorEvent error)
      {
          Console.WriteLine($"\n[Error: {error.Error?.Message ?? "unknown"}]");
          break;
      }
  }
  ```

  ```go Go
  	// 먼저 스트림을 연 다음 사용자 메시지를 보냅니다
  	stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
  	defer stream.Close()

  	if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  		Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  			OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  				Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  					OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  						Text: "Summarize the repo README",
  					},
  				}},
  			},
  		}},
  	}); err != nil {
  		panic(err)
  	}

  events:
  	for stream.Next() {
  		switch event := stream.Current().AsAny().(type) {
  		case anthropic.BetaManagedAgentsAgentMessageEvent:
  			// 구체 타입 목록: BetaManagedAgentsTextBlock
  			for _, block := range event.Content {
  				fmt.Print(block.Text)
  			}
  		case anthropic.BetaManagedAgentsSessionStatusIdleEvent:
  			break events
  		case anthropic.BetaManagedAgentsSessionErrorEvent:
  			fmt.Printf("\n[Error: %s]\n", cmp.Or(event.Error.Message, "unknown"))
  			break events
  		}
  	}
  	if err := stream.Err(); err != nil {
  		panic(err)
  	}
  ```

  ```java Java
  // 먼저 스트림을 연 다음 사용자 메시지를 보냅니다
  try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
      client.beta().sessions().events().send(
          session.id(),
          EventSendParams.builder()
              .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
                  .addTextContent("Summarize the repo README")
                  .build())
              .build()
      );

      events:
      for (var event : stream) {
          switch (event.type().value()) {
              case AGENT_MESSAGE -> event.asAgentMessage().content().forEach(block -> block.text().ifPresent(textBlock -> IO.print(textBlock.text())));
              case SESSION_STATUS_IDLE -> {
                  break events;
              }
              case SESSION_ERROR -> {
                  IO.println("\n[Error: " + event.asSessionError().error().message() + "]");
                  break events;
              }
          }
      }
  }
  ```

  ```php PHP
  use Anthropic\Beta\Sessions\Events\ManagedAgentsAgentMessageEvent;
  use Anthropic\Beta\Sessions\Events\ManagedAgentsSessionErrorEvent;
  use Anthropic\Beta\Sessions\Events\ManagedAgentsTextBlock;

  // 먼저 스트림을 연 다음 사용자 메시지를 보냅니다
  $stream = $client->beta->sessions->events->streamStream($session->id);
  $client->beta->sessions->events->send(
      $session->id,
      events: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'Summarize the repo README']],
          ],
      ],
  );

  foreach ($stream as $event) {
      match (true) {
          $event instanceof ManagedAgentsAgentMessageEvent => array_walk(
              $event->content,
              static fn ($block) => $block instanceof ManagedAgentsTextBlock ? print($block->text) : null,
          ),
          $event instanceof ManagedAgentsSessionErrorEvent => printf("\n[Error: %s]", $event->error?->message ?? 'unknown'),
          default => null,
      };
      if ($event->type === 'session.status_idle' || $event->type === 'session.error') {
          break;
      }
  }
  $stream->close();
  ```

  ```ruby Ruby
  # 먼저 스트림을 연 다음 사용자 메시지를 보냅니다
  stream = client.beta.sessions.events.stream_events(session.id)

  client.beta.sessions.events.send_(
    session.id,
    events: [{
      type: "user.message",
      content: [{type: "text", text: "Summarize the repo README"}]
    }]
  )

  stream.each do |event|
    case event
    when Anthropic::Beta::Sessions::BetaManagedAgentsAgentMessageEvent
      event.content.each { print it.text }
    when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusIdleEvent
      break
    when Anthropic::Beta::Sessions::BetaManagedAgentsSessionErrorEvent
      puts "\n[Error: #{event.error&.message || "unknown"}]"
      break
    else
      # 다른 이벤트 유형은 무시합니다
    end
  end
  ```
</CodeGroup>

세션은 `session.error` 이벤트를 통해 오류를 보고합니다. 해당 필드는 [이벤트 유형](https://platform.claude.com/docs/ko/managed-agents/reference#event-types)을 참조하세요.

에이전트의 응답 텍스트는 버퍼링된 `agent.message` 이벤트로 도착하며, 각 이벤트는 이를 생성한 모델 요청이 완료된 후에만 발생합니다. 모델이 아직 텍스트를 생성하는 중에 텍스트를 렌더링하려면 [이벤트 델타로 응답 미리보기](https://platform.claude.com/docs/ko/managed-agents/event-deltas)를 참조하세요.

### 이벤트 누락 없이 재연결하기

이벤트를 놓치지 않고 기존 세션에 재연결하려면 새 스트림과 이벤트 기록을 결합하세요.

1. 새 스트림을 엽니다.
2. [전체 이벤트 기록을 조회](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#list-past-events)하여 이미 확인한 이벤트 ID 집합을 초기화합니다.
3. 라이브 스트림을 추적하면서 기록 목록에서 이미 반환된 이벤트는 건너뜁니다.

<CodeGroup exclude="shell:cURL, shell:CLI">
  <CodeGroupItem language="cURL">
    이 워크플로에는 단일 셸 명령보다 더 많은 로직이 필요합니다. 실행하려면 [Anthropic SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)를 사용하세요.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    이 워크플로에는 단일 셸 명령보다 더 많은 로직이 필요합니다. 실행하려면 [Anthropic SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)를 사용하세요.
  </CodeGroupItem>

  ```python Python
  with client.beta.sessions.events.stream(session.id) as stream:
      # 스트림이 열려 버퍼링 중입니다. 라이브 추적 전에 기록을 조회합니다.
      history = client.beta.sessions.events.list(session.id)
      seen_event_ids = {past_event.id for past_event in history}

      # 이미 본 이벤트는 건너뛰고 라이브 이벤트를 추적합니다
      for event in stream:
          if event.type == "event_start" or event.type == "event_delta":
              # 이 연결에서는 델타 미리보기가 활성화되어 있지 않습니다.
              continue
          if event.id in seen_event_ids:
              continue
          seen_event_ids.add(event.id)
          match event.type:
              case "agent.message":
                  for block in event.content:
                      if block.type == "text":
                          print(block.text, end="")
              case "session.status_idle":
                  break
  ```

  ```typescript TypeScript
  const seenEventIds = new Set<string>();
  const stream = await client.beta.sessions.events.stream(session.id);

  // 스트림이 열려 버퍼링 중입니다. 라이브 추적 전에 기록을 조회합니다.
  for await (const event of client.beta.sessions.events.list(session.id)) {
    seenEventIds.add(event.id);
  }

  // 이미 본 항목은 건너뛰고 라이브 이벤트를 추적합니다
  tail: for await (const event of stream) {
    // 미리보기 이벤트(event_start/event_delta)에는 최상위 `id`가 없습니다
    if (event.type === "event_start" || event.type === "event_delta") {
      continue;
    }
    if (seenEventIds.has(event.id)) {
      continue;
    }
    seenEventIds.add(event.id);
    switch (event.type) {
      case "agent.message":
        for (const block of event.content) {
          if (block.type === "text") {
            process.stdout.write(block.text);
          }
        }
        break;
      case "session.status_idle":
        break tail;
    }
  }
  ```

  ```csharp C#
  using var stream = await client.Beta.Sessions.Events.WithRawResponse.StreamStreaming(session.ID);

  // 스트림이 열려 버퍼링 중입니다. 라이브 추적 전에 기록을 조회합니다.
  HashSet<string> seenEventIds = [];
  var history = await client.Beta.Sessions.Events.List(session.ID);
  await foreach (var pastEvent in history.Paginate())
  {
      seenEventIds.Add(pastEvent.ID);
  }

  // 이미 본 이벤트는 건너뛰고 라이브 이벤트를 추적합니다
  await foreach (var streamEvent in stream.Enumerate())
  {
      if (!seenEventIds.Add(streamEvent.ID))
      {
          continue;
      }
      if (streamEvent.Value is BetaManagedAgentsAgentMessageEvent message)
      {
          foreach (var block in message.Content)
          {
              if (block.Value is BetaManagedAgentsTextBlock textBlock)
              {
                  Console.Write(textBlock.Text);
              }
          }
      }
      else if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent)
      {
          break;
      }
  }
  ```

  ```go Go
  	stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
  	defer stream.Close()

  	// 스트림이 열려 버퍼링 중입니다. 라이브 추적 전에 기록을 조회합니다.
  	seenEventIDs := map[string]struct{}{}
  	history := client.Beta.Sessions.Events.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionEventListParams{})
  	for history.Next() {
  		seenEventIDs[history.Current().ID] = struct{}{}
  	}
  	if err := history.Err(); err != nil {
  		panic(err)
  	}

  	// 이미 본 항목은 건너뛰고 라이브 이벤트를 추적합니다
  tail:
  	for stream.Next() {
  		event := stream.Current()
  		if _, seen := seenEventIDs[event.ID]; seen {
  			continue
  		}
  		seenEventIDs[event.ID] = struct{}{}
  		switch event := event.AsAny().(type) {
  		case anthropic.BetaManagedAgentsAgentMessageEvent:
  			// 구체 타입 목록: BetaManagedAgentsTextBlock
  			for _, block := range event.Content {
  				fmt.Print(block.Text)
  			}
  		case anthropic.BetaManagedAgentsSessionStatusIdleEvent:
  			break tail
  		}
  	}
  	if err := stream.Err(); err != nil {
  		panic(err)
  	}
  ```

  ```java Java
  try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
      // 스트림이 열려 버퍼링 중입니다. 라이브 추적 전에 기록을 나열합니다.
      var seenEventIds = new HashSet<String>();
      for (var pastEvent : client.beta().sessions().events().list(session.id()).autoPager()) {
          seenEventIds.add(pastEvent.id());
      }

      // 라이브 이벤트를 추적합니다. 이미 본 ID는 Set.add가 false를 반환하므로 재생을 건너뜁니다.
      stream.stream()
          .filter(event -> event.id().map(seenEventIds::add).orElse(true))
          .takeWhile(event -> !event.isSessionStatusIdle())
          .filter(BetaManagedAgentsStreamSessionEvents::isAgentMessage)
          .forEach(event -> event.asAgentMessage().content()
              .forEach(block -> block.text().ifPresent(textBlock -> IO.print(textBlock.text()))));
  }
  ```

  ```php PHP
  use Anthropic\Beta\Sessions\Events\ManagedAgentsAgentMessageEvent;
  use Anthropic\Beta\Sessions\Events\ManagedAgentsTextBlock;

  $stream = $client->beta->sessions->events->streamStream($session->id);

  // 스트림이 열려 버퍼링 중입니다. 라이브 이벤트를 추적하기 전에 기록을 조회합니다.
  $seenEventIds = [];
  foreach ($client->beta->sessions->events->list($session->id)->pagingEachItem() as $event) {
      $seenEventIds[$event->id] = true;
  }

  // 이미 본 이벤트는 건너뛰고 라이브 이벤트를 추적합니다
  foreach ($stream as $event) {
      if (isset($seenEventIds[$event->id])) {
          continue;
      }
      $seenEventIds[$event->id] = true;
      match (true) {
          $event instanceof ManagedAgentsAgentMessageEvent => array_walk(
              $event->content,
              static fn ($block) => $block instanceof ManagedAgentsTextBlock ? print($block->text) : null,
          ),
          default => null,
      };
      if ($event->type === 'session.status_idle') {
          break;
      }
  }
  $stream->close();
  ```

  ```ruby Ruby
  stream = client.beta.sessions.events.stream_events(session.id)

  # 스트림이 열려 버퍼링 중입니다. 라이브 추적 전에 기록을 조회합니다.
  seen_event_ids = Set.new
  client.beta.sessions.events.list(session.id).auto_paging_each { seen_event_ids << it.id }

  # 라이브 이벤트를 추적하며 이미 본 항목은 건너뜁니다(Set#add?는 중복 시 nil 반환)
  stream.each do |event|
    next unless seen_event_ids.add?(event.id)
    case event
    when Anthropic::Beta::Sessions::BetaManagedAgentsAgentMessageEvent
      event.content.each { print it.text }
    when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusIdleEvent
      break
    else
      # 다른 이벤트 유형은 무시합니다
    end
  end
  ```
</CodeGroup>

## 이벤트 전송

에이전트의 작업을 시작하거나 계속하려면 `user.message` 이벤트를 전송하세요.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "events": [
        {
          "type": "user.message",
          "content": [
            {"type": "text", "text": "Analyze the performance of the sort function in utils.py"}
          ]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML'
  events:
    - type: user.message
      content:
        - type: text
          text: Analyze the performance of the sort function in utils.py
  YAML
  ```

  ```python Python
  client.beta.sessions.events.send(
      session.id,
      events=[
          {
              "type": "user.message",
              "content": [
                  {
                      "type": "text",
                      "text": "Analyze the performance of the sort function in utils.py",
                  },
              ],
          },
      ],
  )
  ```

  ```typescript TypeScript
  await client.beta.sessions.events.send(session.id, {
    events: [
      {
        type: "user.message",
        content: [
          {
            type: "text",
            text: "Analyze the performance of the sort function in utils.py"
          }
        ]
      }
    ]
  });
  ```

  ```csharp C#
  await client.Beta.Sessions.Events.Send(session.ID, new()
  {
      Events =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Text = "Analyze the performance of the sort function in utils.py",
                  },
              ],
          },
      ],
  });
  ```

  ```go Go
  if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Text: "Analyze the performance of the sort function in utils.py",
  				},
  			}},
  		},
  	}},
  }); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().sessions().events().send(
      session.id(),
      EventSendParams.builder()
          .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
              .addTextContent("Analyze the performance of the sort function in utils.py")
              .build())
          .build());
  ```

  ```php PHP
  $client->beta->sessions->events->send(
      $session->id,
      events: [
          [
              'type' => 'user.message',
              'content' => [
                  [
                      'type' => 'text',
                      'text' => 'Analyze the performance of the sort function in utils.py',
                  ],
              ],
          ],
      ],
  );
  ```

  ```ruby Ruby
  client.beta.sessions.events.send_(
    session.id,
    events: [
      {
        type: "user.message",
        content: [
          {
            type: "text",
            text: "Analyze the performance of the sort function in utils.py"
          }
        ]
      }
    ]
  )
  ```
</CodeGroup>

세션 기록의 모든 이벤트에는 이벤트 처리가 완료될 때 설정되는 `processed_at` (java, php: `processedAt`; csharp, go: `ProcessedAt`) 타임스탬프가 포함됩니다. 사용자가 전송한 이벤트의 경우, 이벤트가 이전 이벤트 뒤에서 아직 대기 중인 동안 `processed_at` (java, php: `processedAt`; csharp, go: `ProcessedAt`)는 `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `time.Time{}`)입니다. 예외는 `user.define_outcome`, `user.custom_tool_result`, `user.tool_result`로, 이들은 수신 즉시 처리되며 `processed_at` (java, php: `processedAt`; csharp, go: `ProcessedAt`)가 이미 채워진 상태로 반환됩니다.

## 세션이 유휴 상태가 되면 응답하기

`session.status_idle` 이벤트는 에이전트가 중지되어 입력을 기다리고 있음을 의미합니다. 해당 이벤트의 `stop_reason.type`이 그 이유를 알려줍니다.

| `stop_reason.type` | 세션이 중지된 이유 | 해야 할 일 |
| ----- | ----- | ----- |
| `end_turn` | 에이전트가 턴을 마쳤거나 [사용자가 중단했습니다](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#interrupt-the-agent). | 에이전트에게 맡길 작업이 더 있으면 [`user.message`를 전송하세요](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#resume-an-idle-session). |
| `requires_action` | 커스텀 도구 호출이나 확인 요청 등 하나 이상의 도구 호출에 사용자의 응답이 필요합니다. | [차단 중인 각 도구 호출에 응답하세요](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session). |
| `budget_reached` | 세션의 추적된 정가 비용이 [예산](https://platform.claude.com/docs/ko/managed-agents/budgets)에 도달했습니다. | [예산을 변경하거나 제거하세요](https://platform.claude.com/docs/ko/managed-agents/budgets#resume-a-session-at-its-budget). |

예산에 도달하여 일시 중지된 세션은 어떤 이벤트를 전송해도 재개되지 않습니다. 예산으로 인해 일시 중지된 작업은 예산을 소비된 정가 비용보다 높은 값으로 변경하거나 예산을 제거하면 자동으로 재개됩니다. 작업이 재개되면 세션은 [예산으로 인해 일시 중지된 워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#budgets-and-limits)마다 `workflow_run.status_running` 이벤트를 발생시킵니다. 중단(interrupt)으로 일시 중지된 실행은 일시 중지 상태로 유지됩니다. [예산에 도달한 세션 재개하기](https://platform.claude.com/docs/ko/managed-agents/budgets#resume-a-session-at-its-budget)를 참조하세요. 일시 중지를 나타내는 이벤트와 세션이 여전히 수락하는 이벤트는 [세션이 예산에 도달했을 때](https://platform.claude.com/docs/ko/managed-agents/budgets#when-a-session-reaches-its-budget)를 참조하세요.

## 세션을 일시 중지시키는 도구 호출에 응답하기

세션은 에이전트가 [커스텀 도구](https://platform.claude.com/docs/ko/managed-agents/tools#custom-tools)를 호출할 때, 그리고 [권한 정책](https://platform.claude.com/docs/ko/managed-agents/permission-policies)에 따라 도구 호출에 사용자의 확인이 필요할 때 일시 중지됩니다. 두 경우 모두 동일한 순서를 따릅니다:

1. 세션이 도구 호출을 `agent.custom_tool_use`, `agent.tool_use` 또는 `agent.mcp_tool_use` 이벤트로 발생시킵니다.
2. 세션이 `stop_reason.type`이 `requires_action`인 `session.status_idle` 이벤트와 함께 일시 중지됩니다. 차단 중인 이벤트 ID는 `stop_reason.event_ids` 배열에 있습니다.
3. 차단 중인 각 이벤트 ID에 대해 [`user.custom_tool_result`](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#return-a-custom-tool-result) 또는 [`user.tool_confirmation`](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#confirm-a-tool-call) 이벤트를 전송합니다. 커스텀 도구 결과는 2단계를 기다릴 필요가 없습니다.
4. 차단 중인 모든 이벤트가 해결되면 세션은 다시 `running` 상태로 전환됩니다.

멀티에이전트 세션에서는 서버가 서브에이전트의 차단 이벤트를 기본 스레드에도 게시합니다. [도구 권한 및 커스텀 도구](https://platform.claude.com/docs/ko/managed-agents/session-threads#tool-permissions-and-custom-tools)를 참조하세요.

### 커스텀 도구 결과 반환하기

`agent.custom_tool_use` 이벤트에는 도구 이름과 입력이 포함되어 있습니다. 사용자의 시스템에서 도구를 실행하세요. 그런 다음 `custom_tool_use_id` (java: `customToolUseId`; php: `customToolUseID`; csharp, go: `CustomToolUseID`) 매개변수에 이벤트 ID를 전달하고 결과 콘텐츠와 함께 `user.custom_tool_result` 이벤트를 전송하세요.

`session.status_idle`을 기다리지 않고 `agent.custom_tool_use` 이벤트가 도착하는 즉시 결과를 전송할 수 있습니다. 세션은 해당 호출에 대해 여전히 `requires_action` 중지 이유와 함께 `session.status_idle`을 발생시키며, 클라이언트는 이를 무시해도 됩니다. 서버는 동일한 호출에 대한 두 번째 결과를 수락하지만, 해당 결과는 아무런 효과가 없습니다.

[일시 중지된 세션에 재연결](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#reconnect-without-missing-events)하면, 최신 `session.status_idle` 이벤트의 `stop_reason.event_ids`에 응답해야 할 호출이 나열됩니다.

다음 예제는 각 호출이 도착할 때마다 응답합니다.

<CodeGroup exclude="shell:cURL, shell:CLI">
  <CodeGroupItem language="cURL">
    이 워크플로에는 단일 셸 명령보다 더 많은 로직이 필요합니다. 실행하려면 [Anthropic SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)를 사용하세요.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    이 워크플로에는 단일 셸 명령보다 더 많은 로직이 필요합니다. 실행하려면 [Anthropic SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)를 사용하세요.
  </CodeGroupItem>

  ```python Python
  with client.beta.sessions.events.stream(session.id) as stream:
      for event in stream:
          match event.type:
              case "agent.custom_tool_use":
                  result = call_tool(event.name, event.input)

                  client.beta.sessions.events.send(
                      session.id,
                      events=[
                          {
                              "type": "user.custom_tool_result",
                              "custom_tool_use_id": event.id,
                              "content": [{"type": "text", "text": result}],
                          },
                      ],
                  )
              case "session.status_idle":
                  if event.stop_reason and event.stop_reason.type == "end_turn":
                      break
  ```

  ```typescript TypeScript
  const stream = await client.beta.sessions.events.stream(session.id);

  loop: for await (const event of stream) {
    switch (event.type) {
      case "agent.custom_tool_use": {
        const result = await callTool(event.name, event.input);

        await client.beta.sessions.events.send(session.id, {
          events: [
            {
              type: "user.custom_tool_result",
              custom_tool_use_id: event.id,
              content: [{ type: "text", text: result }]
            }
          ]
        });
        break;
      }
      case "session.status_idle":
        if (event.stop_reason.type === "end_turn") {
          break loop;
        }
        break;
    }
  }
  ```

  ```csharp C#
  await foreach (var streamEvent in client.Beta.Sessions.Events.StreamStreaming(session.ID))
  {
      if (streamEvent.Value is BetaManagedAgentsAgentCustomToolUseEvent toolUse)
      {
          var result = await CallTool(toolUse.Name, toolUse.Input);

          await client.Beta.Sessions.Events.Send(session.ID, new()
          {
              Events =
              [
                  new BetaManagedAgentsUserCustomToolResultEventParams
                  {
                      CustomToolUseID = toolUse.ID,
                      Content = [new BetaManagedAgentsTextBlock { Text = result }],
                  },
              ],
          });
      }
      else if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent idle
          && idle.StopReason?.Value is BetaManagedAgentsSessionEndTurn)
      {
          break;
      }
  }
  ```

  ```go Go
  	stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
  	defer stream.Close()

  loop:
  	for stream.Next() {
  		switch event := stream.Current().AsAny().(type) {
  		case anthropic.BetaManagedAgentsAgentCustomToolUseEvent:
  			result := callTool(event.Name, event.Input)
  			if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  				Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  					OfUserCustomToolResult: &anthropic.BetaManagedAgentsUserCustomToolResultEventParams{
  						CustomToolUseID: event.ID,
  						Content: []anthropic.BetaManagedAgentsUserCustomToolResultEventParamsContentUnion{{
  							OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  								Text: result,
  							},
  						}},
  					},
  				}},
  			}); err != nil {
  				panic(err)
  			}
  		case anthropic.BetaManagedAgentsSessionStatusIdleEvent:
  			if _, ok := event.StopReason.AsAny().(anthropic.BetaManagedAgentsSessionEndTurn); ok {
  				break loop
  			}
  		}
  	}
  	if err := stream.Err(); err != nil {
  		panic(err)
  	}
  ```

  ```java Java
  try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
      loop:
      for (var event : stream) {
          switch (event.type().value()) {
              case AGENT_CUSTOM_TOOL_USE -> {
                  var toolUse = event.asAgentCustomToolUse();
                  var result = callTool(toolUse.name(), toolUse.input());

                  client.beta().sessions().events().send(
                      session.id(),
                      EventSendParams.builder()
                          .addEvent(BetaManagedAgentsUserCustomToolResultEventParams.builder()
                              .customToolUseId(toolUse.id())
                              .addTextContent(result)
                              .build())
                          .build());
              }
              case SESSION_STATUS_IDLE -> {
                  if (event.asSessionStatusIdle().stopReason().isEndTurn()) {
                      break loop;
                  }
              }
          }
      }
  }
  ```

  ```php PHP
  $stream = $client->beta->sessions->events->streamStream($session->id);

  foreach ($stream as $event) {
      switch (true) {
          case $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsAgentCustomToolUseEvent:
              $result = callTool($event->name, $event->input);

              $client->beta->sessions->events->send(
                  $session->id,
                  events: [
                      [
                          'type' => 'user.custom_tool_result',
                          'custom_tool_use_id' => $event->id,
                          'content' => [['type' => 'text', 'text' => $result]],
                      ],
                  ],
              );
              break;
          case $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionStatusIdleEvent:
              if ($event->stopReason instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionEndTurn) {
                  break 2;
              }
              break;
      }
  }
  ```

  ```ruby Ruby
  client.beta.sessions.events.stream_events(session.id).each do |event|
    case event
    when Anthropic::Beta::Sessions::BetaManagedAgentsAgentCustomToolUseEvent
      result = call_tool.call(event.name, event.input)
      client.beta.sessions.events.send_(
        session.id,
        events: [
          {
            type: "user.custom_tool_result",
            custom_tool_use_id: event.id,
            content: [{type: "text", text: result}]
          }
        ]
      )
    when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusIdleEvent
      break if event.stop_reason.is_a?(Anthropic::Beta::Sessions::BetaManagedAgentsSessionEndTurn)
    end
  end
  ```
</CodeGroup>

에이전트에 열려 있는 [워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs)이 있으면, 세션이 `running` 상태를 유지하는 동안 커스텀 도구 호출이 도착할 수 있습니다. `requires_action` 유휴 이벤트는 [세션의 스레드](https://platform.claude.com/docs/ko/managed-agents/session-threads) 중 어느 것도 작업 중이지 않을 때만 도착합니다. 이를 기다리지 말고, 각 호출의 `agent.custom_tool_use` 이벤트가 도착하면 응답하세요. [실행 추적하기](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#follow-a-run)의 샘플에서 방법을 확인할 수 있습니다.

### 도구 호출 확인하기

`tool_use_id` (java: `toolUseId`; php: `toolUseID`; csharp, go: `ToolUseID`) 매개변수에 이벤트 ID를 전달하여 `user.tool_confirmation` 이벤트를 전송하세요. `result` (csharp, go: `Result`)를 `"allow"` 또는 `"deny"`로 설정하세요. 어떤 호출이 확인을 기다리는지, 그리고 거부 사유를 설명하는 방법은 [확인 요청에 응답하기](https://platform.claude.com/docs/ko/managed-agents/permission-policies#respond-to-confirmation-requests)를 참조하세요.

다음 예제는 대기 중인 모든 호출을 승인합니다.

<CodeGroup exclude="shell:cURL, shell:CLI">
  <CodeGroupItem language="cURL">
    이 워크플로에는 단일 셸 명령보다 더 많은 로직이 필요합니다. 실행하려면 [Anthropic SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)를 사용하세요.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    이 워크플로에는 단일 셸 명령보다 더 많은 로직이 필요합니다. 실행하려면 [Anthropic SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)를 사용하세요.
  </CodeGroupItem>

  ```python Python
  with client.beta.sessions.events.stream(session.id) as stream:
      for event in stream:
          if event.type == "session.status_idle" and (stop_reason := event.stop_reason):
              match stop_reason.type:
                  case "requires_action":
                      for event_id in stop_reason.event_ids:
                          client.beta.sessions.events.send(
                              session.id,
                              events=[
                                  {
                                      "type": "user.tool_confirmation",
                                      "tool_use_id": event_id,
                                      "result": "allow",
                                  },
                              ],
                          )
                  case "end_turn":
                      break
  ```

  ```typescript TypeScript
  const stream = await client.beta.sessions.events.stream(session.id);

  for await (const event of stream) {
    if (event.type !== "session.status_idle") {
      continue;
    }
    if (event.stop_reason.type === "end_turn") {
      break;
    }
    if (event.stop_reason.type !== "requires_action") {
      continue;
    }

    for (const eventId of event.stop_reason.event_ids) {
      await client.beta.sessions.events.send(session.id, {
        events: [
          {
            type: "user.tool_confirmation",
            tool_use_id: eventId,
            result: "allow"
          }
        ]
      });
    }
  }
  ```

  ```csharp C#
  await foreach (var streamEvent in client.Beta.Sessions.Events.StreamStreaming(session.ID))
  {
      if (streamEvent.Value is not BetaManagedAgentsSessionStatusIdleEvent idle) continue;

      if (idle.StopReason?.Value is BetaManagedAgentsSessionRequiresAction requiresAction)
      {
          foreach (var eventId in requiresAction.EventIds)
          {
              await client.Beta.Sessions.Events.Send(session.ID, new()
              {
                  Events =
                  [
                      new BetaManagedAgentsUserToolConfirmationEventParams
                      {
                          ToolUseID = eventId,
                          Result = BetaManagedAgentsUserToolConfirmationEventParamsResult.Allow,
                      },
                  ],
              });
          }
      }
      else if (idle.StopReason?.Value is BetaManagedAgentsSessionEndTurn)
      {
          break;
      }
  }
  ```

  ```go Go
  	stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
  	defer stream.Close()

  loop:
  	for stream.Next() {
  		event, ok := stream.Current().AsAny().(anthropic.BetaManagedAgentsSessionStatusIdleEvent)
  		if !ok {
  			continue
  		}
  		switch stopReason := event.StopReason.AsAny().(type) {
  		case anthropic.BetaManagedAgentsSessionRequiresAction:
  			for _, eventID := range stopReason.EventIDs {
  				if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  					Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  						OfUserToolConfirmation: &anthropic.BetaManagedAgentsUserToolConfirmationEventParams{
  							ToolUseID: eventID,
  							Result:    anthropic.BetaManagedAgentsUserToolConfirmationEventParamsResultAllow,
  						},
  					}},
  				}); err != nil {
  					panic(err)
  				}
  			}
  		case anthropic.BetaManagedAgentsSessionEndTurn:
  			break loop
  		}
  	}
  	if err := stream.Err(); err != nil {
  		panic(err)
  	}
  ```

  ```java Java
  try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
      stream.stream()
          .filter(BetaManagedAgentsStreamSessionEvents::isSessionStatusIdle)
          .map(idleEvent -> idleEvent.asSessionStatusIdle().stopReason())
          .takeWhile(stopReason -> !stopReason.isEndTurn())
          .filter(stopReason -> stopReason.isRequiresAction())
          .flatMap(stopReason -> stopReason.asRequiresAction().eventIds().stream())
          .forEach(toolUseId -> client.beta().sessions().events().send(
              session.id(),
              EventSendParams.builder()
                  .addEvent(BetaManagedAgentsUserToolConfirmationEventParams.builder()
                      .toolUseId(toolUseId)
                      .result(BetaManagedAgentsUserToolConfirmationEventParams.Result.ALLOW)
                      .build())
                  .build()));
  }
  ```

  ```php PHP
  $stream = $client->beta->sessions->events->streamStream($session->id);

  foreach ($stream as $event) {
      if ($event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionStatusIdleEvent && $event->stopReason) {
          switch (true) {
              case $event->stopReason instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionRequiresAction:
                  foreach ($event->stopReason->eventIDs as $eventId) {
                      $client->beta->sessions->events->send(
                          $session->id,
                          events: [
                              [
                                  'type' => 'user.tool_confirmation',
                                  'tool_use_id' => $eventId,
                                  'result' => 'allow',
                              ],
                          ],
                      );
                  }
                  break;
              case $event->stopReason instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionEndTurn:
                  break 2;
          }
      }
  }
  ```

  ```ruby Ruby
  client.beta.sessions.events.stream_events(session.id).each do |event|
    case event
    when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusIdleEvent
      stop_reason = event.stop_reason
      case stop_reason
      when Anthropic::Beta::Sessions::BetaManagedAgentsSessionRequiresAction
        stop_reason.event_ids.each do |event_id|
          client.beta.sessions.events.send_(
            session.id,
            events: [
              {type: "user.tool_confirmation", tool_use_id: event_id, result: "allow"}
            ]
          )
        end
      when Anthropic::Beta::Sessions::BetaManagedAgentsSessionEndTurn
        break
      end
    end
  end
  ```
</CodeGroup>

앞의 예제는 세션이 유휴 상태가 된 후 각 호출을 승인합니다. 에이전트에 열려 있는 [워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs)이 있으면, 세션이 `running` 상태를 유지하는 동안 도구 호출이 사용자의 확인을 기다릴 수 있습니다. 유휴 이벤트를 기다리지 마세요. [`evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`)](https://platform.claude.com/docs/ko/managed-agents/permission-policies#see-how-each-call-was-evaluated)가 `ask`인 `agent.tool_use` 또는 `agent.mcp_tool_use` 이벤트가 도착하면 응답하세요. [실행 추적하기](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#follow-a-run)의 샘플은 이 방식으로 커스텀 도구 호출에 응답하며, 해당 소개 부분에서 확인을 추가하는 방법을 설명합니다.

## 유휴 세션 재개하기

세션은 상호작용 사이에도 유지됩니다. 세션을 재개하려면 평소처럼 `user.message` 이벤트를 전송하세요.

<CodeGroup>
  ```bash cURL
  # 프로덕션에서는 재개하려는 세션의 저장된 ID를 전달하세요.
  curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "events": [
        {
          "type": "user.message",
          "content": [
            {"type": "text", "text": "Now run the tests against the changes you made earlier."}
          ]
        }
      ]
    }'
  ```

  ```bash CLI
  # 프로덕션에서는 재개하려는 세션의 저장된 ID를 전달하세요.
  ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML'
  events:
    - type: user.message
      content:
        - type: text
          text: Now run the tests against the changes you made earlier.
  YAML
  ```

  ```python Python
  # 새 user.message 이벤트를 전송하여 이전에 생성된 세션을 재개합니다.
  # 프로덕션에서는 재개하려는 세션의 저장된 ID를 전달하세요.
  client.beta.sessions.events.send(
      session.id,
      events=[
          {
              "type": "user.message",
              "content": [
                  {
                      "type": "text",
                      "text": "Now run the tests against the changes you made earlier.",
                  },
              ],
          },
      ],
  )
  ```

  ```typescript TypeScript
  // 이전에 생성된 세션에 새 사용자 이벤트를 보내 세션을 재개합니다.
  // 프로덕션에서는 재개하려는 세션의 저장된 ID를 전달하세요.
  await client.beta.sessions.events.send(session.id, {
    events: [
      {
        type: "user.message",
        content: [
          {
            type: "text",
            text: "Now run the tests against the changes you made earlier."
          }
        ]
      }
    ]
  });
  ```

  ```csharp C#
  // ID로 이전에 생성된 세션을 재개합니다. 프로덕션에서는 세션이
  // 생성될 때 저장해 둔 세션 ID를 전달하세요.
  await client.Beta.Sessions.Events.Send(session.ID, new()
  {
      Events =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Text = "Now run the tests against the changes you made earlier.",
                  },
              ],
          },
      ],
  });
  ```

  ```go Go
  // 새 user.message 이벤트를 전송하여 이전에 생성된 세션을 재개합니다.
  // 프로덕션에서는 재개할 세션의 저장된 ID를 전달하세요.
  if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Text: "Now run the tests against the changes you made earlier.",
  				},
  			}},
  		},
  	}},
  }); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  // 이전에 생성된 세션을 ID로 재개합니다. 프로덕션에서는 세션이
  // 생성될 때 저장해 둔 세션 ID를 전달하세요.
  client.beta().sessions().events().send(
      session.id(),
      EventSendParams.builder()
          .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
              .addTextContent("Now run the tests against the changes you made earlier.")
              .build())
          .build());
  ```

  ```php PHP
  // 새 user.message 이벤트를 보내 이전에 생성한 세션을 재개합니다.
  // 프로덕션에서는 세션 생성 시 저장한 세션 ID를 전달하세요.
  $client->beta->sessions->events->send(
      $session->id,
      events: [
          [
              'type' => 'user.message',
              'content' => [
                  [
                      'type' => 'text',
                      'text' => 'Now run the tests against the changes you made earlier.',
                  ],
              ],
          ],
      ],
  );
  ```

  ```ruby Ruby
  # 세션을 재개하려면 다음 이벤트를 보내세요. 프로덕션에서는
  # 세션 생성 시 저장한 세션 ID를 전달하세요.
  client.beta.sessions.events.send_(
    session.id,
    events: [
      {
        type: "user.message",
        content: [
          {type: "text", text: "Now run the tests against the changes you made earlier."}
        ]
      }
    ]
  )
  ```
</CodeGroup>

세션은 사용자가 세션을 삭제할 때까지 대화 기록을 유지합니다. 세션이 유휴 상태가 되면 Claude Managed Agents가 해당 샌드박스의 체크포인트를 생성합니다. 체크포인트는 파일 시스템, 설치된 패키지, 에이전트가 생성한 모든 파일을 포함한 전체 샌드박스 상태를 보존합니다.

<Note>
  샌드박스 상태는 샌드박스가 생성된 후 30일 동안만 유지되며, 활동이 있어도 이 기간은 연장되지 않습니다. 30일이 지나면 샌드박스 상태(파일, 설치된 도구 등)는 복구할 수 없으며, 재개된 세션은 새 샌드박스에서 시작됩니다. 워크플로가 샌드박스 내용에 의존한다면, 기간이 끝나기 전에 에이전트가 중요한 결과물을 [출력](https://platform.claude.com/docs/ko/managed-agents/define-outcomes#retrieving-deliverables)에 기록하도록 하세요.
</Note>

## 에이전트 중단하기

실행 중인 에이전트를 중지하려면 `user.interrupt` 이벤트를 전송한 다음, `user.message` 이벤트를 이어서 전송하여 방향을 바꾸세요:

<CodeGroup>
  ```bash cURL
  # 에이전트가 현재 파일을 분석 중입니다...
  # 새로운 지시로 중단합니다:
  curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "events": [
        {"type": "user.interrupt"},
        {
          "type": "user.message",
          "content": [
            {"type": "text", "text": "Instead, focus on fixing the bug in line 42."}
          ]
        }
      ]
    }'
  ```

  ```bash CLI
  # 에이전트가 현재 파일을 분석 중입니다...
  # 새로운 지시로 중단합니다:
  ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML'
  events:
    - type: user.interrupt
    - type: user.message
      content:
        - type: text
          text: Instead, focus on fixing the bug in line 42.
  YAML
  ```

  ```python Python
  # 에이전트가 현재 파일을 분석 중입니다...
  # 새로운 지시로 중단합니다:
  client.beta.sessions.events.send(
      session.id,
      events=[
          {"type": "user.interrupt"},
          {
              "type": "user.message",
              "content": [
                  {
                      "type": "text",
                      "text": "Instead, focus on fixing the bug in line 42.",
                  },
              ],
          },
      ],
  )
  ```

  ```typescript TypeScript
  // 에이전트가 현재 파일을 분석 중입니다...
  // 새로운 방향으로 중단(interrupt)합니다:
  await client.beta.sessions.events.send(session.id, {
    events: [
      { type: "user.interrupt" },
      {
        type: "user.message",
        content: [
          {
            type: "text",
            text: "Instead, focus on fixing the bug in line 42."
          }
        ]
      }
    ]
  });
  ```

  ```csharp C#
  // 에이전트가 현재 파일을 분석 중입니다...
  // 새로운 방향으로 인터럽트:
  await client.Beta.Sessions.Events.Send(session.ID, new()
  {
      Events =
      [
          new BetaManagedAgentsUserInterruptEventParams(),
          new BetaManagedAgentsUserMessageEventParams
          {
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Text = "Instead, focus on fixing the bug in line 42.",
                  },
              ],
          },
      ],
  });
  ```

  ```go Go
  // 에이전트가 현재 파일을 분석 중입니다...
  // 새로운 지시로 중단합니다:
  if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  	Events: []anthropic.BetaManagedAgentsEventParamsUnion{
  		{
  			OfUserInterrupt: &anthropic.BetaManagedAgentsUserInterruptEventParams{},
  		},
  		{
  			OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  				Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  					OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  						Text: "Instead, focus on fixing the bug in line 42.",
  					},
  				}},
  			},
  		},
  	},
  }); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  // 에이전트가 현재 파일을 분석 중입니다...
  // 새로운 방향으로 인터럽트합니다:
  client.beta().sessions().events().send(
      session.id(),
      EventSendParams.builder()
          .addEvent(BetaManagedAgentsUserInterruptEventParams.builder().build())
          .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
              .addTextContent("Instead, focus on fixing the bug in line 42.")
              .build())
          .build());
  ```

  ```php PHP
  // 에이전트가 현재 파일을 분석하는 중입니다...
  // 새로운 지시로 중단합니다:
  $client->beta->sessions->events->send(
      $session->id,
      events: [
          ['type' => 'user.interrupt'],
          [
              'type' => 'user.message',
              'content' => [
                  [
                      'type' => 'text',
                      'text' => 'Instead, focus on fixing the bug in line 42.',
                  ],
              ],
          ],
      ],
  );
  ```

  ```ruby Ruby
  # 에이전트가 현재 파일을 분석 중입니다...
  # 새로운 지시로 중단합니다:
  client.beta.sessions.events.send_(
    session.id,
    events: [
      {type: "user.interrupt"},
      {
        type: "user.message",
        content: [
          {type: "text", text: "Instead, focus on fixing the bug in line 42."}
        ]
      }
    ]
  )
  ```
</CodeGroup>

호출은 이벤트가 대기열에 추가되는 즉시 반환됩니다. 그런 다음 중단은 다음 순서로 적용됩니다.

1. 에이전트가 중단을 적용합니다. 그때까지 중단 이벤트의 `processed_at` (java, php: `processedAt`; csharp, go: `ProcessedAt`)는 `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `time.Time{}`) 상태로 유지되며, 세션은 `running` 상태를 유지합니다. 진행 중인 모델 응답은 즉시 중지되지만, 도구 호출이 실행 중인 동안에는 중단이 적용되는 데 더 오래 걸릴 수 있습니다.
2. `user.interrupt` 이벤트가 스트림에 나타나고, 중단된 턴은 `session.status_idle` 이벤트와 함께 종료됩니다.
3. 에이전트는 중단 후 전송한 `user.message`로 다음 턴을 시작합니다.

유휴 이벤트의 `stop_reason.type`은 `end_turn`으로, 스스로 완료된 턴과 같은 값입니다. 열려 있는 워크플로 실행이 있는 경우, 중단은 그중 어느 것도 종료하지 않습니다. 실행 중인 워크플로 실행은 세션을 `running` 상태로 유지할 수 있으므로, 2단계의 `session.status_idle` 이벤트가 도착하지 않을 수 있습니다. [실행이 열려 있는 세션 중단하기](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#interrupt-a-session-with-runs-open)를 참조하세요.

## 과거 이벤트 조회하기

세션의 전체 이벤트 기록을 가져옵니다.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json"
  ```

  ```bash CLI
  ant beta:sessions:events list --session-id "$SESSION_ID" --format jsonl
  ```

  ```python Python
  events = client.beta.sessions.events.list(session.id)
  for event in events.data:
      print(f"[{event.type}] {event.processed_at}")
  ```

  ```typescript TypeScript
  const events = await client.beta.sessions.events.list(session.id);
  for (const event of events.data) {
    console.log(`[${event.type}] ${event.processed_at}`);
  }
  ```

  ```csharp C#
  var events = await client.Beta.Sessions.Events.List(session.ID);
  foreach (var sessionEvent in events.Items)
  {
      Console.WriteLine($"[{sessionEvent.Type.Raw()}] {sessionEvent.ProcessedAt}");
  }
  ```

  ```go Go
  events, err := client.Beta.Sessions.Events.List(ctx, session.ID, anthropic.BetaSessionEventListParams{})
  if err != nil {
  	panic(err)
  }
  for _, event := range events.Data {
  	fmt.Printf("[%s] %s\n", event.Type, event.ProcessedAt)
  }
  ```

  ```java Java
  var events = client.beta().sessions().events().list(session.id());
  for (var event : events.data()) {
      IO.println("[" + event.type().asString() + "] " + event.processedAt().orElse(null));
  }
  ```

  ```php PHP
  $events = $client->beta->sessions->events->list($session->id);
  foreach ($events->data as $event) {
      $processedAt = ($event->processedAt ?? null)?->format(DATE_RFC3339) ?? 'null';
      echo "[{$event->type}] {$processedAt}\n";
  }
  ```

  ```ruby Ruby
  events = client.beta.sessions.events.list(session.id)
  events.data.each { puts "[#{it.type}] #{it.processed_at}" }
  ```
</CodeGroup>

특정 이벤트 유형만 반환하려면 `types` (curl: `types[]`; cli: `--type`; csharp, go: `Types`) 필터를 전달하세요.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true&types[]=agent.tool_use&types[]=agent.tool_result" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:sessions:events list --session-id "$SESSION_ID" \
    --type agent.tool_use --type agent.tool_result \
    --format jsonl
  ```

  ```python Python
  events = client.beta.sessions.events.list(
      session.id,
      types=["agent.tool_use", "agent.tool_result"],
  )
  for event in events.data:
      print(f"[{event.type}] {event.processed_at}")
  ```

  ```typescript TypeScript
  const events = await client.beta.sessions.events.list(session.id, {
    types: ["agent.tool_use", "agent.tool_result"]
  });
  for (const event of events.data) {
    console.log(`[${event.type}] ${event.processed_at}`);
  }
  ```

  ```csharp C#
  var events = await client.Beta.Sessions.Events.List(session.ID, new()
  {
      Types = ["agent.tool_use", "agent.tool_result"],
  });
  foreach (var sessionEvent in events.Items)
  {
      Console.WriteLine($"[{sessionEvent.Type.Raw()}] {sessionEvent.ProcessedAt}");
  }
  ```

  ```go Go
  events, err := client.Beta.Sessions.Events.List(ctx, session.ID, anthropic.BetaSessionEventListParams{
  	Types: []anthropic.BetaManagedAgentsSessionEventType{
  		anthropic.BetaManagedAgentsSessionEventTypeAgentToolUse,
  		anthropic.BetaManagedAgentsSessionEventTypeAgentToolResult,
  	},
  })
  if err != nil {
  	panic(err)
  }
  for _, event := range events.Data {
  	fmt.Printf("[%s] %s\n", event.Type, event.ProcessedAt)
  }
  ```

  ```java Java
  var events = client.beta().sessions().events().list(
      session.id(),
      EventListParams.builder()
          .addType(BetaManagedAgentsSessionEventType.AGENT_TOOL_USE)
          .addType(BetaManagedAgentsSessionEventType.AGENT_TOOL_RESULT)
          .build());
  for (var event : events.data()) {
      event.agentToolUse().ifPresent(toolUse ->
          IO.println("[" + toolUse._type() + "] " + toolUse.processedAt()));
      event.agentToolResult().ifPresent(toolResult ->
          IO.println("[" + toolResult._type() + "] " + toolResult.processedAt()));
  }
  ```

  ```php PHP
  $events = $client->beta->sessions->events->list(
      $session->id,
      types: ['agent.tool_use', 'agent.tool_result'],
  );
  foreach ($events->data as $event) {
      $processedAt = ($event->processedAt ?? null)?->format(DATE_RFC3339) ?? 'null';
      echo "[{$event->type}] {$processedAt}\n";
  }
  ```

  ```ruby Ruby
  events = client.beta.sessions.events.list(
    session.id,
    types: ["agent.tool_use", "agent.tool_result"]
  )
  events.data.each { puts "[#{it.type}] #{it.processed_at}" }
  ```
</CodeGroup>

## 시스템 메시지 전송하기

[지원되는 모델](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#supported-models)에서는 `system.message` 이벤트를 전송하여 에이전트에 권한 있는 시스템 수준 컨텍스트를 제공할 수 있습니다. 이 컨텍스트는 함께 전송된 턴과 이후의 모든 턴에 적용됩니다. 세션 도중 에이전트에 업데이트된 시스템 수준 지침이 필요할 때 사용하세요. 예를 들어 다른 페르소나, 수정된 제약 조건, 런타임에 가져온 컨텍스트 등이 있습니다.

이벤트의 `content` (csharp, go: `Content`)는 1\~1,000개의 텍스트 항목을 허용합니다. 서버는 콘텐츠를 `role: "system"` 턴으로 세션의 시스템 컨텍스트에 추가합니다. 이는 에이전트 정의의 `system` (csharp, go: `System`; ruby: `system_`) 필드로 설정되는 최상위 시스템 프롬프트를 대체하지 않습니다.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "events": [
        {
          "type": "system.message",
          "content": [
            {"type": "text", "text": "The current timezone of the user is America/New_York."}
          ]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML'
  events:
    - type: system.message
      content:
        - type: text
          text: "The user's current timezone is America/New_York."
  YAML
  ```

  ```python Python
  client.beta.sessions.events.send(
      session.id,
      events=[
          {
              "type": "system.message",
              "content": [
                  {
                      "type": "text",
                      "text": "The user's current timezone is America/New_York.",
                  },
              ],
          },
      ],
  )
  ```

  ```typescript TypeScript
  await client.beta.sessions.events.send(session.id, {
    events: [
      {
        type: "system.message",
        content: [
          {
            type: "text",
            text: "The user's current timezone is America/New_York."
          }
        ]
      }
    ]
  });
  ```

  ```csharp C#
  await client.Beta.Sessions.Events.Send(session.ID, new()
  {
      Events =
      [
          new BetaManagedAgentsSystemMessageEventParams
          {
              Content =
              [
                  new BetaManagedAgentsSystemContentBlock
                  {
                      Text = "The user's current timezone is America/New_York.",
                  },
              ],
          },
      ],
  });
  ```

  ```go Go
  if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  		OfSystemMessage: &anthropic.BetaManagedAgentsSystemMessageEventParams{
  			Content: []anthropic.BetaManagedAgentsSystemContentBlockParam{{
  				Text: "The user's current timezone is America/New_York.",
  			}},
  		},
  	}},
  }); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().sessions().events().send(
      session.id(),
      EventSendParams.builder()
          .addEvent(BetaManagedAgentsSystemMessageEventParams.builder()
              .addTextContent("The user's current timezone is America/New_York.")
              .build())
          .build());
  ```

  ```php PHP
  $client->beta->sessions->events->send(
      $session->id,
      events: [
          [
              'type' => 'system.message',
              'content' => [
                  [
                      'type' => 'text',
                      'text' => "The user's current timezone is America/New_York.",
                  ],
              ],
          ],
      ],
  );
  ```

  ```ruby Ruby
  client.beta.sessions.events.send_(
    session.id,
    events: [
      {
        type: "system.message",
        content: [
          {type: "text", text: "The user's current timezone is America/New_York."}
        ]
      }
    ]
  )
  ```
</CodeGroup>

### 지원되는 모델

다음 모델이 `system.message`를 지원합니다.

* Claude Fable 5.2
* Claude Mythos 5.2
* Claude Fable 5.1
* Claude Mythos 5.1
* Claude Fable 5
* Claude Mythos 5
* Claude Opus 5.5
* Claude Opus 5
* Claude Opus 4.8
* Claude Sonnet 5.5
* Claude Haiku 5.5

에이전트의 기본 모델이 대화 도중 시스템 주입을 지원하지 않으면, API는 `model_does_not_support_mid_conversation_system` 유효성 검사 오류와 함께 이벤트를 거부합니다. `system.message`는 기본 스레드에만 전달되므로 API는 서브에이전트 모델을 검사하지 않습니다.

### 도구 호출이 대기 중일 때의 시스템 메시지

세션이 `requires_action` 중지 이유로 유휴 상태인 동안에는 `system.message`가 동일한 요청에서 도구 결과 이벤트 뒤에 와야 합니다. 단독으로 전송하거나 `user.message`와 함께 전송하면, 대기 중인 도구 이벤트가 해결될 때까지 거부됩니다.

## 다음 단계

<CardGroup cols={2}>
  <Card title="이벤트 델타로 응답 미리 보기" icon="text" href="https://platform.claude.com/docs/ko/managed-agents/event-deltas">
    모델이 아직 생성 중인 에이전트의 응답 텍스트를 렌더링합니다.
  </Card>

  <Card title="세션 검사 및 사용량 추적" icon="magnifying-glass" href="https://platform.claude.com/docs/ko/managed-agents/session-observability">
    Claude Console에서 세션을 검사하고 토큰 사용량과 정가 비용을 확인합니다.
  </Card>

  <Card title="Webhook 구독하기" icon="link" href="https://platform.claude.com/docs/ko/managed-agents/webhooks">
    폴링 없이 주요 이벤트가 발생하면 알림을 받습니다.
  </Card>

  <Card title="이벤트 유형" icon="book" href="https://platform.claude.com/docs/ko/managed-agents/reference#event-types">
    세션이 전송하거나 수신할 수 있는 모든 이벤트 유형을 찾아봅니다.
  </Card>
</CardGroup>
