Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

11.4 KB
Raw Blame
"""The template language, as an agent needs it to write a document.

A condensed ``docs/TEMPLATES.md``, served by the ``get_template_guide``
operation next to the JSON schema of the room documents this server accepts.
It teaches version 2 (resources with a key and a type), which is what an
agent should write, and what it needs to read a version 1 document it finds.
Keep it in step with the docs when the language changes.
"""

TEMPLATE_GUIDE = """\
# Switch templates, for agents

A template is one YAML document that says what to create: agents, rooms, a
group of rooms. You run one you write with create_room_from_yaml, save it
with save_template, or run a saved one with run_template. Write new
templates in version 2, described here; "Version 1" at the end is for
reading older ones.

## The shape

version: 2
params:      # the inputs, each written as {name} anywhere below
  <name>: {type: ..., default: ..., ...}
resources:   # what the template creates, each under a key with a type
  <key>:     # letters, digits and _
    type: agent | room | group
    if: "{param}" | "{param} == value" | "{param} != value"   # optional
    ...the fields of that type
form:        # optional: how the form folds things away
  advanced: {label: Advanced, open: false}

Resources refer to each other by key: a room's agents: [lead] lists the
agent whose key is lead, and {lead.name} anywhere is the name that resource
is created under (an agent's name, or the identifier its display_name
gives). A reference to a resource whose if: does not hold is refused.

## if:, the one conditional

- On a resource: it is created only while the condition holds.
- On a param: it is asked only while the condition holds. A param that is
  not asked reads as empty, and drops out of the lists it was written in.
- In a field's value, as a list: the first entry whose if holds is taken,
  and an entry with no if always holds:
    addressing:
      - {if: "{start_in} == new_room", value: {anyone_in: [lead_room]}}
      - {value: anyone}

A condition reads one param: "{param}" (true when it has a value) or
"{param} == value" / "{param} != value".

## An agent (type: agent)

  instructions: text             # REQUIRED. The agent's brief.
  provider: claude | codex | opencode | antigravity | cursor | "{param}"   # REQUIRED
  machine: machine name or id | "{param}"           # REQUIRED: where it runs
  directory: path | "{param}"                       # REQUIRED
  name: identifier               # optional; else derived from display_name.
                                 # Lowercase letters, digits, . - _
  display_name: text             # optional; how people see it
  icon_url: https URL            # optional; its picture, else one drawn from its name
  description: text              # optional; what it is for
  model: text | "{param}"        # optional; the provider's default if absent
  advanced_config: {key: value}  # optional; see get_advanced_config(provider)
  isolation: shared | isolated   # optional; default shared
  auto_mode: true | false        # optional; default true. The provider's own
                                 # review: safe actions run, risky ones ask
  auto_approve: true | false     # optional; default false. Bypass: no
                                 # permission checks at all; overrides auto_mode
  can_manage_agents: true | false  # optional; default false. It may create
                                 # agents on the deployer's machines
  addressing: owner | owner-agents | anyone | {anyone_in: [room keys]}
                                 # optional; default owner-agents (the deployer
                                 # and the deployer's agents)
  connections:                   # optional; the deployer's connections it gets
    - {service: github, access: read | write, repos: [owner/name]}
    - atlassian                  #   or just the service's name
  repo: URL                      # optional; it clones it into its directory
                                 # (a private one needs a github connection)
  join: [existing room name or "{param}"]   # optional; rooms it is added to
  sources: [{label, url} or url] # optional; pages it should read
  allow_existing: true | false   # optional; an existing agent may stand in

Each agent is created as a managed agent of the deployer (your owner, when
you run it) on the machine it names, before the rooms. That needs agent
management on the server and, for you, the "can manage agents" capability;
the machine must be online with the provider installed and signed in. The
whole run is checked before anything is created; every problem comes back
with its reason code, and agents made before a later failure are deleted.

provider, machine and directory are never filled in for you: say each on the
agent, as a value or "{param}". A param offers a choice with a default:
machine default [$first] is the first online machine that can run the agents'
providers; provider default [claude, codex] the first ready on its machine;
directory "{$agents_dir}/{lead.name}" the agent's own folder on its machine.

connections are the deployer's own, granted to the new agent: they must have
connected each, with write access to grant write. anyone_in admits anyone in
those rooms of the run as well as the deployer. join adds the agent to rooms
that already exist; each must be one the deployer may add agents to.
allow_existing: true lets run_template(agents={key: existing agent name}) put
an agent that exists in the slot instead; leave it out unless asked.

Before saving an agent template, settle with the person who asked: which
coding agent runs each agent, on which machine, in which directory, what it
may reach (connections), who may talk to it (addressing), and whether an
existing agent may stand in for it.

## A room (type: room)

  name: text                     # REQUIRED
  description: text              # REQUIRED
  instructions: text             # standing brief for the room's agents
  bridge: messaging app display name, or "{param}"
  channel_type: channel_public | channel_private
  agents: [agent keys, or names of agents that exist]
  users: [usernames on its messaging app; "{$creator}" is the deployer]
  roles: [{name, instructions, exclusive: true | false}]
  references: [{id} | {name} | {type, name, description, instructions,
               value: {urls: [...]}}]
  docs: [{name, description, instructions, content}]
  aliases: {agent key or name: alias}   # @alias addresses it in this room
  packages: [{id: package id} or {name: package name}]   # packages that
                                 # exist, attached as they are
  kickoff: text                  # posted once the room exists
  group: <group key>             # when the template has a group

roles are hats for the room's agents: one assumes a role with assume_role,
works under its instructions and releases it; exclusive: true (default
false) lets one agent hold it at a time. references attach outside material
(a Drive folder, a repository, a Jira project): {id: ...} or {name: ...}
attaches one that exists, and a missing, ambiguous or unreadable one stops
the run; a full entry creates a new one of a reference type (google_drive,
confluence, github, jira, or one the server defines), private unless
read_visibility / write_visibility say otherwise. docs are documents created
in the room; its agents see each one's description and load the content
when they need it. Capturing a room writes roles and docs in full and
references by id:

    roles:
      - {name: reviewer, exclusive: true, instructions: Review each change.}
    references:
      - {id: <reference id>}
      - {name: Design notes}
      - type: github
        name: Service repo
        description: The code under review
        instructions: Read it; do not push.
        value: {urls: ["https://github.com/org/repo"]}
    docs:
      - name: checklist
        description: What every review covers
        instructions: Work through it for each change.
        content: "Tests pass. Errors are handled. The docs say what changed."

Without bridge the room goes on the server's default messaging app; users
needs one (make them depend on it: [{if: "{bridge}", value: [...]},
{value: []}]). Several rooms go in one group. packages must be ones the
deployer can attach by hand; a missing or ambiguous one stops the run.

## A group (type: group)

  name: text
  description: text
  links: [{from: room key, to: room key, label: text}]

## Params

  <name>:
    type: string | number | boolean | enum | agent | bridge | room | user
          | provider | machine | directory
    description: text
    label: text                  # the input's name on the form
    default: a value, or for agent/bridge/room/provider/machine a list of
             candidates tried in order, $first meaning the first that works
    required: true | false       # default: false with a single default value,
                                 # true with none or with a list of candidates
    input: ask | advanced | fixed  # shown, folded away, or not editable
    enum: [choices]              # enum only
    pattern: regex               # string only, whole value must match
    min: number, max: number     # number only
    multiline: true | false      # string only, a text area
    if: condition                # asked only while it holds

Give values in run_template's inputs argument; a required param with no value
is refused with its name.

## Placeholders

{param} is replaced by the param's value; a field that is exactly one
placeholder keeps the value's type. {key.name} is a resource's name. Built
in: {$creator} (the deployer, as the messaging app knows them),
{$creator_email}, {$date} (YYYY-MM-DD), {$timestamp}, and {$agents_dir} (the
folder an agent's machine keeps agents in). A {word} that names nothing is
left as written.

## Kickoff

An agent starts working when a message addresses it, so a room's kickoff
mentions each agent it needs: kickoff: "@{lead.name} start on the brief."
When you run the template, the kickoff speaks for you, not your owner: an
agent that would not accept messages from you makes the run fail before
anything is created (leave a new agent on the default, owner-agents, or give
it anyone_in its room; owner shuts you out). Asking again for a room with the same kickoff you already used
further up the same path pauses the run until your owner lets it continue.

## Revisions and updates

A template's revision is its own edit count, not the language version.
Running a saved or official template by id records which agents that run
created; an agent created from an official template is brought up to each new
revision of it when the server starts, except for what someone changed and its
permissions. get_template_status tells an agent how it differs from its own.

## Example

version: 2
params:
  topic: {type: string, description: What the room is about}
resources:
  review:
    type: room
    name: "{topic} review"
    description: "Reviewing {topic}"
    agents: [reviewer]
    users: ["{$creator}"]
    kickoff: "@reviewer read the brief and list three risks in {topic}."

## Version 1

Older templates have no resources: and say what a block is by where it sits.
A top-level agent: or agents: list holds agents (each with location: local |
ssh host instead of machine: on a Console that runs them itself), room: one
room with a top-level kickoff:, and group: with rooms: and links: a group. A
room lists agents by the text written as their name, and in a single agent:
document {agent} is its name. They still run as they are; write new ones in
version 2.
"""