Skip to content

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

Document room roles, references and docs in the template guide (#996)

Abel Dantasfd036ee4d3b2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f6f510ab1..fff9e0b67 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -45,6 +45,12 @@ version of their own to them without also giving them a release of their own.
### [Unreleased]
#### Fixed
+- **The template guide agents read now covers a room's `roles:`,
+ `references:` and `docs:`.** All three already worked in a room resource
+ and appear when a room is captured, but the guide stopped at `aliases:`, so
+ an agent writing a template did not know they existed or what shape they
+ take. It now gives each one's fields, a sentence on what it does, and a
+ short example.
- **The Teams command menu fits Teams' limit again.** Switch's own Teams app
listed thirteen commands, one more than Teams allows, once `/remove-agent`
joined it. Both Teams apps now offer the same twelve: `/remove-agent` is in,
diff --git a/core/switch_core/template_guide.py b/core/switch_core/template_guide.py
index 66a464382..8ceaca61d 100644
--- a/core/switch_core/template_guide.py
+++ b/core/switch_core/template_guide.py
@@ -114,10 +114,42 @@ existing agent may stand in for it.
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
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.
diff --git a/core/tests/switch_core/bridges/agent/operations/test_agent_template_tools.py b/core/tests/switch_core/bridges/agent/operations/test_agent_template_tools.py
index 0ae083aa7..ea6e1844e 100644
--- a/core/tests/switch_core/bridges/agent/operations/test_agent_template_tools.py
+++ b/core/tests/switch_core/bridges/agent/operations/test_agent_template_tools.py
@@ -42,6 +42,8 @@ from switch_core.bridges.agent.operations.definitions import (
from switch_core.db.models import Agent, Room, Template, User
from switch_core.db.stores.agent_store import AgentStore
from switch_core.db.stores.template_store import TemplateStore
+from switch_core.rooms_yaml import RoomSpec
+from switch_core.template_guide import TEMPLATE_GUIDE
ROOM_TEMPLATE = """\
version: 1
@@ -749,6 +751,25 @@ async def test_the_guide_describes_the_language_and_the_example_in_it_is_valid(t
assert created["room_name"] == "billing review"
+def test_the_guide_shows_room_roles_references_and_docs_in_an_accepted_shape():
+ room_section = TEMPLATE_GUIDE.split("## A room (type: room)", 1)[1].split(
+ "\n## ", 1
+ )[0]
+ for key in ("roles:", "references:", "docs:"):
+ assert key in room_section
+ example = yaml.safe_load(
+ room_section.split("references by id:\n\n", 1)[1].split("\n\n", 1)[0]
+ )
+ spec = RoomSpec(name="n", description="d", **example)
+ assert [type(r).__name__ for r in spec.references] == [
+ "ExistingReferenceById",
+ "ExistingReferenceByName",
+ "InlineExternalReference",
+ ]
+ assert spec.roles[0].exclusive is True
+ assert spec.docs[0].content
+
+
def test_an_agent_param_whose_candidates_name_a_slot_follows_the_swap():
template = """\
params:
diff --git a/docs/TEMPLATES.md b/docs/TEMPLATES.md
index e6d64ba51..df6aedcd4 100644
--- a/docs/TEMPLATES.md
+++ b/docs/TEMPLATES.md
@@ -448,6 +448,17 @@ exports, so an exported room is a valid template once you add `params:`.
`examples/room-templates/red-blue-workroom.template.yaml` documents every
field in place.
+`roles:` are hats the room's agents can assume, each
+`{name, instructions, exclusive}`; an `exclusive: true` role (the default is
+`false`) has one holder at a time. `references:` attach outside material:
+`{id: ...}` or `{name: ...}` attaches a reference that exists, and one that
+is missing, ambiguous or not the deployer's to read stops the run; an entry
+with `type`, `name`, `description`, `instructions` and `value: {urls: [...]}`
+creates a new one (private unless `read_visibility` / `write_visibility` say
+otherwise). `docs:` are documents created in the room, each
+`{name, description, instructions, content}`. An exported room writes roles
+and docs in full and references by `id`.
+
`agents:` names agents that exist on the server, plus the ones this
document creates by the text written as their `name`. `users:` names people
by their username on the room's messaging app; `{$creator}` puts the