Ferramentas de limpeza de contexto e terminal

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.

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.

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.