Triggers - Guild

A trigger runs an agent automatically — either when an event occurs in an external service, on a recurring schedule, or on demand via an API request.

Trigger types

Event

Fires when an event occurs in a connected service, such as a new Slack mention or a GitHub pull request.

Scheduled

Fires on a recurring schedule: hourly, daily, weekly, or monthly.

API

Fires on demand when an authenticated HTTP request is made to the workspace session endpoint.

Create a trigger

Open your workspace

Go to guild.ai and open the workspace where the agent is installed.

Go to Triggers

In the left sidebar, open More and click Triggers, then click New trigger.

Choose a type

Select Event, Scheduled, or API, then configure the trigger.

Select an agent

Choose the agent the trigger will run when it fires.

Event triggers

Event triggers fire when a specific event occurs in a connected service.

In the CLI and REST API, event triggers are referred to as webhook triggers.

Supported services

Service	Example events
Slack	`app_mention`, `message`
GitHub	`pull_request`, `issues`, `push`
Linear	`issue`, `comment`
Jira	`issue_created`, `issue_updated`
Azure DevOps	`workitem.created`, `git.pullrequest.created`
Google Docs	Document changes
Notion	Page updates

Configure the service, event type, and optional event action when creating the trigger. By default, the agent receives the event payload as its input.

Agent input

Webhook triggers support a customizable agent input, identical to the agent input on time triggers. Open the Edit Trigger dialog to edit it. On desktop, a schema-driven panel appears on the right side of the dialog. On mobile, a text field appears instead. When no input has been saved, the field pre-populates with a default based on the integration name, event type, and action.

Custom agent input for webhook triggers

By default, the agent receives the raw webhook payload as its input. You can override this by providing a custom agent_input object when creating the trigger. The custom input is merged with (or replaces) the default payload delivered to the agent. Use custom agent input when you want to:

Pass a fixed system prompt or configuration alongside the webhook payload
Map specific webhook fields to a named input schema your agent expects

guild trigger create \
  --type webhook \
  --service GITHUB \
  --event pull_request \
  --action opened \
  --agent code-reviewer \
  --agent-input '{"review_style": "concise", "post_comment": true}'

Custom agent_input can also be set from the web UI when creating or editing a webhook trigger.

Pass the webhook payload unaltered

When you create or edit an event trigger in the web UI, select Pass the webhook payload unaltered to forward the raw webhook JSON payload directly to the agent. Checking this option disables and clears the input editor, so you do not need to define a custom input template to deliver the payload as-is. This option corresponds to an empty agent_input in the CLI and REST API, which the backend treats as “forward the payload unaltered.”

Toggling Pass the webhook payload unaltered is non-destructive. If you uncheck it, the input editor restores the agent input template you previously entered.

Scope events with `service_config`

Use service_config to restrict event triggers to specific repositories, channels, or projects. Webhook triggers accept an optional service_config JSON object. When you omit it or set it to null, the trigger matches all events of the selected type (for example, every repository or every channel).

Service	Field	Example	Behavior
GitHub	`repo`	`"guildaidev/guildcode"`	Only events for this repository (`owner/repo` format)
Slack	`channel_ids`	`["C01234567"]`	Only events in these channel IDs. Messages from the Slack app itself are always excluded to prevent loops.
Jira	`project`	`"ENG"`	Only events for this project key (case-insensitive)

service_config must be a JSON object. Do not pass an array or string at the top level. Pass service_config when you create or update a trigger with the CLI:

# GitHub: only pull requests in one repo
guild trigger create \
  --type webhook \
  --service GITHUB \
  --event pull_request \
  --action opened \
  --agent code-reviewer \
  --service-config '{"repo": "guildaidev/guildcode"}'

# Slack: only mentions in specific channels
guild trigger create \
  --type webhook \
  --service SLACK \
  --event app_mention \
  --agent slack-assistant \
  --service-config '{"channel_ids": ["C01234567"]}'

For Slack, an empty channel_ids array matches all channels. Omit service_config entirely only if you intend to process events workspace-wide.

Session affinity with `session_affinity_key`

