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` diz por que uma notificação `scheduled-trigger` disparou, como um token curto em minúsculas, como `scheduled`, `manual`, `retry`, `catch_up` ou `api`. Os servidores da Anthropic o definem nas entregas de uma [rotina](/docs/pt/routines), e sua aplicação o define quando declara uma execução agendada. Está ausente quando nenhum dos dois enviou um. Requer TypeScript Agent SDK v0.3.280 ou posterior.2417`fireReason` diz por que uma notificação `scheduled-trigger` disparou, como um token curto em minúsculas, como `scheduled`, `manual`, `retry`, `catch_up` ou `api`. Os servidores da Anthropic o definem nas entregas de uma [rotina](/docs/pt/routines), e sua aplicação o define quando declara uma execução agendada. Está ausente quando nenhum dos dois enviou um. Requer TypeScript Agent SDK v0.3.280 ou posterior.
2417 2418
2419Uma tarefa em segundo plano pode ser executada mais de uma vez sob o mesmo `task_id`, como quando o Claude [retoma um subagente](/docs/pt/agent-sdk/subagents#resume-subagents). Cada execução tem seu próprio [`run_id`](#sdktaskstartedmessage). Quando a notificação de uma execução chega à sua sessão como uma mensagem de usuário, `runId` no origin `task-notification` dessa mensagem contém o mesmo valor. Uma notificação pode chegar depois que a próxima execução da tarefa já começou e, ainda assim, carrega o ID da execução anterior. Para saber a qual execução um turno pertence, compare `runId`, não `task_id`. Requer TypeScript Agent SDK v0.3.292 ou posterior.
2420
2418<h4 id="declare-a-scheduled-run">2421<h4 id="declare-a-scheduled-run">
2419 Declarar uma execução agendada2422 Declarar uma execução agendada
2420</h4>2423</h4>
3263 Tipos de Entrada de Ferramenta3266 Tipos de Entrada de Ferramenta
3264</h2>3267</h2>
3265 3268
32663269Documentação de esquemas de entrada para todas as ferramentas integradas do Claude Code. Esses tipos são exportados de `@anthropic-ai/claude-agent-sdk/sdk-tools` e podem ser usados para interações de ferramenta type-safe.Documentação de esquemas de entrada para ferramentas integradas do Claude Code. Esses tipos são exportados de `@anthropic-ai/claude-agent-sdk/sdk-tools` e podem ser usados para interações de ferramenta type-safe.
3267 3270
3268<h3 id="toolinputschemas">3271<h3 id="toolinputschemas">
3269 `ToolInputSchemas`3272 `ToolInputSchemas`
4079 Tipos de Saída de Ferramentas4082 Tipos de Saída de Ferramentas
4080</h2>4083</h2>
4081 4084
40824085Documentação dos esquemas de saída para todas as ferramentas Claude Code integradas. Esses tipos são exportados de `@anthropic-ai/claude-agent-sdk/sdk-tools` e representam os dados de resposta reais retornados por cada ferramenta.Documentação dos esquemas de saída para as ferramentas Claude Code integradas. Esses tipos são exportados de `@anthropic-ai/claude-agent-sdk/sdk-tools` e representam os dados de resposta reais retornados por cada ferramenta.
4083 4086
4084<h3 id="tooloutputschemas">4087<h3 id="tooloutputschemas">
4085 `ToolOutputSchemas`4088 `ToolOutputSchemas`
5732 `SDKTaskNotificationMessage`5735 `SDKTaskNotificationMessage`
5733</h3>5736</h3>
5734 5737
57355738Notificação quando uma tarefa em segundo plano é concluída, falha ou é parada. Tarefas em segundo plano incluem comandos Bash `run_in_background`, watches [Monitor](#monitor) e subagentes em segundo plano. Para o campo `ambient`, veja [`SDKTaskStartedMessage`](#sdktaskstartedmessage), que o define e seu requisito de versão.Notificação quando uma tarefa em segundo plano é concluída, falha ou é parada. Tarefas em segundo plano incluem comandos Bash `run_in_background`, watches [Monitor](#monitor) e subagentes em segundo plano. Para os campos `run_id` e `ambient`, veja [`SDKTaskStartedMessage`](#sdktaskstartedmessage), que os define e seus requisitos de versão.
5736 5739
5737```typescript theme={null}5740```typescript theme={null}
5738type SDKTaskNotificationMessage = {5741type SDKTaskNotificationMessage = {
5739 type: "system";5742 type: "system";
5740 subtype: "task_notification";5743 subtype: "task_notification";
5741 task_id: string;5744 task_id: string;
5745 run_id?: string;
5742 tool_use_id?: string;5746 tool_use_id?: string;
5743 status: "completed" | "failed" | "stopped";5747 status: "completed" | "failed" | "stopped";
5744 reason?: "worker_restart";5748 reason?: "worker_restart";
5911 type: "system";5915 type: "system";
5912 subtype: "task_started";5916 subtype: "task_started";
5913 task_id: string;5917 task_id: string;
5918 run_id?: string;
5914 tool_use_id?: string;5919 tool_use_id?: string;
5915 description: string;5920 description: string;
5916 task_type?: string;5921 task_type?: string;
5923};5928};
5924```5929```
5925 5930
5931`run_id` identifica uma execução da tarefa. Quando uma tarefa é executada novamente sob o mesmo `task_id`, como um [subagente que Claude retoma](/docs/pt/agent-sdk/subagents#resume-subagents), a nova execução recebe um novo `run_id`. O campo requer Agent SDK v0.3.292 ou posterior. Use-o para manter separadas as execuções de uma tarefa:
5932
5933* **Associar mensagens a uma execução**: as mensagens `task_started`, [`task_progress`](#sdktaskprogressmessage), [`task_updated`](#sdktaskupdatedmessage) e [`task_notification`](#sdktasknotificationmessage) de uma execução carregam o mesmo `run_id`. A entrada da execução em cada [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) também o carrega, assim como o [`runId`](#task-notification-subkinds) na origem da mensagem de usuário que entrega a notificação da execução.
5934* **Detectar uma mensagem atrasada**: comparados como strings simples, os IDs de execução de uma tarefa são ordenados na ordem em que as execuções começaram, então uma mensagem cujo `run_id` fica antes da execução que você está exibindo vem de uma execução anterior. Trate o valor como opaco, exceto por essa comparação.
5935* **Recorrer a `task_id`**: quando uma mensagem não carrega `run_id`, como a `task_notification` que uma sessão retomada emite para encerrar uma tarefa que o processo anterior iniciou, atribua-a por `task_id`.
5936
5937Por exemplo, estas três mensagens, reduzidas aos seus campos de identificação, vêm de um subagente em segundo plano que Claude retomou uma vez. As duas mensagens `task_started` compartilham um `task_id`, e a notificação que encerrou a primeira execução carrega o ID da primeira execução:
5938
5939```json theme={null}
5940{"subtype": "task_started", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubbs7i8-6f0c2d41"}
5941{"subtype": "task_notification", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubbs7i8-6f0c2d41", "status": "completed"}
5942{"subtype": "task_started", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubc18m1-b7719e05"}
5943```
5944
5926`ambient` é `true` para tarefas que não fazem parte do trabalho da sessão, como tarefas que Claude Code executa para sua própria operação. Watchers de atualização ao vivo também são ambient, incluindo watchers que o usuário pediu. Exclua tarefas ambient de indicadores de atividade. O campo requer Agent SDK v0.3.247 ou posterior.5945`ambient` é `true` para tarefas que não fazem parte do trabalho da sessão, como tarefas que Claude Code executa para sua própria operação. Watchers de atualização ao vivo também são ambient, incluindo watchers que o usuário pediu. Exclua tarefas ambient de indicadores de atividade. O campo requer Agent SDK v0.3.247 ou posterior.
5927 5946
5928`ambient` também aparece em [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) e em entradas [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage).5947`ambient` também aparece em [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) e em entradas [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage).
5946 `SDKTaskProgressMessage`5965 `SDKTaskProgressMessage`
5947</h3>5966</h3>
5948 5967
59495968Emitido periodicamente enquanto um subagente ou tarefa em segundo plano está em execução.Emitido periodicamente enquanto um subagente ou tarefa em segundo plano está em execução. Para o campo `run_id`, veja [`SDKTaskStartedMessage`](#sdktaskstartedmessage), que o define e seu requisito de versão.
5950 5969
5951Para uma tarefa de subagente, o campo `summary` carrega um resumo de progresso gerado por modelo e é preenchido apenas quando [`agentProgressSummaries`](#options) está ativado. Para uma [chamada de ferramenta MCP em segundo plano](/docs/pt/mcp#automatic-backgrounding-of-long-tool-calls), `summary` carrega o progresso mais recente relatado pelo servidor MCP e não depende dessa opção.5970Para uma tarefa de subagente, o campo `summary` carrega um resumo de progresso gerado por modelo e é preenchido apenas quando [`agentProgressSummaries`](#options) está ativado. Para uma [chamada de ferramenta MCP em segundo plano](/docs/pt/mcp#automatic-backgrounding-of-long-tool-calls), `summary` carrega o progresso mais recente relatado pelo servidor MCP e não depende dessa opção.
5952 5971
5955 type: "system";5974 type: "system";
5956 subtype: "task_progress";5975 subtype: "task_progress";
5957 task_id: string;5976 task_id: string;
5977 run_id?: string;
5958 tool_use_id?: string;5978 tool_use_id?: string;
5959 description: string;5979 description: string;
5960 subagent_type?: string;5980 subagent_type?: string;
5974 `SDKTaskUpdatedMessage`5994 `SDKTaskUpdatedMessage`
5975</h3>5995</h3>
5976 5996
59775997Emitido quando o estado de uma tarefa em segundo plano muda, como quando ela faz a transição de `running` para `completed`. Mescle `patch` em seu mapa de tarefas local com chave `task_id`. O campo `end_time` é um timestamp de época Unix em milissegundos, comparável com `Date.now()`.Emitido quando o estado de uma tarefa em segundo plano muda, como quando ela faz a transição de `running` para `completed`. Mescle `patch` em seu mapa de tarefas local com chave `task_id`. O campo `end_time` é um timestamp de época Unix em milissegundos, comparável com `Date.now()`. Para o campo `run_id`, veja [`SDKTaskStartedMessage`](#sdktaskstartedmessage), que o define e seu requisito de versão.
5978 5998
5979```typescript theme={null}5999```typescript theme={null}
5980type SDKTaskUpdatedMessage = {6000type SDKTaskUpdatedMessage = {
5981 type: "system";6001 type: "system";
5982 subtype: "task_updated";6002 subtype: "task_updated";
5983 task_id: string;6003 task_id: string;
6004 run_id?: string;
5984 patch: {6005 patch: {
5985 status?: "pending" | "running" | "completed" | "failed" | "killed";6006 status?: "pending" | "running" | "completed" | "failed" | "killed";
5986 description?: string;6007 description?: string;
5998 `SDKBackgroundTasksChangedMessage`6019 `SDKBackgroundTasksChangedMessage`
5999</h3>6020</h3>
6000 6021
60016022Emitido sempre que o conjunto de tarefas em segundo plano ativas muda: uma tarefa inicia, é concluída ou é eliminada; um agente em primeiro plano é colocado em segundo plano; ou o campo `description`, `ambient` ou `parent_task_id` de uma tarefa muda. Para o campo `parent_task_id` em cada entrada, veja [`SDKTaskStartedMessage`](#sdktaskstartedmessage), que o define e seu requisito de versão.Emitido sempre que o conjunto de tarefas em segundo plano ativas muda: uma tarefa inicia, é concluída ou é eliminada; um agente em primeiro plano é colocado em segundo plano; ou o campo `description`, `ambient` ou `parent_task_id` de uma tarefa muda. Para os campos `run_id` e `parent_task_id` em cada entrada, veja [`SDKTaskStartedMessage`](#sdktaskstartedmessage), que os define e seus requisitos de versão.
6002 6023
6003O array `tasks` é o conjunto completo ativo. Substitua qualquer conjunto em cache por cada payload em vez de emparelhar eventos `task_started` e `task_notification`, para que a próxima mudança de associação corrija qualquer evento que você tenha perdido.6024O array `tasks` é o conjunto completo ativo. Substitua qualquer conjunto em cache por cada payload em vez de emparelhar eventos `task_started` e `task_notification`, para que a próxima mudança de associação corrija qualquer evento que você tenha perdido.
6004 6025
6016 subtype: "background_tasks_changed";6037 subtype: "background_tasks_changed";
6017 tasks: {6038 tasks: {
6018 task_id: string;6039 task_id: string;
6040 run_id?: string;
6019 task_type: string;6041 task_type: string;
6020 subagent_type?: string;6042 subagent_type?: string;
6021 description: string;6043 description: string;