Triggering Agents

Triggers automatically invoke agents in response to events. They enable autonomous workflows without manual intervention.

​

Available Trigger Types

​

How Triggers Work

When a trigger fires:

1. The event payload is captured
2. Your agent receives the event data as context
3. The agent executes with access to relevant tools
4. Results are logged and can be posted back to the source

​

Slack Triggers

Slack triggers allow you to invoke agents by @mentioning the Cotool bot in channels where it’s installed. In DMs, the bot can create personal chats or invoke agents depending on your trigger configuration.

​

Setting Up a Slack Trigger

1. Navigate to your agent’s Triggers tab
2. Click Add Trigger and select Slack
3. Choose the channel(s) where the trigger should be active, or select “All Channels”
4. Save the trigger

Once configured, @mentioning the Cotool bot in the specified channels will invoke your agent with the message content as context.

​

One Trigger Per Channel

Each Slack channel can only have one active trigger. This prevents conflicts where multiple agents could respond to the same @mention. What this means:

• You can create multiple Slack triggers for different channels (e.g., one for #alerts, another for #support)
• You cannot create two triggers that both include the same channel
• An “All Channels” trigger cannot coexist with any other Slack trigger

Example configurations: If you need different agents for the same channel based on context (e.g., user groups or keywords), consider using a single trigger with conditional logic in your agent’s system prompt.

​

Thread Conversations (Re-entry)

When Cotool responds in Slack, users can continue the conversation by @mentioning Cotool in the same thread. This enables back-and-forth interactions without starting a new execution each time. How it works:

• @mention Cotool in a thread that already has a Cotool response to continue that conversation
• Both agent-triggered conversations and personal chats support thread re-entry
• The conversation has full context of the previous messages in that thread
• This allows for follow-up questions, clarifications, and iterative workflows

Note: An @mention is required for all interactions with Cotool, including thread re-entry. Simply replying in a thread without @mentioning will not trigger a response. Example flow (agent):

1. User @mentions Cotool: “@Cotool investigate alert #12345”
2. Agent responds with initial findings
3. User replies in thread: “@Cotool can you check if this IP has been seen before?”
4. Agent continues the same execution with the new request

Example flow (personal chat):

1. User DMs Cotool: “@Cotool help me analyze this log file”
2. Cotool responds with analysis
3. User replies in thread: “@Cotool can you summarize the key findings?”
4. Cotool continues the conversation and responds in the thread

​

Permissions

• User matching: The Slack user’s email must match a Cotool account in your organization
• Agent execution: Users must have the agent.execute permission for the specific agent to trigger or re-enter conversations
• Thread ownership: Only users with appropriate permissions can continue agent conversations in threads

​

Response Buttons

Each Cotool response in Slack includes a button to view the full conversation in the web interface: These buttons provide quick access to the full conversation context, tool outputs, and any visualizations in the Cotool web interface.

​

DM vs Channel Behavior

Direct Messages (DMs):

• DMs always create a personal chat accessible via the web interface
• Slack triggers do not apply to DMs—this ensures consistent, predictable behavior
• Thread re-entry works for both personal chats and agent conversations (see below)

Channels:

• @mentions in channels require a configured trigger for that channel
• If no trigger is configured for the channel, users see a message prompting them to set up a trigger
• This ensures public channel conversations are always handled by a configured agent with appropriate guardrails

This separation provides a clear mental model: DMs = personal assistant, Channels = agent workflows.

​

Thread Re-entry for Personal Chats

Personal chats (started via DM) support thread re-entry just like agent conversations:

1. Start a conversation by @mentioning Cotool in a DM
2. Cotool responds in a thread
3. @mention Cotool in the thread to continue the conversation
4. Cotool will respond directly in the Slack thread

Note: Only the original chat owner can continue personal chat conversations. The system verifies that the Slack user’s email matches the Cotool account that owns the chat.

​

Linear Triggers

Linear triggers allow you to invoke agents by @mentioning or assigning Cotool directly in Linear issues. When triggered, the agent processes the request and streams real-time updates — including reasoning, tool actions, and plan progress — back into the Linear issue thread.

​

Setting Up a Linear Trigger

1. Navigate to your agent’s Triggers tab
2. Click Add Trigger and select Linear
3. Choose Agent Session mode (the default for new triggers)
4. Save the trigger

Once configured, @mentioning or assigning Cotool in any Linear issue will invoke your agent with the issue context.

​

Agent Sessions vs. Legacy Webhooks

Linear triggers support two modes: New triggers default to Agent Session mode. Existing legacy webhook triggers continue to work and can be kept as-is.

​

How Agent Sessions Work

When Cotool receives a Linear Agent Session event:

1. Cotool immediately acknowledges with a “Thinking…” status
2. The configured agent processes the request with full issue context
3. Progress is streamed to the Linear thread in real-time (reasoning, tool actions, plan steps)
4. The final response is posted as a reply with a link to the full run in Cotool

​

Conversation Continuity

Follow-up messages in the same Linear Agent Session thread continue the existing Cotool conversation. The agent retains full context from previous turns, enabling multi-step investigations and iterative workflows. Example flow:

1. User @mentions Cotool: “Investigate alert #5678”
2. Agent responds with initial findings
3. User follows up: “Check if this IP was seen in other alerts this week”
4. Agent continues the same conversation with the new request

​

Fallback to Personal Chats

If no Linear trigger is configured for your workspace, Cotool falls back to creating a personal chat for the requesting user (similar to Slack DMs). The user’s Linear email must match a Cotool account.

​

Stopping an Agent

Users can stop a running agent directly from Linear. Cotool will interrupt the execution and confirm the stop in the Linear thread. For full details on the Linear integration, including setup, available tools, and best practices, see the Linear Integration page.