上下文清除和终端工具

上下文清除不同于创建新会话：删除面向模型的会话时，它会保留会话标识、系统和开发人员消息、配置和事件日志。

重要

clearContext 是工具处理程序基元。运行时会拒绝以下调用：在没有正在进行的工具调用时发起的调用、初始提示词为空的调用，以及针对远程会话发起的调用。

定义上下文清除工具

一个有效的上下文清除工具应该是终极的。否则，在开始预置轮次之前，代理循环可能会基于刚清空的上下文窗口再次调用模型。

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

所需的 prompt 将成为新上下文中的第一条用户消息。清除成功后，会发出 session.context_cleared，并附带已移除的消息数量和初始消息。

终端工具的行为

isTerminal 仅当工具成功时，才会结束当前代理轮次。失败、拒绝、拒绝、超时或输入验证错误对模型仍可见，以便它可以恢复或重试。

此选项遵循每个语言的命名约定：

SDK	工具选项
Node.js	`isTerminal`
Python	`is_terminal`
Go	`IsTerminal`
.NET	`CopilotToolOptions.IsTerminal`
Java
`ToolDefinition.isTerminal(true)` 或 `@CopilotTool(isTerminal = true)`
Rust	`with_is_terminal(true)`

仅对那些成功完成后应结束当前轮次的工具使用终止属性。常规工具应保持其未设置状态。

在本文中

定义上下文清除工具

终端工具的行为