Config tools

Introduction

Config tools let a conversation configure the product: “create an agent that summarises tickets” becomes a validated agent definition, without the user opening the editor. They are for products where users shape their own assistants.

Turning them on

app.module.ts

PilotooModule.forRoot({
  configTools: { profiles: true, skills: true },
});

A SaaS server that stores model profiles itself and wants agents and skills only passes { profiles: false, skills: true }.

The agent tools come with any flag. They need the agent editor, so agentDefinitionStore must not be null. Hosts whose profiles do not come from files (modelProfileSource) leave profiles off.

Giving an agent the tools

The tools are registered opt-in, so tools: null never gives them. Only an agent naming them has them.

.pilotoo/agents/builder.yaml (excerpt)

runtime:
  tools: [config_overview, config_read_agent, config_save_agent, config_save_skill]

The tools

Tool	Registered when	Does
config_overview	any configTools	Lists the agents, model profiles, tools, built-in tools and skills, with the invalid ones and why. Lists the caller’s effective skills.
config_read_agent	any configTools	Reads one agent.
config_save_agent	any configTools	Takes the whole YAML; creates or replaces by id.
config_delete_agent	any configTools	Deletes an agent.
config_read_profile, config_save_profile	profiles: true	Reads and writes PILOTOO_CONFIG_DIR/profiles.
config_read_skill, config_save_skill	skills: true	On the skills directory or, with a tenant skill layer, on the caller’s effective skills.

With a tenant skill layer (see Skills), config_read_skill reads the caller’s tenant folder, then global, then system. config_save_skill writes only <tenantDir>/<tenant>/<name>/. Saving a name that global or system holds creates the tenant’s override, keeping the overridden skill’s reference files when files is left out. It never writes those layers.

Limiting what an agent can grant

configTools.grantableBuiltins is a list of built-in tool names (every one when omitted) that limits which built-ins config_save_agent may newly give an agent. One outside it is refused with a Not done: message that names it. A built-in the agent already had stays through a resave. The human editor is not bound by it.

Caution

A host whose agents run unsandboxed, such as the local backend, should leave out execute, write_file, edit_file and delete, which are a shell on the user’s machine. @pilotoo/local-server takes the option in the host’s configTools, which replaces its default ({ profiles: true, skills: true }), so name the flags too.

What the kit guarantees

• Every tool refuses a caller the agent manager would refuse (AGENT_MANAGER_ROLES, see Agents) and a call without a caller.
• An agent is validated by the manager exactly as the editor’s save.
• A profile is written only when the boot check would accept it (the schema for its provider’s kind, a provider this process loaded). A missing key is a warning in the answer.
• A skill is staged in a hidden folder and read back with DeepAgents’ parser before it replaces the old one, so an unparseable frontmatter is refused rather than silently dropped.
• A refusal is the tool’s answer, Not done: <reason>, and writes nothing.
• Files are written beside their target and renamed over it.

Using them outside the module

import { createConfigTools } from '@pilotoo/agent-runtime';

const tools = createConfigTools({ agents, profiles, skills, grantableBuiltins });

agents is an AgentManager, profiles a ModelProfileStore (createFileModelProfileStore) and skills a SkillStore (createDirectorySkillStore, or createTenantSkillStore for the tenant layer). The tools pass the caller’s identity to them.

Next steps

• Agents for what an agent definition holds.
• Skills for the layers config_save_skill writes to.
• Hosting it from another app for the local backend’s defaults.