AgentsVille

Concepts

NPC

An NPC is a named, reusable character you create and then put to work. It has a name, a job title, a description, an optional system prompt, a portrait, and either a Provider and Model of its own or one or more Levels. It belongs to one Player, and it can be given Skills, Tools, a Sandbox and Memory.

An NPC is not a one-off prompt. You write it once and hold as many Conversations with it as you like, and what you teach it persists between them.

The four fields

Name. What you call it. Pike, Wren, Ledger.

Job title. What the NPC is for, in the words you would use to introduce it — Engineer, Researcher, Editor. It is shown wherever NPCs are listed, so it is what tells you which one to open when you have eleven of them.

Description. A sentence about what it does. "Writes and runs code on its own machine, and shows its work."

System prompt. How it should work: standards, preferences, what it should refuse to guess at. This is the long field, and it is the one you will edit.

Only the name is required. Because the first three reach the model on every turn (below), an NPC with a name, a job title and a description and no system prompt at all is a working NPC; the system prompt is for everything beyond who it is.

Draft from identity

The NPC form's Draft from identity button hands the name, job title and description to a model — the Village default, or the cheapest mapped Level — and fills in the rest: a system prompt, the Levels the job needs, and which of your Tools and Skills it should hold. It saves nothing. Everything it writes is editable before you create the NPC, and each suggested Tool is a checkbox, granted only if it is still ticked when you save.

Portrait

Every NPC has one of fifty pixel-art portraits, shown next to its name in lists, in the Party bar and above its replies in a Party. A new NPC is given one at random, preferring portraits none of your other NPCs wear yet; Shuffle and Choose on the form change it.

The first three reach the model

Name, job title and description are not just labels on a card. They are placed at the top of the NPC's prompt, above your system prompt, as a short "Who you are" section — unconditionally, in every Conversation:

## Who you are
You are Pike, Engineer. Writes and runs code on its own machine, and shows itswork.

Identity goes first because it is the most stable thing in the prompt: your instructions should read as elaboration on an established character rather than as a competing one. If your system prompt already opens with "You are Pike, an engineer…", the NPC now hears it twice — harmless, but worth removing.

In a Party, each NPC also sees a roster of the others. Roster entries keep only the first sentence of a description, or 160 characters, whichever comes first, because a roster is re-sent on every single turn. An NPC's own description is never truncated. See ADR 0017.

Provider and Model, or Levels

Leave both blank and the NPC runs on its Levels — the model slots the Operator maps in Settings — or, with no Levels, on the Village default. Change either and the NPC's next reply follows it, with no edit to the NPC. See Choosing models.

Set both and the NPC ignores the default. They move together: a model identifier only means something to the Provider that issued it, so AgentsVille will not let you set one without the other.

The model box is free text on purpose. A Provider may ship a model before AgentsVille has heard of it, and you should not have to wait for a release to use it. If the Provider you name has no key configured, the NPC is refused before the reply starts, with a message naming the Provider.

See Choosing models.

Thinking

Each NPC has a thinking level: off, low, medium or high. Off is the default, because reasoning costs tokens and nothing in AgentsVille enforces a budget. Turn it on for the NPC whose work you actually need to audit, and leave it off for the rest. See Reading thinking and tool calls.

What you give it

An NPC on its own can only produce text. What makes it useful is what you grant it, per NPC, nothing implicit:

Next