Skip to main content
Channel event names and the channels configuration contract are experimental and may change without migration as AgentUse adds destinations.
Channels connect AgentUse lifecycle events to external collaboration surfaces. In the current release, Slack is the implemented channel. Use channels when a person should know that an agent needs review, finished successfully, or failed, or when Slack thread replies should continue a run.

​
Basic Slack Setup

Add Slack to the agent frontmatter:
For explicit event selection:
Set a Slack bot token and default channel:
To get a Slack bot token:
  1. Go to api.slack.com/apps and create or open a Slack app.
  2. Open OAuth & Permissions.
  3. Add the bot token scope chat:write.
  4. Click Install to Workspace or Reinstall to Workspace.
  5. Copy the Bot User OAuth Token. It starts with xoxb-.
Optional: add assistant:write if you want Slack Assistant thread status while a live run is active. Approval channel threads can also accept decisions. For Approve/Reject buttons and comment-by-thread-reply, configure Socket Mode:
The app-level token needs connections:write. To resume from normal thread replies, enable Slack event subscriptions for message.channels and, if you use private channels, message.groups; add channels:history and/or groups:history bot scopes as needed. To get a channel id:
  1. Open the channel in Slack.
  2. Click the channel name.
  3. Copy the channel id from the channel details panel. It starts with C... for public channels or G... for private channels.
You can also copy a channel link and use the C... or G... value from the URL. Invite the bot to the target channel before sending channel messages. For private channels, this is required.

​
Slack Config

V1 supports one Slack channel per agent.
Fields:
  • channels.slack: true or an object to enable Slack
  • channels.slack.enabled: set to false to temporarily disable Slack
  • channels.slack.events: event or list of events
  • channels.slack.channel_id: Slack channel id for this agent
Slack can be written in any of these forms:
If channel_id is omitted, AgentUse uses SLACK_APPROVAL_CHANNEL.

​
Events

Supported event names:
  • approval: the agent created an approval request and is waiting for review
  • completion: the agent finished successfully
  • failure: the agent ended with an execution error
A run whose blocker is a person (waiting on an approval or review, or rejected by one) does not fire failure. Its live run card settles as run incomplete with the agent’s reason. Use completion, not complete or completed. If events is omitted, AgentUse enables all supported events. completion and failure are terminal run events. A Slack channel that listens for approval, or for both completion and failure, posts a run-start card immediately and updates the same card when the run completes, fails, or waits for approval. Single-outcome channels such as events: [failure] stay terminal-only so they do not leave stale running messages.

​
Slack Messages

Slack uses one concise channel message as the status card and puts approval details in that message’s thread. Approval channel messages include:
  • Channel card with prompt, session/project metadata, status, and a Review approval button
  • Thread details with summary, draft, artifact, context, and risk when the agent provides them
  • Thread actions for Approve, Reject, and Comment when Socket Mode interactivity is enabled
  • Plain thread replies become comment decisions when Socket Mode message events are enabled
The AgentUse session page (/sessions/<id>) remains the source of truth for review state. Completion channel messages include:
  • Channel card with agent name, session id, status, and duration
  • Thread details with the final answer, tool call count, and token count when available
Failure channel messages include:
  • Channel card with agent name, session id, status, and duration when available
  • Thread details with the error message and run metadata
When Slack Socket Mode message events are enabled, a reviewer can reply in a completed or failed run channel thread to continue from that session with the reply as the new instruction. For live run cards, AgentUse also tries Slack Assistant thread status while the run is active. This is best effort; Slack may ignore it when the app does not have Assistant support.

​
Approval Gates

Approval Gates use channels only to alert reviewers. Configure the approval policy separately:
See Approval Gates for the approval dashboard, reviewer flow, and Approval API.