1561 parent_tool_use_id: string | null;1561 parent_tool_use_id: string | null;
1562 error?: SDKAssistantMessageError;1562 error?: SDKAssistantMessageError;
1563 aborted?: true;1563 aborted?: true;
1564 agent_id?: string;
1564 timestamp?: string;1565 timestamp?: string;
1565 context_usage?: SDKContextUsage;1566 context_usage?: SDKContextUsage;
1566 user_message_uuid?: string;1567 user_message_uuid?: string;
1580 1581
1581`aborted`는 인터럽트 또는 중단으로 인해 스트림이 완료되기 전에 어시스턴트 메시지가 잘렸을 때 `true`입니다. 이 경우 메시지에는 `stop_reason`이 없으며 콘텐츠가 단어 중간에서 끝날 수 있습니다. 정상적으로 완료된 메시지에는 이 필드가 없습니다. Agent SDK v0.3.214 이상이 필요합니다.1582`aborted`는 인터럽트 또는 중단으로 인해 스트림이 완료되기 전에 어시스턴트 메시지가 잘렸을 때 `true`입니다. 이 경우 메시지에는 `stop_reason`이 없으며 콘텐츠가 단어 중간에서 끝날 수 있습니다. 정상적으로 완료된 메시지에는 이 필드가 없습니다. Agent SDK v0.3.214 이상이 필요합니다.
1582 1583
1584`agent_id`는 메시지를 생성한 서브에이전트를 식별하며, 메인 스레드 메시지에는 없습니다. 이 값은 해당 서브에이전트의 [`task_started`](#sdktaskstartedmessage) 및 기타 작업 이벤트의 `task_id`와 같으며, 서브에이전트가 [재개](/docs/ko/agent-sdk/subagents#resume-subagents)되어도 변경되지 않습니다. 이 필드에는 Agent SDK v0.3.292 이상이 필요합니다.
1585
1586서브에이전트의 메시지를 작업 이벤트와 매칭할 때는 메시지의 `parent_tool_use_id`를 작업 이벤트의 `tool_use_id`와 짝짓지 말고 `agent_id`를 기준으로 매칭하세요. 도구 호출이 서브에이전트를 재개하면 작업 이벤트는 해당 호출의 `tool_use_id`를 가지지만, 메시지는 서브에이전트를 처음 시작한 도구 호출의 `parent_tool_use_id`를 유지하므로 두 값이 더 이상 일치하지 않습니다.
1587
1583Claude Code는 [`user_message_uuid`](#user_message_uuid)에 설명된 조건에 따라 턴의 첫 번째 어시스턴트 메시지에 `user_message_uuid`와 `user_message_uuids`를 설정합니다. 재시작으로 중단된 턴을 Claude Code가 다시 실행할 때, 해당 필드를 가진 재실행의 어시스턴트 메시지에는 [`resume_reason`](#resume_reason)도 포함됩니다.1588Claude Code는 [`user_message_uuid`](#user_message_uuid)에 설명된 조건에 따라 턴의 첫 번째 어시스턴트 메시지에 `user_message_uuid`와 `user_message_uuids`를 설정합니다. 재시작으로 중단된 턴을 Claude Code가 다시 실행할 때, 해당 필드를 가진 재실행의 어시스턴트 메시지에는 [`resume_reason`](#resume_reason)도 포함됩니다.
1584 1589
1585`timestamp`는 메시지를 생성한 프로세스에서 메시지 콘텐츠 생성이 완료된 ISO 8601 시각입니다. 이 값은 해당 머신의 시계에서 가져오므로 표시 용도로만 사용하고 메시지 정렬에는 사용하지 마세요. 하나의 API 턴이 같은 `message.id`를 공유하는 여러 어시스턴트 메시지를 생성할 수 있으며, 각 메시지는 고유한 `timestamp`를 가집니다. 이 필드가 없으면 메시지를 수신한 시각을 대신 사용하세요.1590`timestamp`는 메시지를 생성한 프로세스에서 메시지 콘텐츠 생성이 완료된 ISO 8601 시각입니다. 이 값은 해당 머신의 시계에서 가져오므로 표시 용도로만 사용하고 메시지 정렬에는 사용하지 마세요. 하나의 API 턴이 같은 `message.id`를 공유하는 여러 어시스턴트 메시지를 생성할 수 있으며, 각 메시지는 고유한 `timestamp`를 가집니다. 이 필드가 없으면 메시지를 수신한 시각을 대신 사용하세요.
1597 type: "user";1602 type: "user";
1598 uuid?: UUID;1603 uuid?: UUID;
1599 session_id?: string;1604 session_id?: string;
1605 agent_id?: string;
1600 message: MessageParam; // From Anthropic SDK1606 message: MessageParam; // From Anthropic SDK
1601 pasted_content?: MessageParam["content"][];1607 pasted_content?: MessageParam["content"][];
1602 parent_tool_use_id: string | null;1608 parent_tool_use_id: string | null;
1636};1642};
1637```1643```
1638 1644
1645서브에이전트가 생성하는 사용자 메시지(예: 자체 도구 호출 중 하나에 대한 `tool_result`)는 `agent_id`를 가집니다. 이 필드와 버전 요구 사항은 [`SDKAssistantMessage`](#sdkassistantmessage)에서 정의합니다.
1646
1639`tool_result` 블록을 포함한 메시지에서 `tool_use_result`는 모델에 전송된 텍스트가 아니라 도구의 구조화된 출력 객체입니다. 그 형태는 대응하는 `tool_use` 블록이 지정한 도구에 따라 달라지므로 이 필드는 `unknown` 타입입니다. 기본 제공 형태는 [도구 출력 타입](#tool-output-types)에 나열되어 있습니다. 다음 결과는 나열된 형태 이상의 처리가 필요합니다.1647`tool_result` 블록을 포함한 메시지에서 `tool_use_result`는 모델에 전송된 텍스트가 아니라 도구의 구조화된 출력 객체입니다. 그 형태는 대응하는 `tool_use` 블록이 지정한 도구에 따라 달라지므로 이 필드는 `unknown` 타입입니다. 기본 제공 형태는 [도구 출력 타입](#tool-output-types)에 나열되어 있습니다. 다음 결과는 나열된 형태 이상의 처리가 필요합니다.
1640 1648
1641* `Agent` 도구: `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `tool_result` 텍스트를 파싱하지 말고 이 값으로 렌더링하세요. `completed` 결과의 `content`에는 서브에이전트의 보고서가 담기며, 보고서를 `SubagentHandback` 도구 호출로 전달하는 서브에이전트의 경우에는 보고서 대신 해당 인계에 대한 짧은 메모가 담깁니다. Claude Code v2.1.271 이상의 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서는 [포크](/docs/ko/sub-agents#fork-the-current-conversation)가 아닌 한 `completed` 결과를 생성하는 모든 서브에이전트가 그런 방식으로 보고하며, Claude는 서브에이전트로부터 별도의 메시지로 보고서를 받습니다.1649* `Agent` 도구: `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `tool_result` 텍스트를 파싱하지 말고 이 값으로 렌더링하세요. `completed` 결과의 `content`에는 서브에이전트의 보고서가 담기며, 보고서를 `SubagentHandback` 도구 호출로 전달하는 서브에이전트의 경우에는 보고서 대신 해당 인계에 대한 짧은 메모가 담깁니다. Claude Code v2.1.271 이상의 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서는 [포크](/docs/ko/sub-agents#fork-the-current-conversation)가 아닌 한 `completed` 결과를 생성하는 모든 서브에이전트가 그런 방식으로 보고하며, Claude는 서브에이전트로부터 별도의 메시지로 보고서를 받습니다.
1992 `SDKPartialAssistantMessage`2000 `SDKPartialAssistantMessage`
1993</h3>2001</h3>
1994 2002
1995스트리밍 부분 메시지입니다(`includePartialMessages`가 true일 때만). `parent_tool_use_id` 필드는 항상 `null`입니다. 스트림 이벤트는 메인 세션에 대해서만 내보내집니다. 서브에이전트 귀속에는 `parent_tool_use_id`를 가진 완전한 메시지를 사용하거나, [`forwardSubagentText`](#options)를 활성화하여 서브에이전트 텍스트와 사고를 완전한 메시지로 받으세요.2003스트리밍 부분 메시지입니다(`includePartialMessages`가 true인 경우에만).
2004
2005`parent_tool_use_id` 필드는 항상 `null`입니다. 스트림 이벤트는 메인 세션에 대해서만 생성됩니다. 서브에이전트 귀속에는 [`agent_id`](#sdkassistantmessage)와 `parent_tool_use_id`를 가진 완전한 메시지를 사용하거나, [`forwardSubagentText`](#options)를 활성화하여 서브에이전트의 텍스트와 사고를 완전한 메시지로 받으세요.
1996 2006
1997```typescript theme={null}2007```typescript theme={null}
1998type SDKPartialAssistantMessage = {2008type SDKPartialAssistantMessage = {
5773 task_type?: string;5783 task_type?: string;
5774 is_backgrounded?: boolean;5784 is_backgrounded?: boolean;
5775 spawn_depth?: number;5785 spawn_depth?: number;
5786 parent_task_id?: string;
5776 ambient?: boolean;5787 ambient?: boolean;
5777 uuid: UUID;5788 uuid: UUID;
5778 session_id: string;5789 session_id: string;
5790 5801
5791[재개된 서브에이전트](/docs/ko/agent-sdk/subagents#resume-subagents)는 항상 `is_backgrounded: true`를 보고합니다. Claude Code는 모든 재개된 서브에이전트를 백그라운드에서 실행하기 때문입니다. 포그라운드 작업이 나중에 백그라운드로 이동할 때, Claude Code는 두 번째 `task_started`를 전송하는 대신 새로운 `is_backgrounded` 값을 [`task_updated`](#sdktaskupdatedmessage) 메시지에서 보고합니다.5802[재개된 서브에이전트](/docs/ko/agent-sdk/subagents#resume-subagents)는 항상 `is_backgrounded: true`를 보고합니다. Claude Code는 모든 재개된 서브에이전트를 백그라운드에서 실행하기 때문입니다. 포그라운드 작업이 나중에 백그라운드로 이동할 때, Claude Code는 두 번째 `task_started`를 전송하는 대신 새로운 `is_backgrounded` 값을 [`task_updated`](#sdktaskupdatedmessage) 메시지에서 보고합니다.
5792 5803
5804`parent_task_id`는 이 작업을 시작한 서브에이전트의 `task_id`를 담습니다. 이를 사용하여 각 작업을 해당 작업을 시작한 서브에이전트 아래에 그룹화하세요. Claude Code는 서브에이전트, Bash 및 [Monitor](#monitor) 작업에서 이를 설정합니다. 필드는 Agent SDK v0.3.292 이상이 필요합니다. 다음 경우에는 없습니다:
5805
5806* 주 스레드가 작업을 시작한 경우
5807* Claude Code가 더 이상 부모 작업을 추적하지 않는 경우
5808* [팀원](/docs/ko/agent-teams) 또는 워크플로 내부의 에이전트가 작업을 시작한 경우
5809
5810부모는 포그라운드 작업이거나 이미 종료된 작업일 수 있으므로, 인식하지 못하는 ID는 부모가 없는 것으로 취급하세요.
5811
5793<h3 id="sdktaskprogressmessage">5812<h3 id="sdktaskprogressmessage">
5794 `SDKTaskProgressMessage`5813 `SDKTaskProgressMessage`
5795</h3>5814</h3>
5846 `SDKBackgroundTasksChangedMessage`5865 `SDKBackgroundTasksChangedMessage`
5847</h3>5866</h3>
5848 5867
5849라이브 백그라운드 작업 집합이 변경될 때마다 내보내집니다. 작업이 시작되거나, 완료되거나, 종료되거나, 포그라운드 에이전트가 백그라운드로 전환되거나, 작업의 `description` 또는 `ambient` 필드가 변경될 때입니다.5868라이브 백그라운드 작업 집합이 변경될 때마다 내보내집니다. 작업이 시작되거나, 완료되거나, 종료되거나, 포그라운드 에이전트가 백그라운드로 전환되거나, 작업의 `description`, `ambient` 또는 `parent_task_id` 필드가 변경될 때입니다. 각 항목의 `parent_task_id` 필드는 이를 정의하고 버전 요구 사항을 설명하는 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)를 참조하세요.
5850 5869
5851`tasks` 배열은 전체 라이브 집합입니다. `task_started` 및 `task_notification` 이벤트를 쌍으로 맞추는 대신 각 페이로드로 캐시된 집합을 교체하세요. 그러면 다음 멤버십 변경이 놓친 이벤트를 바로잡습니다.5870`tasks` 배열은 전체 라이브 집합입니다. `task_started` 및 `task_notification` 이벤트를 쌍으로 맞추는 대신 각 페이로드로 캐시된 집합을 교체하세요. 그러면 다음 멤버십 변경이 놓친 이벤트를 바로잡습니다.
5852 5871
5853이러한 작업별 이벤트에 대한 순서는 지정되지 않으므로, 두 스트림을 상관시키지 마세요.5872작업이 종료되면 해당 작업의 [`task_updated`](#sdktaskupdatedmessage) 및 [`task_notification`](#sdktasknotificationmessage)이 목록에서 해당 작업을 제거하는 `background_tasks_changed`보다 먼저 도착합니다. 그 외에는 작업별 이벤트에 대한 순서가 지정되지 않습니다.
5854 5873
5855시작 시 아무것도 내보내지지 않습니다. 세션의 CLI 프로세스가 시작되거나 다시 시작될 때마다 빈 집합으로 재설정하고 다음 멤버십 변경이 다시 채우도록 하세요.5874시작 시 아무것도 내보내지지 않습니다. 세션의 CLI 프로세스가 시작되거나 다시 시작될 때마다 빈 집합으로 재설정하고 다음 멤버십 변경이 다시 채우도록 하세요.
5856 5875
5867 task_type: string;5886 task_type: string;
5868 subagent_type?: string;5887 subagent_type?: string;
5869 description: string;5888 description: string;
5889 parent_task_id?: string;
5870 ambient?: boolean;5890 ambient?: boolean;
5871 }[];5891 }[];
5872 uuid: UUID;5892 uuid: UUID;
