AI Agent Shortcut Protocol: Commands, Targets, and References
Version note: the unified shortcut protocol is available starting with
v0.0.4.beta. Prefer standard text generated by the interface, approval notification, or Connector instead of guessing object IDs manually.
Most messages sent to an AI Agent are natural-language tasks. Deleting a session, compressing context, selecting a target session, and submitting an approval decision should not depend on model interpretation.
xAgent separates deterministic control from ordinary tasks:
/command is a deterministic backend command.
@{type:id} directs content or a decision to an explicit target.
#{type:id} only references an object. It does not reroute or execute an action.
@{approval:id} approve/reject is an approval control reply.
#{approval:id} only references the approval record.
Why This Protocol Exists
Natural language alone can make control operations ambiguous. “Delete it” may refer to a session, a file, or a draft. “I approve” does not identify an approval request. Mentioning a file ID should not automatically authorize reading, sending, or deleting that file.
xAgent follows a simple rule: natural language describes work, while the shortcut protocol identifies deterministic targets and operations.
The system parses the protocol before checking ownership, permission, state, and operation scope. A consumed command or approval reply is not sent to the model for interpretation and is not appended again as an ordinary Agent task.
This provides predictable behavior, explicit routing, permission boundaries, and the same semantics across Web, IM Connectors, and other text entry points.
The Four Core Forms
| Form | Meaning | Changes the target | Executes directly |
|---|---|---|---|
/command | Run a deterministic command on the current session | No | Yes |
@{session:id} content | Send content to a specific session | Yes | Depends on content |
#{type:id} | Reference an object in the current message | No | No |
@{approval:id} approve/reject | Submit a decision to a specific approval | Yes, to the owning session | Yes |
/command: Deterministic Commands
A Slash Command runs an explicitly implemented session operation without entering the Agent task-understanding flow.
/compress
Without a target, it applies to the current session. A session target can be placed first:
@{session:13c2b2f5744009c} /compress
This compresses the target session instead of sending “/compress” to the Agent as text.
Session Commands in v0.0.4.beta
| Command | Scope | Effect | Execution location |
|---|---|---|---|
/refresh_messages | Main and Sub Sessions | Synchronize the current page's session messages | Local Web page |
/delete | Sub Sessions only | Delete the target Sub Session | xAgent backend |
/clear-history | Main Session only | Advance the visible history boundary | xAgent backend |
/compress | Main and Sub Sessions | Manually compress target-session context | xAgent backend |
Commands should be sent by themselves. Unknown commands, extra text, invalid targets, or an incompatible session state return a deterministic error instead of becoming an ordinary Agent task.
@{session:id}: Direct Content to a Session
Place a session target at the beginning of a message:
@{session:13c2b2f5744009c} Recheck the conclusion using the new material
A target written in the middle of ordinary text does not change routing:
Ask @{session:13c2b2f5744009c} to recheck the conclusion
This prevents quoted text containing a SessionRef from accidentally rerouting a message.
The target must exist, belong to the current user, and remain available. Multiple different targets are rejected as ambiguous.
@{type:id} is the common protocol form, but only objects that can receive content or a control decision may be targets. The public target types in v0.0.4.beta are session and approval. Files use #{file:id} references and cannot receive messages.
#{type:id}: Reference an Object Only
An object reference tells the current session which object a task concerns. It does not change the target and does not execute an action.
File Reference
Analyze #{file:2329} and prepare a risk summary
The reference identifies a file. Actual access still passes through user and session file boundaries.
Session Reference
Compare the current result with #{session:13c2b2f5744009c}
The message still goes to the current session. Referencing another session does not send content to it or guarantee that the current Agent can read it.
Approval Reference
Explain why #{approval:13c5b94bb80003e} requires approval
This references an approval record without submitting a decision. Further use still depends on available capabilities and permission.
@{approval:id}: Submit an Approval Decision
An approval decision requires a directed target and an explicit decision:
@{approval:13c5b94bb80003e} approve
@{approval:13c5b94bb80003e} reject
Chinese approval notifications accept:
@{approval:13c5b94bb80003e} 同意
@{approval:13c5b94bb80003e} 不同意
xAgent resolves the approval's owning session, checks ownership and waiting state, and accepts the first valid decision. A completed, expired, or already answered approval cannot be changed by later replies.
This does not approve anything:
#{approval:13c5b94bb80003e} approve
The # prefix always means reference only, even when decision words follow it.
Combining Forms
The processing order remains explicit: resolve the target, determine whether the remaining content is a command or a message, and preserve object references in ordinary content.
Send a File-related Task to a Session
@{session:13c2b2f5744009c} Check #{file:2329} and update the report
The message goes to the target Session and references a File. File access and modification still depend on the target session's capabilities, permissions, and approval policy.
Run a Command on a Session
@{session:13c2b2f5744009c} /compress
This performs deterministic compression without activating an ordinary Agent turn.
Using the Protocol on Web and IM
Web Sessions
When the composer receives /, @{, or #{, the interface can suggest currently available commands and objects. Prefer inserting a generated value instead of typing an ID manually.
IM Connectors
WeChat, Telegram, and other Connectors parse shortcut text before choosing a target session. Ordinary messages without a target enter the current user's Main Session by default.
Approval notifications include a complete reply form. Reply with that standard text rather than only “approve,” because the system must identify the approval request.
Security and Usage Boundaries
@selects a receiving target but grants no Tool, file, or external-system permission.#references an object but does not read, delete, send, approve, or execute it./commandruns only commands explicitly implemented and allowed by the system.- Every target passes ownership, existence, state, and operation-scope validation.
- One input can contain only one distinct directed target.
- Shortcuts cannot bypass the virtual filesystem, approval policy, or Connector authorization.
- Invalid syntax, objects, or permissions return errors instead of being delegated to the model to guess.
Common Mistakes
| Incorrect form | Problem | Correct form |
|---|---|---|
#{approval:id} approve | A reference does not submit a decision | @{approval:id} approve |
Ask @{session:id} to continue | The target is not at the beginning | @{session:id} Continue |
@{session:id} | No message or command follows the target | Add content or /command |
/compress then continue writing | A command is mixed with a task | Send /compress, then send the task separately |
@{file:id} Analyze | A file is not a message receiver | Analyze #{file:id} |