Several agents

One workspace can run more than one agent, each with its own instructions, tools and knowledge. Which one a visitor gets is decided by the manifest, from whether they are signed in and what their token says about them.

The case it is for: a marketing site and a customer portal that embed the same widget. The anonymous visitor asking about prices and the signed-in customer asking about their own records are not the same conversation, and one set of instructions serving both ends up serving neither. Before this they had to be two workspaces — two manifests, two knowledge bases, two tokens to keep in step.

Key the agents under agents: and add an entry: table:

agents:
  home:
    name: Ana
    instructions: |
      Answer product and pricing questions using knowledge_lookup.
      Nobody here is signed in: never ask for account details.
    tools: [knowledge_lookup]
    knowledge: [public_docs]

  portal:
    name: Ana
    instructions: |
      You are talking to a signed-in customer. Use my_orders and my_documents
      to answer about their own account, and knowledge_lookup for anything else.
    tools: [my_orders, my_documents, knowledge_lookup]
    knowledge: [portal_kb]

  # Each agent names its own knowledge; there is nothing inherited.

entry:
  - { authenticated: false, agent: home }
  - { claims: { role: staff }, agent: staff }
  - { agent: portal }

agent: is the short form of agents: { main: … }, so a workspace with one agent changes nothing and keeps working exactly as it does today.

Give every agent the same name when the split should be invisible. As far as the visitor can tell they are talking to one person the whole time, which is what the platform rules already assume.

The entry table

An ordered list. The first row whose conditions hold wins, and that is the whole rule — there is no specificity, no scoring, nothing to work out. The policy reads top to bottom, and someone who has never used Vatio can check it in a pull request.

Key	Meaning
agent	Required. The agent this row selects
authenticated	true or false — whether the visitor arrived with a valid token
claims	Claim values that must all match; a list means any of them

A row with no conditions matches everyone. The last row must be one, because a visitor who matches nothing would otherwise have nobody to talk to — and anything written after it is unreachable.

Claims are compared as text, so role: 2 in the manifest matches "2" in the token. vatio tools check warns about an agent no row can ever select.

When it is decided

Before the first reply, on every channel. Vatio verifies the token as the conversation opens — a signature check, no network — so the right agent is chosen before the visitor's first message is answered rather than after.

If they sign in mid-conversation, the SDK's identify() runs the table again. Someone who asked a question anonymously, signed in, and came back keeps everything they typed: same thread, same history, and from the next message on, the agent for who they now are.

What it is not

entry: is not a security control, and should not be used as one. A visitor with no valid token has no verified identity, so no access: private tool runs for them whatever agent they land on. A mistake in the table shows someone the wrong prompt; it cannot show them someone else's data.

Protect data with access: private on the tool, always. The entry table is about giving each audience the right conversation.

Knowledge and links per agent

Each agent states its own, even when two of them say the same thing:

agents:
  home:
    instructions: …
    knowledge: [public_docs]
    links:
      pricing: "https://acme.test/pricing"
  portal:
    instructions: …
    knowledge: [portal_kb]
    links: {}                   # hands out no urls at all

There is no workspace-level default to inherit from, and the repetition is deliberate. What an agent knows and which urls it may hand out are the two things you check when it answers wrongly, and an inherited value means looking somewhere else and then working out whether this agent overrode it. It also matters in the prompt: every declared url is listed in it, so a portal agent would otherwise carry a marketing agent's whole link list around without ever handing one out.