agent-sdk/typescript.md +28 −6
2386 kind: "task-notification";2386 kind: "task-notification";
2387 subkind?: "scheduled-trigger" | "peer-send-message";2387 subkind?: "scheduled-trigger" | "peer-send-message";
2388 fireReason?: string;2388 fireReason?: string;
2389 runId?: string;
2389 }2390 }
2390 | { kind: "coordinator" }2391 | { kind: "coordinator" }
2391 | { kind: "auto-continuation" }2392 | { kind: "auto-continuation" }
2415 2416
2416`fireReason`은 `scheduled-trigger` 알림이 실행된 이유를 `scheduled`, `manual`, `retry`, `catch_up`, `api` 같은 짧은 소문자 토큰으로 나타냅니다. Anthropic 서버는 [루틴](/docs/ko/routines)의 전달에 이를 설정하며, 애플리케이션은 예약 실행을 선언할 때 이를 설정합니다. 어느 쪽도 보내지 않으면 없습니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.2417`fireReason`은 `scheduled-trigger` 알림이 실행된 이유를 `scheduled`, `manual`, `retry`, `catch_up`, `api` 같은 짧은 소문자 토큰으로 나타냅니다. Anthropic 서버는 [루틴](/docs/ko/routines)의 전달에 이를 설정하며, 애플리케이션은 예약 실행을 선언할 때 이를 설정합니다. 어느 쪽도 보내지 않으면 없습니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.
2417 2418
2419Claude가 [서브에이전트를 재개](/docs/ko/agent-sdk/subagents#resume-subagents)하는 경우처럼, 백그라운드 작업은 동일한 `task_id`로 여러 번 실행될 수 있습니다. 각 실행에는 고유한 [`run_id`](#sdktaskstartedmessage)가 있습니다. 실행의 알림이 사용자 메시지로 세션에 도달하면, 해당 메시지의 `task-notification` 출처에 있는 `runId`가 같은 값을 가집니다. 알림은 작업의 다음 실행이 시작된 후에 도착할 수도 있으며, 이 경우에도 이전 실행의 ID를 담고 있습니다. 턴이 어느 실행에 속하는지 구분하려면 `task_id`가 아니라 `runId`를 비교하세요. TypeScript Agent SDK v0.3.292 이상이 필요합니다.
2420
2418<h4 id="declare-a-scheduled-run">2421<h4 id="declare-a-scheduled-run">
2419 예약 실행 선언2422 예약 실행 선언
2420</h4>2423</h4>
3259 도구 입력 타입3262 도구 입력 타입
3260</h2>3263</h2>
3261 3264
32623265모든 기본 제공 Claude Code 도구의 입력 스키마 문서입니다. 이 타입은 `@anthropic-ai/claude-agent-sdk/sdk-tools`에서 내보내지며 타입 안전 도구 상호작용에 사용할 수 있습니다.기본 제공 Claude Code 도구의 입력 스키마 문서입니다. 이 타입은 `@anthropic-ai/claude-agent-sdk/sdk-tools`에서 내보내지며 타입 안전 도구 상호작용에 사용할 수 있습니다.
3263 3266
3264<h3 id="toolinputschemas">3267<h3 id="toolinputschemas">
3265 `ToolInputSchemas`3268 `ToolInputSchemas`
4075 도구 출력 타입4078 도구 출력 타입
4076</h2>4079</h2>
4077 4080
40784081모든 기본 제공 Claude Code 도구의 출력 스키마 문서입니다. 이 타입은 `@anthropic-ai/claude-agent-sdk/sdk-tools`에서 내보내지며 각 도구에서 반환된 실제 응답 데이터를 나타냅니다.기본 제공 Claude Code 도구의 출력 스키마 문서입니다. 이 타입은 `@anthropic-ai/claude-agent-sdk/sdk-tools`에서 내보내지며 각 도구에서 반환된 실제 응답 데이터를 나타냅니다.
4079 4082
4080<h3 id="tooloutputschemas">4083<h3 id="tooloutputschemas">
4081 `ToolOutputSchemas`4084 `ToolOutputSchemas`
5728 `SDKTaskNotificationMessage`5731 `SDKTaskNotificationMessage`
5729</h3>5732</h3>
5730 5733
57315734백그라운드 작업이 완료, 실패 또는 중지될 때의 알림입니다. 백그라운드 작업에는 `run_in_background` Bash 명령, [Monitor](#monitor) 감시 및 백그라운드 서브에이전트가 포함됩니다. `ambient` 필드는 이를 정의하고 버전 요구 사항을 설명하는 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)를 참조하세요.백그라운드 작업이 완료, 실패 또는 중지될 때의 알림입니다. 백그라운드 작업에는 `run_in_background` Bash 명령, [Monitor](#monitor) 감시 및 백그라운드 서브에이전트가 포함됩니다. `run_id` 및 `ambient` 필드는 이를 정의하고 버전 요구 사항을 설명하는 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)를 참조하세요.
5732 5735
5733```typescript theme={null}5736```typescript theme={null}
5734type SDKTaskNotificationMessage = {5737type SDKTaskNotificationMessage = {
5735 type: "system";5738 type: "system";
5736 subtype: "task_notification";5739 subtype: "task_notification";
5737 task_id: string;5740 task_id: string;
5741 run_id?: string;
5738 tool_use_id?: string;5742 tool_use_id?: string;
5739 status: "completed" | "failed" | "stopped";5743 status: "completed" | "failed" | "stopped";
5740 reason?: "worker_restart";5744 reason?: "worker_restart";
5907 type: "system";5911 type: "system";
5908 subtype: "task_started";5912 subtype: "task_started";
5909 task_id: string;5913 task_id: string;
5914 run_id?: string;
5910 tool_use_id?: string;5915 tool_use_id?: string;
5911 description: string;5916 description: string;
5912 task_type?: string;5917 task_type?: string;
5919};5924};
5920```5925```
5921 5926
5927`run_id`는 작업의 한 번의 실행을 식별합니다. [Claude가 재개하는 서브에이전트](/docs/ko/agent-sdk/subagents#resume-subagents)처럼 작업이 동일한 `task_id`로 다시 실행되면, 새 실행은 새 `run_id`를 받습니다. 필드는 Agent SDK v0.3.292 이상이 필요합니다. 이를 사용하여 한 작업의 실행들을 구분하세요:
5928
5929* **메시지를 실행과 일치시키기**: 한 실행의 `task_started`, [`task_progress`](#sdktaskprogressmessage), [`task_updated`](#sdktaskupdatedmessage) 및 [`task_notification`](#sdktasknotificationmessage) 메시지는 동일한 `run_id`를 전달합니다. 각 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage)에 있는 해당 실행의 항목도 이를 전달하며, 해당 실행의 알림을 전달하는 사용자 메시지의 origin에 있는 [`runId`](#task-notification-subkinds)도 마찬가지입니다.
5930* **늦게 도착한 메시지 감지하기**: 일반 문자열로 비교하면 한 작업의 실행 ID는 실행이 시작된 순서대로 정렬되므로, `run_id`가 표시 중인 실행보다 앞에 정렬되는 메시지는 이전 실행에서 온 것입니다. 이 비교 외에는 값을 불투명한 것으로 취급하세요.
5931* **`task_id`로 대체하기**: 이전 프로세스가 시작한 작업을 닫기 위해 재개된 세션이 내보내는 `task_notification`처럼 메시지에 `run_id`가 없을 때는 `task_id`로 귀속시키세요.
5932
5933예를 들어, 식별 필드만 남기고 줄인 다음 세 메시지는 Claude가 한 번 재개한 백그라운드 서브에이전트에서 온 것입니다. 두 `task_started` 메시지는 `task_id`를 공유하며, 첫 번째 실행을 종료한 알림은 첫 번째 실행의 ID를 전달합니다:
5934
5935```json theme={null}
5936{"subtype": "task_started", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubbs7i8-6f0c2d41"}
5937{"subtype": "task_notification", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubbs7i8-6f0c2d41", "status": "completed"}
5938{"subtype": "task_started", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubc18m1-b7719e05"}
5939```
5940
5922`ambient`는 세션의 작업의 일부가 아닌 작업(예: Claude Code가 자신의 작업을 위해 실행하는 작업)에 대해 `true`입니다. 라이브 업데이트 감시자도 ambient이며, 여기에는 사용자가 요청한 감시자가 포함됩니다. ambient 작업을 활동 표시기에서 제외하세요. 필드는 Agent SDK v0.3.247 이상이 필요합니다.5941`ambient`는 세션의 작업의 일부가 아닌 작업(예: Claude Code가 자신의 작업을 위해 실행하는 작업)에 대해 `true`입니다. 라이브 업데이트 감시자도 ambient이며, 여기에는 사용자가 요청한 감시자가 포함됩니다. ambient 작업을 활동 표시기에서 제외하세요. 필드는 Agent SDK v0.3.247 이상이 필요합니다.
5923 5942
5924`ambient`는 또한 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 및 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 항목에 나타납니다.5943`ambient`는 또한 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 및 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 항목에 나타납니다.
5942 `SDKTaskProgressMessage`5961 `SDKTaskProgressMessage`
5943</h3>5962</h3>
5944 5963
59455964서브에이전트 또는 백그라운드 작업이 실행 중일 때 주기적으로 내보내집니다.서브에이전트 또는 백그라운드 작업이 실행 중일 때 주기적으로 내보내집니다. `run_id` 필드는 이를 정의하고 버전 요구 사항을 설명하는 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)를 참조하세요.
5946 5965
5947서브에이전트 작업의 경우, `summary` 필드는 모델 생성 진행 상황 요약을 전달하며 [`agentProgressSummaries`](#options)가 활성화되었을 때만 채워집니다. [백그라운드 MCP 도구 호출](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)의 경우, `summary`는 MCP 서버의 최신 보고된 진행 상황을 전달하며 해당 옵션에 따라 달라지지 않습니다.5966서브에이전트 작업의 경우, `summary` 필드는 모델 생성 진행 상황 요약을 전달하며 [`agentProgressSummaries`](#options)가 활성화되었을 때만 채워집니다. [백그라운드 MCP 도구 호출](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)의 경우, `summary`는 MCP 서버의 최신 보고된 진행 상황을 전달하며 해당 옵션에 따라 달라지지 않습니다.
5948 5967
5951 type: "system";5970 type: "system";
5952 subtype: "task_progress";5971 subtype: "task_progress";
5953 task_id: string;5972 task_id: string;
5973 run_id?: string;
5954 tool_use_id?: string;5974 tool_use_id?: string;
5955 description: string;5975 description: string;
5956 subagent_type?: string;5976 subagent_type?: string;
5970 `SDKTaskUpdatedMessage`5990 `SDKTaskUpdatedMessage`
5971</h3>5991</h3>
5972 5992
59735993백그라운드 작업의 상태가 변경될 때 내보내집니다. 예를 들어 `running`에서 `completed`로 전환될 때입니다. `patch`를 `task_id`로 키가 지정된 로컬 작업 맵에 병합하세요. `end_time` 필드는 Unix epoch 타임스탬프(밀리초)이며 `Date.now()`와 비교할 수 있습니다.백그라운드 작업의 상태가 변경될 때 내보내집니다. 예를 들어 `running`에서 `completed`로 전환될 때입니다. `patch`를 `task_id`로 키가 지정된 로컬 작업 맵에 병합하세요. `end_time` 필드는 Unix epoch 타임스탬프(밀리초)이며 `Date.now()`와 비교할 수 있습니다. `run_id` 필드는 이를 정의하고 버전 요구 사항을 설명하는 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)를 참조하세요.
5974 5994
5975```typescript theme={null}5995```typescript theme={null}
5976type SDKTaskUpdatedMessage = {5996type SDKTaskUpdatedMessage = {
5977 type: "system";5997 type: "system";
5978 subtype: "task_updated";5998 subtype: "task_updated";
5979 task_id: string;5999 task_id: string;
6000 run_id?: string;
5980 patch: {6001 patch: {
5981 status?: "pending" | "running" | "completed" | "failed" | "killed";6002 status?: "pending" | "running" | "completed" | "failed" | "killed";
5982 description?: string;6003 description?: string;
5994 `SDKBackgroundTasksChangedMessage`6015 `SDKBackgroundTasksChangedMessage`
5995</h3>6016</h3>
5996 6017
59976018라이브 백그라운드 작업 집합이 변경될 때마다 내보내집니다. 작업이 시작되거나, 완료되거나, 종료되거나, 포그라운드 에이전트가 백그라운드로 전환되거나, 작업의 `description`, `ambient` 또는 `parent_task_id` 필드가 변경될 때입니다. 각 항목의 `parent_task_id` 필드는 이를 정의하고 버전 요구 사항을 설명하는 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)를 참조하세요.라이브 백그라운드 작업 집합이 변경될 때마다 내보내집니다. 작업이 시작되거나, 완료되거나, 종료되거나, 포그라운드 에이전트가 백그라운드로 전환되거나, 작업의 `description`, `ambient` 또는 `parent_task_id` 필드가 변경될 때입니다. 각 항목의 `run_id` 및 `parent_task_id` 필드는 이를 정의하고 버전 요구 사항을 설명하는 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)를 참조하세요.
5998 6019
5999`tasks` 배열은 전체 라이브 집합입니다. `task_started` 및 `task_notification` 이벤트를 쌍으로 맞추는 대신 각 페이로드로 캐시된 집합을 교체하세요. 그러면 다음 멤버십 변경이 놓친 이벤트를 바로잡습니다.6020`tasks` 배열은 전체 라이브 집합입니다. `task_started` 및 `task_notification` 이벤트를 쌍으로 맞추는 대신 각 페이로드로 캐시된 집합을 교체하세요. 그러면 다음 멤버십 변경이 놓친 이벤트를 바로잡습니다.
6000 6021
6012 subtype: "background_tasks_changed";6033 subtype: "background_tasks_changed";
6013 tasks: {6034 tasks: {
6014 task_id: string;6035 task_id: string;
6036 run_id?: string;
6015 task_type: string;6037 task_type: string;
6016 subagent_type?: string;6038 subagent_type?: string;
6017 description: string;6039 description: string;