By default, Guild uses integration-specific logic to determine which session an incoming webhook event belongs to. Set session_affinity_key to extract the session correlation ID directly from the webhook payload instead. session_affinity_key is a dot-notation path into the webhook payload. The value at that path becomes the remote_id that matches the event to an existing session. When the extracted value matches a prior event’s remote_id, the agent continues in that session rather than starting a new one. When set, session_affinity_key overrides the integration handler’s default session correlation logic. For example, "event.thread_ts" extracts the Slack thread timestamp from a payload structured as {"event": {"thread_ts": "1234567890.123"}}.

If the path does not resolve — because the field is absent or an intermediate value is not an object — the trigger falls back to no affinity and starts a new session.

CLI

# Create a Slack event trigger
guild trigger create \
  --type webhook \
  --service SLACK \
  --event app_mention \
  --agent slack-assistant

# Create a GitHub event trigger for opened pull requests
guild trigger create \
  --type webhook \
  --service GITHUB \
  --event pull_request \
  --action opened \
  --agent code-reviewer

Scheduled triggers

Scheduled triggers fire on a recurring schedule and run the agent with a fixed input.

In the CLI and REST API, scheduled triggers are referred to as time triggers.

Frequencies

Frequency	Options
`HOURLY`	—
`DAILY`	Time of day
`WEEKLY`	Days of week, time of day
`MONTHLY`	Days of month, time of day

CLI

# Daily trigger at 9:00 AM
guild trigger create \
  --type time \
  --frequency DAILY \
  --time 09:00 \
  --agent daily-report \
  --input '{"project": "GUILD"}'

# Weekly trigger on Monday mornings
guild trigger create \
  --type time \
  --frequency WEEKLY \
  --days-of-week monday \
  --time 09:00 \
  --agent weekly-summary

API triggers

An API trigger runs the agent on demand via an authenticated HTTP request. API triggers require an API key to authenticate requests.

Generate an API key

API keys are created and managed via the web UI:

Go to Triggers in your workspace and click New trigger.
Select API and choose the agent this trigger will run.
Once the trigger is created, copy the combined credentials string (<api_key_id>:<api_key_secret>) displayed in the dialog. The generated string contains both the api_key_id and api_key_secret.

Creating and managing API keys is currently exclusive to the web UI. There is no CLI subcommand available for managing API keys.

Authentication

Guildcode uses HTTP Basic Authentication to authorize API requests. Pass the combined credentials string as the authentication parameter (for example, with curl -u):

Trigger a session

To start a new agent session, make a POST request to the workspace’s sessions endpoint:

POST /api/workspaces/{owner_name}/{workspace_name}/sessions

Request body

The request body must be a JSON object with:

session_type: Must be set to "api_trigger".
agent_input: A JSON object matching the input schema of your agent.

Example

curl -X POST https://app.guild.ai/api/workspaces/<owner_name>/<workspace_name>/sessions \
  -u "<api_key_id>:<api_key_secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "session_type": "api_trigger",
    "agent_input": {
      "text": "Hello, agent!"
    }
  }'

Interactive follow-up

If the agent is conversational or awaits subsequent inputs, you can post follow-up events directly to the session:

POST /api/sessions/{session_id}/events

Request body

mode: Set to "text" (default), "json", or "multimodal".
content: The message content. For "text" mode, a string; for "json" mode, a JSON object; for "multimodal" mode, a non-empty array of content part objects.

When mode is "multimodal", each content part is an object with a type field:

When type is "text", the object must include a non-empty "text" string.
When type is "image" or "file", the object must include a valid "attachment_id" that references an uploaded attachment.

A single message supports a maximum of 5 attachments.

Example

curl -X POST https://app.guild.ai/api/sessions/<session_id>/events \
  -u "<api_key_id>:<api_key_secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "text",
    "content": "Follow-up question or answer goes here"
  }'

Multimodal example

Send a message with both a text part and an image attachment:

curl -X POST https://app.guild.ai/api/sessions/<session_id>/events \
  -u "<api_key_id>:<api_key_secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "multimodal",
    "content": [
      { "type": "text", "text": "Here is the screenshot you asked about." },
      { "type": "image", "attachment_id": "<attachment_id>" }
    ]
  }'

