# Ferramentas de limpeza de contexto e terminal

Use session.history.clearContext quando um host precisar substituir o contexto de conversa atual sem substituir a sessão. Os usos típicos incluem entregas e políticas de ciclo de vida de contexto gerenciadas pelo host.

<!-- markdownlint-disable GHD046 GHD005 -->
<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->

A limpeza de contexto é diferente da criação de uma nova sessão: preserva a identidade da sessão, as mensagens do sistema e do desenvolvedor, a configuração e o log de eventos ao remover a conversa voltada para o modelo.

> [!IMPORTANT]
> `clearContext` é uma primitiva de manipulador de ferramentas. O runtime rejeita chamadas feitas sem uma chamada de ferramenta em andamento, chamadas com um prompt inicial vazio e chamadas em sessões remotas.

## Definir uma ferramenta de limpeza de contexto

Uma ferramenta de limpeza de contexto bem-sucedida deve ser terminal. Caso contrário, o loop do agente poderá fazer outra chamada ao modelo na janela recém-limpa antes de iniciar o turno inicializado.

```typescript
import { approveAll, CopilotClient, defineTool } from "@github/copilot-sdk";
import type { CopilotSession } from "@github/copilot-sdk";
import { z } from "zod";

const client = new CopilotClient();
let session: CopilotSession;

session = await client.createSession({
  onPermissionRequest: approveAll,
  tools: [
    defineTool("clear_context", {
      description: "Clear the conversation and start a fresh context window",
      parameters: z.object({ prompt: z.string() }),
      isTerminal: true,
      defer: "never",
      handler: async ({ prompt }) => {
        const { messagesCleared } =
          await session.rpc.history.clearContext({ prompt });
        return `Cleared ${messagesCleared} messages.`;
      },
    }),
  ],
});
```

O necessário `prompt` se torna a primeira mensagem de usuário no novo contexto. Uma limpeza bem-sucedida emite `session.context_cleared` com o número de mensagens removidas e a mensagem inicial.

## Comportamento da ferramenta Terminal

`isTerminal` encerra a interação atual do agente somente quando a ferramenta for executada com sucesso. Um erro de falha, negação, rejeição, tempo limite ou validação de entrada permanece visível para o modelo para que ele possa recuperar ou tentar novamente.

A opção segue as convenções de nomenclatura de cada idioma:

| SDK | Opção de ferramenta |
|---|---|
| Node.js | `isTerminal` |
| Python | `is_terminal` |
| Go | `IsTerminal` |
| .NET | `CopilotToolOptions.IsTerminal` |
| Java | 
`ToolDefinition.isTerminal(true)` ou `@CopilotTool(isTerminal = true)` |
| Rust | `with_is_terminal(true)` |

Use terminalidade somente para ferramentas cuja conclusão bem-sucedida deve encerrar o turno. As ferramentas comuns devem deixá-la sem configuração.