Talking to an agent

An agent with a persona and no routines or duties is one people talk to, and any agent may be talked to. A conversation with an agent speaks in its persona and reaches only what its conversation block allows:

agents/jonathon.yml

name: jonathon
job: Help people read scripture, and be known while they do.
routing: Ask me about the Bible, a passage, a person in the text, faith or doubt.
persona: realm-bible/jonathon
conversation:
  realms: [realm-bible]                  # default: the realm that ships the agent
  builtins: [memory, views]              # host tools kept; name the fewest the job needs
  skills: [diagrams]                     # skills by name, beside what realms and builtins bring
  llm: chat_best                         # an LLM role, never a model; default: the host's chat role
  sampling:                              # what a caller may ask for; omitted = the role's own settings
    maxTokens: 2000
authority:
  default: never

conversation field	Meaning
realms	The realms the conversation reaches. The host binds the conversation to them and enforces the binding where every call is dispatched, not only in what the model is shown.
builtins	Which of the host’s own tools the conversation keeps, by category: code, graph, views, data, memory, documents, attachments, images, artifacts, apps, host. true keeps all, false none. A host tool in no listed category is dropped. A realm’s own tools are governed by realms, not this. Omitted means all, which is almost never what an agent should have — see Scope it to the job.
skills	Skills brought in by name, in addition to what realms and builtins bring: a host-provided skill, or one the world installed or wrote, that the named builtins categories would otherwise leave out. Three limits. A realm’s skills arrive only with the realm: naming a skill another realm ships, without that realm in realms, is refused, and the refusal says to add the realm. A name brings in a skill and never a tool — host tools stay by category. A name that matches no skill is a validation error for the agent, listing the skills that exist. See Scope it to the job.
llm	The LLM role the conversation runs on. A realm never names a model, and a caller cannot choose one.
sampling.maxTokens	The most a caller’s max_tokens may ask for.

sampling declares no temperature. Current models ignore a sampling temperature or reject one, so a host sets none; a temperature an agent file still declares is ignored.

Scope it to the job

An agent’s conversation SHOULD reach the fewest tools its job needs, and a realm SHOULD name its builtins rather than take the default. This is not tidiness. A model chooses among the tools it is shown, and every tool outside the job is one more wrong turn it can take: offered forty tools, a scripture agent reached for entity search, a vector search and a code runner instead of the view that answered, then filled the gap from its own recall — fluent, confident, and wrong. Offered the handful its job needs, the same model on the same question ran the view. A narrow scope is what lets a small, cheap model be a reliable colleague, and no model is reliable choosing among tools it should never have seen.

So:

• Start from builtins: [memory, views] for an agent that answers from a realm’s views, and add a category only when the agent cannot do its job without it — and can show it.
• A view that retrieves inside itself (RELEVANT_TO, a producer) needs no documents or graph category; the host runs the retrieval when the view runs.
• Name realms the same way: conversation.realms lists the realms the job draws on, not every realm the world happens to have.
• Name skills with cause. Every skill added is one more choice the model makes on every turn — its description is read, weighed against the question, and sometimes chosen instead of the view that answers. Add a skill when a question the agent must answer needs it, and not because it might come in useful.

What the conversation is offered. Exactly four things: the tools and skills of the realms realms names; the host tools of the categories builtins names, with any host skill that documents one of those categories; the skills skills names; and the few a host keeps on every conversation (its notes and progress reporting). Nothing else — not another realm’s tools or skills, not the world’s own APIs, not a host tool or skill that belongs to no named category. A host SHOULD report the tool surface each turn was offered, so an author can check it, and an author SHOULD check it before judging how the agent behaves: an agent that misbehaves with tools it should not have is a scoping defect first.

Who can be talked to. Only an agent that may work: signed, with a sponsor, active, not off duty, and in a world that is not halted. A host refuses a conversation with any other agent and says which of these is missing, and it checks again on every turn, so standing an agent down ends its conversations at the next message.

What a stage means here. Observing, an agent talks and reads, and every effect it attempts is refused and reported. On duty, what it may change is its signed authority, exactly as for its routines; a conversation borrows no authority from the person talking. Talking never shows the person more than they could see themselves: the agent sees the intersection of its own scope and the speaker’s access.

A caller can narrow, never widen. Everything a caller may ask for (below) tightens what the agent does or what is shown. Nothing a caller sends adds a realm, a tool, a verb or a model.