Retrieve session status

Retrieve the current execution state and metadata of a specific session:

GET /api/sessions/{session_id}

Example

curl -X GET https://app.guild.ai/api/sessions/<session_id> \
  -u "<api_key_id>:<api_key_secret>"

Fetch session events (logs and thoughts)

Retrieve the chronological feed of logs, agent thought progress, LLM usage statistics, tool calls, and final outputs:

GET /api/sessions/{session_id}/events

Query parameters (Optional)

limit: Maximum number of events to return (default: 20).
types: Filter by specific event types (e.g., agent_console).

Example

curl -X GET "https://app.guild.ai/api/sessions/<session_id>/events?limit=100" \
  -u "<api_key_id>:<api_key_secret>"

Fetch session sub-tasks

Fetch a list of all sub-tasks spawned by parent agents or tool calls inside this session:

GET /api/sessions/{session_id}/tasks

Example

curl -X GET https://app.guild.ai/api/sessions/<session_id>/tasks \
  -u "<api_key_id>:<api_key_secret>"

Real-time streaming (WebSockets)

If you are developing a real-time interface or monitoring tool, establish a WebSocket connection rather than polling. Pass your Basic Auth credentials in the connection headers.

Live Messages and Logs Feed: wss://app.guild.ai/api/sessions/<session_id>/events/ws
Real-time LLM Token Streams: wss://app.guild.ai/api/sessions/<session_id>/response-stream-drafts/ws
Sub-task Progress Feed: wss://app.guild.ai/api/sessions/<session_id>/tasks/ws

Security and scope

Workspace Scope: The API key carries workspace-level permissions. This allows it to read and write (including fetching status, event feeds, sub-tasks, and runtime statuses, as well as sending follow-up events/messages) to any session in the same workspace.
Execution Identity: Sessions started via an API key do not run on behalf of a human user (acting_user_id is None). However, when viewing the session’s chat feed in the UI, any events generated by the API will display the avatar of the user who originally created the trigger.

Manage triggers

Activate and deactivate

Deactivate a trigger to pause it without deleting it.

guild trigger deactivate <trigger-id>
guild trigger activate <trigger-id>

List and inspect

# List all triggers in the workspace
guild trigger list

# Get details for a specific trigger
guild trigger get <trigger-id>

# List sessions spawned by a trigger
guild trigger sessions <trigger-id>

Update

# Change the schedule of a scheduled trigger
guild trigger update <trigger-id> --time 10:00

# Change the event of an event trigger
guild trigger update <trigger-id> --event message

​Trigger types

Event

Scheduled

API

​Create a trigger

​Event triggers

​Supported services

​Agent input

​Custom agent input for webhook triggers

​Pass the webhook payload unaltered

​Scope events with service_config

​Session affinity with session_affinity_key

​CLI

​Scheduled triggers

​Frequencies

​CLI

​API triggers

​Generate an API key

​Authentication

​Trigger a session

​Request body

​Example

​Interactive follow-up

​Request body

​Example

​Multimodal example

​Retrieve session status

​Example

​Fetch session events (logs and thoughts)

​Query parameters (Optional)

​Example

​Fetch session sub-tasks

​Example

​Real-time streaming (WebSockets)

​Security and scope

​Manage triggers

​Activate and deactivate

​List and inspect

​Update

Trigger types

Create a trigger

Event triggers

Supported services

Agent input

Custom agent input for webhook triggers

Pass the webhook payload unaltered

Scope events with `service_config`

Session affinity with `session_affinity_key`

CLI

Scheduled triggers

Frequencies

CLI

API triggers

Generate an API key

Authentication

Trigger a session

Request body

Example

Interactive follow-up

Request body

Example

Multimodal example

Retrieve session status

Example

Fetch session events (logs and thoughts)

Query parameters (Optional)

Example

Fetch session sub-tasks

Example

Real-time streaming (WebSockets)

Security and scope

Manage triggers

Activate and deactivate

List and inspect

Update