Skip to main content
Skip to content

Alterando ferramentas durante uma sessão

Um aplicativo pode substituir as ferramentas fornecidas para uma sessão ativa sem recriá-la. Por exemplo, uma página da Web pode oferecer ferramentas diferentes à medida que o usuário navega ou um cliente que assume uma sessão pode trazer suas próprias ferramentas. Cada SDK substitui o conjunto de ferramentas completo do cliente e os handlers que o atendem em uma chamada.

Experimental. A substituição da ferramenta encapsula o RPC experimental session.tools.set e requer um runtime compatível com ele.

Substituir as ferramentas desse cliente

Informe o conjunto completo de ferramentas que este cliente deve fornecer. Ele substitui as ferramentas fornecidas pelo cliente quando a sessão foi criada ou retomada ou em uma substituição anterior. Ferramentas internas, MCP e plug-ins, e ferramentas fornecidas por outros clientes conectados à mesma sessão não são afetadas. Passe uma lista vazia para remover todas as ferramentas desse cliente.

As ferramentas são definidas exatamente da mesma forma que para criar uma sessão, e uma ferramenta sem um manipulador se comporta da mesma forma como acontece ali.

Idiomas de código navigation

TypeScript
import { defineTool } from "@github/copilot-sdk";
import { z } from "zod";

const searchIssues = defineTool("search_issues", {
    description: "Search the issues shown on the current page",
    parameters: z.object({ query: z.string().describe("Search text") }),
    handler: async ({ query }) => findIssues(query),
});

// Supply only the tools the current page provides.
await session.setTools([searchIssues]);

// Remove all of this client's tools.
await session.setTools([]);

Quando as novas ferramentas entrarem em vigor

  • Solicitações de modelo. O runtime oferece as novas ferramentas a partir da próxima solicitação de modelo do agente. Essa solicitação pode fazer parte de uma interação que já está em andamento.
  • Tratadores. Assim que o runtime aceitar a substituição, cada chamada de ferramenta que a sessão despacha usará os novos manipuladores. As chamadas que já estão em execução terminam nos manipuladores que as iniciaram.
  • Rejeição. Se o runtime rejeitar a substituição, a chamada falhará e as ferramentas e manipuladores anteriores permanecerão em vigor. O runtime rejeita nomes de ferramentas com caracteres inválidos e nomes que outro cliente conectado já fornece.
  • Pedidos. As substituições simultâneas na mesma sessão são aplicadas uma de cada vez, na ordem em que são feitas.
  • Cancelamento. Em SDKs que permitem cancelar a chamada, cancelá-la enquanto uma substituição anterior ainda está em andamento não envia nada. Depois que a solicitação é enviada, o cancelamento só interrompe a espera: se o runtime aceitar a substituição, os novos manipuladores ainda entrarão em vigor.

Substituindo ferramentas durante uma vez

Uma solicitação de modelo que já está em andamento foi feita com as ferramentas anteriores, portanto, o agente ainda pode chamar uma ferramenta que você acabou de remover. A sessão não atende a essa chamada, pois outro cliente conectado pode fornecer uma ferramenta com o mesmo nome, portanto, a chamada pode permanecer pendente até que o turno seja anulado.

Se uma interação em execução ainda puder chamar uma ferramenta que você remove, substitua as ferramentas enquanto a sessão estiver ociosa, por exemplo, após o evento session.idle, ou aborte a interação primeiro. Substituir o manipulador de uma ferramenta com o mesmo nome é seguro durante um turno: chamadas enviadas após o runtime aceitar a substituição usam o novo manipulador.

Referência do SDK

SDKMétodo
TypeScriptsession.setTools(tools)
Pythonawait session.set_tools(tools)
Gosession.SetTools(ctx, tools)
.NETawait session.SetToolsAsync(tools, cancellationToken)
Java
session.setTools(tools), que retorna um CompletableFuture<Void>
Rustsession.set_tools(tools).await