arizuko › howto › Talking to agents

talking to agents

You address the agent at two levels. The chat platform gives mentions, replies and reactions. arizuko adds slash commands, sticky routing and MCP tools.

A mention starts a turn on a mention-only route

The route decides whether a message starts a turn. The usual route for a public channel answers on a mention and only observes the other messages. Asymmetric channels shows this route. Each platform has its own mention:

platform	mention	notes
Slack	`@<bot> hello`	slakd sets `verb=mention` when the text contains `<@bot_user_id>`. A reply to the bot and a reaction on a bot message also count as mentions.
Discord	`@<bot> hello`	The same as Slack. A reply to a bot message and a reaction on it become mentions.
Telegram	`@<botname>` or a reply	A group chat starts a turn on a mention or on a reply to a bot message. A direct message always starts a turn.
WhatsApp	`@<phone>` or a reply	A group needs a mention. A reply to a bot message becomes a mention, also a reply without text.
web, `/chat/<token>/`	any message	The chat page connects one visitor to the agent. Every message is a turn.
email	To: `<bot>@<domain>`	emaid groups the messages of a thread by Message-ID. Reply-all keeps the thread.

routd answers eleven slash commands before the agent runs

The commands work on every platform. routd handles them and starts no turn. Type the command as the first word of a message. routd accepts the Telegram suffix /cmd@botname. The handlers are in [routd/steer.go].

command	who	what it does
`/new [text]`	any sender	Clears the session of the folder. The optional `text` is the first message of the new session.
`/ping`	any sender	Replies with the folder, the start of the session ID, the count of active turns and the count of groups.
`/chatid`	any sender	Replies with the `chat_jid` of the chat. Use it to write a route rule.
`/stop`	any sender	Stops the active turn of the folder. The next message starts a new guest.
`/status`	operator	Counts of channels, groups, active turns, errored chats and active tasks.
`/root <msg>`	operator	Runs `<msg>` in this chat as one root turn. Every grant check passes for that message only. The reply comes to this chat.
`/invite [N]`	operator	Makes an invite link through `onbod`. `N` is the maximum number of uses, default 1.
`/gate list\|add\|rm\|enable\|disable`	operator	Manages the onboarding gates in `onbod`. `/gate add <spec> <N>` admits `N` users a day.
`/approve <id> [note]`	admin of the folder	Approves a held tool call. The agent then runs the call.
`/reject <id> [note]`	admin of the folder	Rejects a held tool call.
`/always <id> [note]`	admin of the folder	Approves a held tool call and writes a rule that skips the approval for the same call later. The reply names the rule and how to remove it.

An operator is a sender with a ** grant. routd reads a leading @ before the commands, as the next section shows.

@folder and #topic pin the routing of a chat

A message that contains only @<folder> or #<topic> changes the routing of the next messages in the chat. The pin stays until you clear it. The code is in [routd/steer.go].

@<folder>: Pins the chat to the folder. Replies come to this chat, and the agent of <folder> runs. routd gives a message with an unknown folder name to the agent unchanged, so a sentence that starts with @everyone still works.
@: Clears the folder pin. The route rules apply again.
#<topic>: Pins a topic. Use it for several threads of work in one chat.
#: Clears the topic pin.

A message that starts with @<child> <text> on one line goes to the child folder once. routd sends that one message to <folder>/<child>, as one delegate_group call from the agent does.

The agents use MCP tools to move work between folders

The operator moves a conversation between agents with the same MCP tools that the agents use. Ask the agent in the chat, for example "delegate this to research". Or call the tool through the MCP socket of the chat. The MCP reference lists the parameters.

tool	direction	use it when
`delegate_group`	parent → child	The work belongs to a child agent. The child runs the turn, and the reply comes back here.
`escalate_group`	child → parent	The child agent needs a decision from the parent. The parent gets the message. No grant changes.
`register_group`	parent makes a child	Makes a new child folder. In an autoviv setup, the world agent calls it on the first message from a new channel.
`inject_message`	into the store	Writes a message into the store as if a chat sent it, and the normal loop starts a turn. Tasks and tests use it.
`refresh_groups`	read	Lists the group folders. The grant on the tool limits what the agent sees.

Each tool needs its own grant. The default member role does not hold register_group, delegate_group or escalate_group. An agent has them only where an admin granted them, and the scope glob of the grant sets the folders that the agent can name. Grants explains the permission model.

A JID names one chat on one platform

A chat_jid has the form <platform>:<rest>. JID has the full table. To write a route rule, send /chatid in the target chat and copy the result.

slack:T012/channel/C345    # one Slack channel
discord:dm/123             # one Discord DM
telegram:group/1001234567  # one Telegram group
whatsapp:789@g.us          # one WhatsApp group
web:<folder>               # browser chat at folder, through /chat/<token>/
hook:<folder>/<source>     # webhook ingest at folder, through /hook/<token>

Each task has one mechanism

task	use
Start a new agent session in this chat	`/new`
Find the JID of this chat for a route rule	`/chatid`
Send one message as a root turn	`/root <msg>`
Send all next messages to `research`	`@research` alone in a message
Give one task to `research`	`@research <task>` in one message, or ask the agent to call `delegate_group`
Make a new child folder	Ask the agent to call `register_group`
Start a turn in a folder from a tool	Ask the agent to call `inject_message`
Bring in events from GitHub or Stripe	Connect a webhook, as Webhooks shows
Stop the agent and start again	`/stop`, then `/new`

Each platform has one or two special cases

Slack: slakd reads a mention from the text of the message.* events, so the app_mention subscription is not necessary. With both subscriptions, Slack sends each mention twice. Slack shows the event list.
Telegram: Slash commands can carry the @botname suffix, for example /new@mybot. routd removes the suffix before it reads the command.
WhatsApp: A reply to a bot message without text counts as a mention.
Reactions: On Slack and Discord, a reaction on a bot message comes back as verb=reaction with the emoji. The agent can read 👎 as a dislike. No separate code path exists.

Five pages explain the parts in detail

routing: How a chat goes to a folder.
grants: Who can run which command.
autoviv: Folders that the first message makes.
MCP reference: Every tool and every parameter.
CLI reference: The command line of the operator.