arizuko › howto › Talking to agents

talking to agents

Two layers of "address the bot" live side by side: the chat platform (mention syntax, replies, reactions) and arizuko itself (slash commands, sticky routing, MCP tools). This page is the operator's map of both.

get the agent's attention

Whether a message fires the agent at all depends on the route. The default shape for a public channel is "respond on mention, observe everything else" (see asymmetric channels). A mention means different things per platform:

platform	mention syntax	notes
Slack	`@<bot> hello`	slakd derives `verb=mention` from `<@bot_user_id>` in message text. Reactions and replies-to-bot also count as mentions.
Discord	`@<bot> hello`	Same shape. Replies to bot messages and reactions on them are promoted to mentions.
Telegram	`@<botname>` or reply	Group chats fire on @-mention or on reply to a bot message. DMs always fire.
WhatsApp	`@<phone>` or reply	WhatsApp groups need @-mention. Reply-to-bot promotes to mention (v0.40.2).
web (`/chat/<token>/`)	any message	The chat page is one-on-one with the agent. Every message is a turn.
email	To: `<bot>@<domain>`	emaid threads by Message-ID. Reply-all keeps the thread.

`routd` slash commands

Six commands work on every platform — they short-circuit before the agent runs. The handler list is routd/steer.go. Type them as the first non-whitespace token of a message; Telegram's /cmd@botname suffix is accepted.

command	who can run	what it does
`/new [text]`	anyone with interact	Clear the agent's session for this folder. Optional `text` runs as the first message of the new session.
`/ping`	anyone with interact	Replies with current folder, session ID prefix, active container count, registered group count.
`/chatid`	anyone with interact	Replies with the `chat_jid` of the current chat. Useful when writing route rules.
`/stop`	anyone with interact	Kills the current agent container for this chat. Next message spawns a fresh one.
`/status`	root only	Channel count, group count, active containers, errored chats, active tasks.
`/root <msg>`	tier ≤ 1	Delegate `<msg>` to the root group of the current folder hierarchy. Replies route back here.
`/invite [N]`	root only	Mint an invite link; `N` = max uses (default 1).
`/gate list\|add\|rm\|enable\|disable`	root only	Manage rate-limit gates.

Bare @ at the start of a message is parsed before commands — see sticky routing below.

sticky routing — `@<folder>` and `#<topic>`

On its own line at the start of a message, these change where subsequent messages in this chat go — until cleared. Implementation: routd/steer.go.

@<folder> — pin this chat to folder <folder>. Replies arrive here, but the agent for <folder> is the one that runs. Unknown folder names are passed to the agent (so a Czech sentence starting @everyone doesn't break).
@ alone — clear the pin, route by rules again.
#<topic> — pin a thread label. Useful for multi-thread workflows in one chat.
# alone — clear the topic pin.

With a leading @<child> <text> (single message, not on its own line), routd delegates that one message to the child folder — same effect as a single-shot delegate_group from inside the agent.

crossing agents (operator-driven)

The operator's tools for moving conversation between agents are the same MCP tools the agents use among themselves. Two ways to invoke them: ask the agent in chat ("delegate this to research") or call the tool directly from the chat MCP socket. Tool reference: MCP reference.

tool	direction	use it when
`delegate_group`	parent → child	This folder owns a problem that belongs to a child agent. The child runs the turn; the reply routes back here.
`escalate_group`	child → parent	The child agent needs a decision from the parent. Parent receives the message; nothing is granted automatically.
`register_group`	parent creates child	Create a new sub-folder on the fly. Common in autoviv setups (autoviv) — tier-1 agent calls this on first message from a new channel.
`inject_message`	any → any	Push a system-style message into another folder's chat. Used by tasks and timed events.
`refresh_groups`	self	Reload the in-memory group list. Run after a folder is added or removed out-of-band.

These are tier-gated. register_group needs tier ≤ 1; delegate_group and escalate_group follow the folder hierarchy rules (parent can delegate to known children; child can escalate to its parent). See grants for the permission model.

JID quick reference

A chat_jid is <platform>:<rest>. Full table at JID format. For writing route rules, you almost always want /chatid in the target chat and to paste the result.

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

which mechanism for which job

I want to…	use
Start a fresh agent session in this chat	`/new`
Find this chat's JID for a route rule	`/chatid`
Send one message to the root agent	`/root <msg>`
Route all subsequent messages to `research`	`@research` on its own line
Hand this one task to `research`	`@research <task>` as one message, or ask the agent to `delegate_group`
Open a new sub-folder	Ask the agent to call `register_group`
Push a system note into another folder	Ask the agent to call `inject_message`
Bring in events from GitHub or Stripe	Wire a webhook → webhooks
Make the agent forget and start over	`/stop` (kills container), then `/new`

per-platform gotchas

Slack — don't subscribe to app_mention; slakd derives mention from the regular message.* event. Subscribing both double-fires (see Slack adapter, step 3).
Telegram — slash commands keep the @botname suffix (/new@mybot); routd strips it before matching.
WhatsApp — pure-reply-without-text (just hitting "reply" with no body) was promoted to a mention in v0.40.2; before then, the agent never saw it.
Reactions — on Slack and Discord, a reaction on a bot message routes back as verb=reaction with the emoji. The agent can treat 👎 as a dislike signal — no separate code path.

go deeper

routing — how chats become folders.
grants — who can run which command.
autoviv — auto-create folders on first message.
MCP reference — every tool, every param.
CLI reference — the operator's command line.
webhooks — external sources into arizuko.