Write a profile or a pack

The profile format: what an account is, which tool plays which role, the client card, monitors, reports and what auto-answer may read.

A profile tells ChatPilot what it knows about a kind of system or one product. A pack is a folder of profiles for one product. How ChatPilot picks one for a system is in Profiles, packs and REST APIs; this page is about writing them.

Profiles are data only: names and plain-words conditions, no code and no keys. ChatPilot reads every figure through the system's own read tools, with the usual approval rules. Unknown keys are refused, so a typo shows up instead of being ignored.

A pack

A pack is a folder (or a git repository) with:

pack.yaml (optional): pack, title, version, description;
one *.yaml file per profile, in the folder or in a profiles/ folder inside it.

Check it, install it and see what ChatPilot made of it:

chatpilot profiles check my-pack/
chatpilot profiles install my-pack/
chatpilot profiles

check lists every problem with its key, without installing anything. Installing copies only data files (profiles, pack.yaml, README, LICENSE). chatpilot profiles remove <pack> takes it out again. A profile of your own, outside a pack, goes into the profiles folder in ChatPilot's settings folder.

A profile, key by key

Key	What it says
`profile`	the id: lowercase letters, digits, `-` `_` `.`
`title`, `description`	shown in the panel
`category`	`ad_platform`, `crm`, `shop`, `helpdesk`, `finance`, `projects` or `other`
`matches`	when it fits a system: `tools_all`, `tools_any`, `url` and `name` patterns. More conditions win over fewer
`perspective`	`operator` (one login for many accounts, each bound to a client's chat; the usual) or `own_account` (the key is the user's own account: the card shows on Today as My account)
`account`	what an account is: `kinds`, `about`, and `lookup: {tool, arg, by}` to find one by id, e-mail, phone, domain, company or name, with `name_field`, `id_field` and `id_arg`
`roles`	which read tool gives what: `balance: get_account.balance`. Only the roles of the category
`card`	the client card's fields: a role, a `role.field`, or `{label, role, field, args}` with fixed arguments such as `{period: today}`
`monitors`	`{id, title, role, when, every, severity}` checks, `every` at least `5m`. They always start off
`stop_loss`	a monitor plus the one tool that pauses what it found, and the tool Resume runs. Never money, a budget, a bid or a delete
`reports`	scheduled reports for bound chats, `every: "mon 09:00"`. Always drafts first
`pages`	ready-made report pages, from words or with their widgets
`questions`	example questions clients ask
`autopilot_answers`	the roles auto-answer may read for the chat's own account
`actions`	CRM only: the tools behind Save as note and Move stage
`pipeline`	CRM only: the order of the stages, and which ones count as won or lost
`api`	a REST API described as read tools, for a system without MCP: see Describe a REST API

Leave out matches for a general profile of a category. A role whose tool the system doesn't have stays empty and is listed as missing.

What auto-answer may read

Auto-answer never gets tools. It asks for a role from autopilot_answers, and ChatPilot runs that role's read tool itself, for the chat's own account only. For that to work:

the account's lookup must find exactly one record with an id;
a role about the whole account needs a tool with an argument naming the account (such as customer_id or email). ChatPilot fills it in, the AI never does;
a role about one item (an order, a ticket) is used only when the answer shows whose it is, and that is the chat's account;
figures over time need a period argument (from and to, date or since).

Fields named like margin, profit, markup, commission, internal or notes never reach a client's answer.

A system's own profile

A connected system can offer its own profile as an MCP resource, of the type application/vnd.chatpilot.profile+json. ChatPilot reads it when it connects and on Learn again, checks it like a pack's profile and uses it for that system only. A pack or your own profile that fits the system wins over it.

Keep packs for one product apart

A product's own pack belongs to that product's makers or users, as its own folder or git repository: chatpilot profiles install <git URL> installs it from there. ChatPilot itself only ships general profiles and a few packs for well-known systems.

Checked against ChatPilot 0.1.0b1. Report a problem with this page