AgentsVille

Getting started

Your first NPC

An NPC is a named, reusable character you own: a Job Title, a description, a system prompt, and optionally a Provider and Model of its own. Once it exists you hold Conversations with it, and you keep holding them — the NPC is the thing that persists, not any one Conversation.

This page creates one and talks to it. It assumes you have registered on a Village and are signed in.

Create it

Go to the NPCs page and press New NPC. A new NPC is made in five steps:

  1. Start: pick a Template to copy, or Start blank.
  2. Identity: portrait, name, Job Title and description.
  3. Instructions: the system prompt, and any Tools to grant.
  4. Model: Provider and Model or Levels, and Thinking.
  5. Review: everything on one page. Create NPC saves it.

Next and Back move between them. Only the name is required, and it holds you on Identity until you give one. The two things that decide how useful the NPC turns out are the Job Title and the system prompt. Editing an NPC later shows every field in one form instead.

Pick a name you would actually say out loud. "Release notes editor" beats "NPC 2".

Give it a Job Title

The Job Title is what the NPC is for, in the words you would use to introduce it to a colleague: technical writer, on-call triager, contract reviewer. It is shown wherever the NPC is listed, which is the whole point — a Village with eight NPCs in it is only navigable if you can tell at a glance which one to open.

The description is a sentence underneath it, for anything the Job Title alone leaves ambiguous: "Turns merged pull requests into release notes."

Neither of these is sent to the model as instructions. They are for you.

Write the system prompt

The system prompt is the NPC's standing instructions — what it does, how it should do it, and what it should not do. It applies to every Conversation you ever hold with this NPC, so write the parts that are always true and leave the one-off detail for the Messages themselves.

A decent first prompt is two or three sentences. What the job is, what good output looks like, and any hard constraint that matters:

You turn merged pull requests into short release notes. One line per change, written for someone who does not read the diff. Never invent a change that is not in the input.

You can edit it later, and editing it affects the NPC's next reply — including in Conversations you have already started.

Pick a Provider and Model

The Provider is the service that runs the model: Anthropic or OpenAI today. The Model is the identifier of one model that Provider offers.

The default choice is to inherit the Village default, which is the pair the Operator set for the whole instance. An NPC that inherits has no Model of its own, so when the Operator moves the Village onto something newer, this NPC's next reply follows without you editing anything. That is the right setting for most NPCs.

Name a Provider explicitly when this particular NPC needs something different — a stronger model for the job that warrants it, a cheaper one for the job that does not. Choosing a Provider reveals a Model list; if the model you want is not in it, choose the option for another model and type the id. AgentsVille never checks a model id against a catalogue, so a model released this morning is usable this morning.

If you name a Provider whose key the Operator has not configured, the reply is refused before the stream opens, with a message naming the Provider. It is not a silent failure halfway through.

Choosing models goes into which to reach for.

Decide whether it thinks

Thinking is off by default. Turned on, the NPC's reasoning arrives as its own Part of the Message, visibly separate from the answer and collapsed until you open it — which is how you tell a considered answer from a confident guess.

It costs extra tokens on every Message, and not every model supports it. Leave it off for an NPC doing something mechanical; turn it on for one whose judgement you need to audit. Three levels are offered, from brief to thorough.

Hold a Conversation

Save the NPC and open it. You land straight in a Conversation — the most recent one if you have talked to this NPC before, a fresh one if you have not. Type in the box at the bottom and send.

The reply streams in as it is produced, and it arrives as Parts rather than one opaque block: text you read, reasoning if you enabled it, and — once the NPC has Tools — each Tool call in order, with what was sent and what came back. A call that fails renders as failed instead of vanishing. Reload the page and the transcript comes back from the database exactly as it streamed.

You can hold as many Conversations with the same NPC as you like. Start another from the list beside the transcript, and use one per piece of work: they are cheap, and a Conversation about one thing stays easier to come back to than a Conversation about six.

What to do next

  • NPC — what else an NPC can hold: Tools, Skills, a Sandbox, and Memory.
  • Choosing models — which Provider and Model to give which job.