Herramientas de borrado de contexto y terminal

Use session.history.clearContext cuando un host necesite reemplazar el contexto de conversación actual sin reemplazar la sesión. Entre los usos típicos se incluyen las transferencias y las directivas del ciclo de vida del contexto gestionado por el host.

En este artículo

Borrar el contexto es distinto de crear una nueva sesión: conserva la identidad de la sesión, los mensajes del sistema y del desarrollador, la configuración y el registro de eventos, mientras elimina la conversación visible para el modelo.

Importante

clearContext es un primitivo de controlador de herramientas. El tiempo de ejecución rechaza las llamadas realizadas sin una llamada de herramienta en curso, las llamadas con un mensaje de inicio vacío y las llamadas en sesiones remotas.

Definición de una herramienta de borrado de contexto

Una herramienta adecuada para borrar el contexto debe ser de línea de comandos. De lo contrario, el bucle del agente podría realizar otra llamada al modelo en la ventana recién despejada antes de iniciar el turno con mensaje de inicio.

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.`;
      },
    }),
  ],
});

El elemento requerido prompt se convierte en el primer mensaje del usuario en el nuevo contexto. Un borrado correcto emite session.context_cleared con el número de mensajes eliminados y el mensaje inicial.

Comportamiento de la herramienta de línea de comandos

isTerminal finaliza el turno actual del agente solo cuando la herramienta se ejecuta con éxito. Un error, denegación, rechazo, tiempo de espera o error de validación de entrada permanece visible para el modelo para que pueda recuperarse o volver a intentarlo.

La opción sigue las convenciones de nomenclatura de cada idioma:

SDKOpción de herramienta
Node.jsisTerminal
Pythonis_terminal
IrIsTerminal
.NETCopilotToolOptions.IsTerminal
Java
ToolDefinition.isTerminal(true) o @CopilotTool(isTerminal = true)
Óxidowith_is_terminal(true)

Utiliza la terminalidad solo para herramientas cuya finalización satisfactoria deba poner fin al turno. Las herramientas ordinarias deben dejarla sin configurar.