Kwirth AI toolsets

What is an AI toolset?

A tool is a function the model can decide to call — list the pods of a namespace, read the last lines of a log. The model chooses whether to call it and with what arguments; Kwirth runs it and hands back the result.

An AI toolset is a packaged, installable group of those tools. It is an extension like any other: an id, a version, a description, installed and removed from its own manager, hot-loaded with no pod restart.

Why a group and not individual tools? Because a tool on its own has no useful boundary — delete a pod only makes sense next to list pods and describe pod. Toolsets are thematic, and that is what makes them governable: you hand out a theme, not a list of function names. If you ever need to govern one single tool, package a toolset containing exactly that tool — there is no such thing as a loose tool in Kwirth.

Two axes, not one

Every tool declares two independent things beyond its name and description. Keeping them apart is how dangerous tools stop being treated as harmless:

One axis says what it touches, the other what it reveals, and the real toolsets show how far apart they can be. Deleting a pod is write but public: it changes the cluster and its answer reveals nothing. Reading a ConfigMap is read but secret: it changes nothing and returns raw values — and a ConfigMap is exactly where credentials end up when somebody skips the Secret.

Available toolsets

The tools Kwirth has always had, now split so they can be granted separately. Each one declares what it needs from the host, and Kwirth provisions only that: a toolset that does arithmetic never receives a Kubernetes client.

Where tools are switched on

Installing a toolset makes it available; it does not give it to anybody. Each AI-enabled channel is assigned an ordered list of toolsets, and may switch off individual tools inside them:

So a channel with no configuration has no tools at all — an AI channel you just installed can reason and write prose, but it cannot see your cluster until you say so. That is the point: capability is granted, never assumed.

The order is configuration, not decoration. When two toolsets bring the same tool name nothing is renamed — the first one assigned serves it and the other is shadowed. Reordering the list therefore changes which code runs. Every invocation is traced with the toolset that served it, precisely so this is never a guess.

Build your own toolset

A toolset is a small package: a manifest declaring what it needs, and a list of tools with their schema and an execute. Nothing else.

export const toolset = {
    id: 'my-toolset',
    requires: [ECapability.K8S],          // only what you declare is provisioned
    tools: [
        {
            name: 'list_namespaces',
            description: 'Lists the namespaces of the cluster',
            effect: EToolEffect.READ,     // observes, changes nothing
            sensitivity: ESensitivity.PUBLIC,
            parameters: { /* zod schema the model must fill */ },
            execute: async (args, host) => {
                host.trace('list_namespaces', {})          // always available
                return await host.k8s.coreApi.listNamespace()
            }
        }
    ]
}

The Kubernetes clients your tool receives are the ones Kwirth itself uses — the same authenticated instances, not new connections. What a toolset does not get is equally deliberate: the service-account token, senders and webhooks stay out. The set can be widened later, but on purpose rather than handed over wholesale.

Point Kwirth at your build while you develop it, the same way as any other extension:

{
  "aitoolsets": {
    "my-toolset": "../aitoolsets/my-toolset/dist"
  }
}