Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
5b308df
feat(agentex): serve Slack webhook triggers over Socket Mode
kenairhodesScale Nov 16, 2026
6eab343
feat(agentex): run the Slack Socket Mode bridge as its own process
kenairhodesScale Nov 16, 2026
32a901f
docs(agentex): launch the Slack bridge with python -m, like the worker
kenairhodesScale Nov 16, 2026
a3fe635
build(agentex): lock only the slack-sdk addition
kenairhodesScale Nov 16, 2026
bee13e3
fix(agentex): sign Socket Mode forwards and serve one trigger per Sla…
kenairhodesScale Nov 17, 2026
7708589
fix(agentex): name the Socket Mode columns for Slack and trim the bri…
kenairhodesScale Nov 17, 2026
19fb99c
refactor(agentex): keep Slack Socket Mode settings in their own table
kenairhodesScale Nov 17, 2026
a196cdc
fix(agentex): reopen a Slack Socket Mode connection that never connects
kenairhodesScale Nov 18, 2026
92348db
fix(agentex): open each Slack Socket Mode app in its own task
kenairhodesScale Nov 18, 2026
1700101
fix(agentex): check that a Slack app token belongs to the app it regi…
kenairhodesScale Nov 18, 2026
3dd42c5
fix(agentex): let a Slack Socket Mode app wait out its rate limit
kenairhodesScale Nov 18, 2026
0f5d96f
fix(agentex): remove the auth registration when an API key insert fails
kenairhodesScale Nov 18, 2026
7d62c41
feat(agentex): update a Slack trigger's Socket Mode settings, and run…
kenairhodesScale Nov 18, 2026
025373b
chore(stlc): seal the python custom code integrated for this branch
kenairhodesScale Nov 18, 2026
f010ef0
Revert "chore(stlc): seal the python custom code integrated for this …
kenairhodesScale Nov 18, 2026
07780d2
chore(agentex): name the compose profile for the bridge slack-socket-…
kenairhodesScale Nov 18, 2026
916c3cf
fix(agentex): check access before loading a key in the Socket Mode ro…
kenairhodesScale Nov 18, 2026
dbc7f89
fix(agentex): load the environment before the bridge checks its key
kenairhodesScale Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
"""slack socket mode apps

Revision ID: f3a5c7e9b1d2
Revises: e2f4a6c8b0d1
Create Date: 2026-11-16 12:00:00.000000

Creates ``slack_socket_mode_apps``: one row per Slack app whose events agentex
receives over Socket Mode, attached to the app's Slack webhook trigger in
``agent_api_keys``. The table is new and empty, so its constraints build without
scanning anything; the foreign key briefly locks ``agent_api_keys`` and does not scan
it. IF NOT EXISTS makes a re-run a no-op.
"""

from collections.abc import Sequence

from alembic import op

# revision identifiers, used by Alembic.
revision: str = "f3a5c7e9b1d2"
down_revision: str | None = "e2f4a6c8b0d1"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None


def upgrade() -> None:
op.execute(
"""
CREATE TABLE IF NOT EXISTS slack_socket_mode_apps (
id VARCHAR NOT NULL PRIMARY KEY,
agent_api_key_id VARCHAR NOT NULL,
agent_id VARCHAR(64) NOT NULL,
slack_app_id VARCHAR(256) NOT NULL,
app_token_encrypted VARCHAR NOT NULL,
forward_path VARCHAR NOT NULL,
created_at TIMESTAMP WITH TIME ZONE DEFAULT now(),
CONSTRAINT uq_slack_socket_mode_apps_slack_app_id UNIQUE (slack_app_id),
CONSTRAINT uq_slack_socket_mode_apps_agent_api_key
UNIQUE (agent_api_key_id, agent_id),
CONSTRAINT fk_slack_socket_mode_apps_agent_api_key
FOREIGN KEY (agent_api_key_id, agent_id)
REFERENCES agent_api_keys (id, agent_id) ON DELETE CASCADE
);
"""
)


def downgrade() -> None:
op.execute("DROP TABLE IF EXISTS slack_socket_mode_apps;")
29 changes: 29 additions & 0 deletions agentex/docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,7 @@ services:
- ENVIRONMENT=development
- UVICORN_PORT=5003
- DATABASE_URL=postgresql://postgres:postgres@agentex-postgres:5432/agentex
- AGENTEX_CREDENTIAL_ENCRYPTION_KEY=${AGENTEX_CREDENTIAL_ENCRYPTION_KEY:-}
- TEMPORAL_ADDRESS=agentex-temporal:7233
- REDIS_URL=redis://agentex-redis:6379
- MONGODB_URI=mongodb://agentex-mongodb:27017
Expand Down Expand Up @@ -276,6 +277,34 @@ services:
user: root
restart: unless-stopped

agentex-slack-socket-bridge:
container_name: agentex-slack-socket-bridge
profiles: ["slack-socket-mode"]
build:
context: ..
dockerfile: agentex/Dockerfile
target: dev
args:
SOURCE_DIR: agentex
environment:
- ENVIRONMENT=development
- DATABASE_URL=postgresql://postgres:postgres@agentex-postgres:5432/agentex
- AGENTEX_CREDENTIAL_ENCRYPTION_KEY=${AGENTEX_CREDENTIAL_ENCRYPTION_KEY:-}
ports:
- "5004:5004"
volumes:
- .:/app:cached
depends_on:
agentex-postgres:
condition: service_healthy
agentex:
condition: service_started
networks:
- agentex-network
command: python -m src.run_slack_socket_mode_bridge
user: root
restart: unless-stopped

volumes:
agentex-temporal-postgres-data:
agentex-postgres-data:
Expand Down
31 changes: 31 additions & 0 deletions agentex/docs/docs/development_guides/webhooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,37 @@ curl -X POST $HOST/agent_api_keys \
}'
```

#### Slack over Socket Mode

If Slack cannot reach agentex over HTTP (for example, when agentex runs in a private network), agentex can receive the app's events over [Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode) instead.
Enable Socket Mode on the app and create an app-level token as that guide describes, then register the trigger with that token. Registration connects to Slack once to check that the token belongs to the app named in `name`, and returns 400 if it does not:

```bash
curl -X POST $HOST/agent_api_keys/webhook-trigger \
Comment thread
kenairhodesScale marked this conversation as resolved.
Resolved
-H "Content-Type: application/json" \
-d '{
"agent_name": "<AGENT_NAME>",
"source": "slack",
"name": "A123ABC456",
"secret": "abcdefg12345",
"forward_path": "slack/events",
"app_token": "xapp-..."
}'
```

The Slack Socket Mode bridge then holds one connection for the app and POSTs every Events API payload to `forward_path` on the agent, the same route and body an HTTP delivery would reach (`url_verification` never happens over a socket).
Each POST carries `X-Slack-Signature` and `X-Slack-Request-Timestamp` computed with the trigger's signing secret, so an agent that verifies Slack signatures itself accepts it as it would an HTTP delivery.
Slack's `retry_attempt` arrives as the usual `X-Slack-Retry-Num` and `X-Slack-Retry-Reason` headers.
An event is acknowledged only after the agent answers 2xx within 2.5 seconds, or answers with `X-Slack-No-Retry: 1` as it can over HTTP; otherwise Slack redelivers it.
Delivery is at least once: an event whose acknowledgement is lost, for example when a bridge replica stops mid-forward, reaches the agent again.
Interactivity and slash-command payloads are not forwarded.

To switch an existing Slack trigger to Socket Mode, or change its token or forward path, `PUT /agent_api_keys/<key_id>/slack_socket_mode` with `app_token` and `forward_path`; it runs the same token check as registration. `DELETE /agent_api_keys/<key_id>/slack_socket_mode` turns Socket Mode off and keeps the trigger. The bridge applies either change within a minute.

Operator notes:

- The bridge is its own process, not part of the API: run `python -m src.run_slack_socket_mode_bridge` (from `agentex/`, the same image as the API, like the Temporal worker's `python -m src.temporal.run_worker`) as a separate Deployment with 2 replicas, one process each. It needs only `DATABASE_URL` and `AGENTEX_CREDENTIAL_ENCRYPTION_KEY`, which encrypts the stored app token; without that key it logs one error and exits. It does not connect to Temporal, MongoDB or Redis.

### Deleting API Keys

If you'd like to remove an existing API key for whatever reason, first grab its ID by listing the keys for the appropriate agent as above.
Expand Down
111 changes: 111 additions & 0 deletions agentex/openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2858,6 +2858,69 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/agent_api_keys/{id}/slack_socket_mode:
put:
tags:
- Agent APIKeys
summary: Serve a Slack trigger over Socket Mode
description: Turn Socket Mode on for an existing Slack trigger, or replace its
app token and forward path. The bridge picks the change up within a minute.
operationId: set_slack_socket_mode_agent_api_keys__id__slack_socket_mode_put
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SetSlackSocketModeRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SlackSocketMode'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Agent APIKeys
summary: Stop serving a Slack trigger over Socket Mode
description: Remove the trigger's app token. The trigger itself stays, and the
bridge closes its connection within a minute.
operationId: delete_slack_socket_mode_agent_api_keys__id__slack_socket_mode_delete
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: string
title: Response Delete Slack Socket Mode Agent Api Keys Id Slack
Socket Mode Delete
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/agent_api_keys/name/{name}:
get:
tags:
Expand Down Expand Up @@ -5313,6 +5376,15 @@ components:
an existing webhook secret. For Slack, this is required and must be the
Slack app's Signing Secret. For Linear, this is required and must be the
Linear OAuth app's webhook signing secret.
app_token:
anyOf:
- type: string
- type: 'null'
title: App Token
description: Slack only. The app's app-level token (xapp-..., scope connections:write).
When set, agentex receives the app's events over Socket Mode and forwards
them to forward_path, so the app needs no public Request URL. Stored encrypted
and never returned.
base_url:
anyOf:
- type: string
Expand Down Expand Up @@ -6390,6 +6462,25 @@ components:
required:
- content
title: SendMessageRequest
SetSlackSocketModeRequest:
properties:
app_token:
type: string
title: App Token
description: The Slack app's app-level token (xapp-..., scope connections:write).
It must belong to the app the trigger is named for. Stored encrypted and
never returned.
forward_path:
type: string
title: Forward Path
description: Subpath of the agent each event is POSTed to, e.g. 'slack/events'.
type: object
required:
- app_token
- forward_path
title: SetSlackSocketModeRequest
description: Turn Socket Mode on for an existing Slack trigger, or replace its
settings.
SkipRunScheduleRequest:
properties:
scheduled_time:
Expand All @@ -6401,6 +6492,26 @@ components:
required:
- scheduled_time
title: SkipRunScheduleRequest
SlackSocketMode:
properties:
key_id:
type: string
title: Key Id
description: The Slack trigger's agent API key id.
slack_app_id:
type: string
title: Slack App Id
description: The Slack app served over Socket Mode.
forward_path:
type: string
title: Forward Path
description: Subpath of the agent each event is POSTed to.
type: object
required:
- key_id
- slack_app_id
- forward_path
title: SlackSocketMode
Span:
properties:
id:
Expand Down
4 changes: 4 additions & 0 deletions agentex/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,10 @@ dependencies = [
# (vulnerable OpenSSL bundled in the wheels). Floor kept at the patched minimum
# so a re-resolve can't regress below it.
"cryptography>=50.0.0",
# Socket Mode client for Slack webhook triggers. Its aiohttp backend reuses the
# aiohttp already pinned above; the [optional] extra is not wanted (it would pull
# websockets>=16, which conflicts with websockets~=14.2).
"slack-sdk>=3.44.1,<4",
]

[dependency-groups]
Expand Down
28 changes: 28 additions & 0 deletions agentex/src/adapters/orm.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,13 @@
Column,
DateTime,
ForeignKey,
ForeignKeyConstraint,
Index,
Integer,
LargeBinary,
String,
Text,
UniqueConstraint,
func,
text,
)
Expand Down Expand Up @@ -202,6 +204,32 @@ class AgentAPIKeyORM(BaseORM):
)


class SlackSocketModeAppORM(BaseORM):
__tablename__ = "slack_socket_mode_apps"
id = Column(String, primary_key=True, default=orm_id)
agent_api_key_id = Column(String, nullable=False)
agent_id = Column(String(64), nullable=False)
slack_app_id = Column(String(256), nullable=False)
app_token_encrypted = Column(String, nullable=False)
forward_path = Column(String, nullable=False)
created_at = Column(DateTime(timezone=True), server_default=func.now())

__table_args__ = (
UniqueConstraint("slack_app_id", name="uq_slack_socket_mode_apps_slack_app_id"),
UniqueConstraint(
"agent_api_key_id",
"agent_id",
name="uq_slack_socket_mode_apps_agent_api_key",
),
ForeignKeyConstraint(
["agent_api_key_id", "agent_id"],
["agent_api_keys.id", "agent_api_keys.agent_id"],
ondelete="CASCADE",
name="fk_slack_socket_mode_apps_agent_api_key",
),
)


class AgentRunScheduleORM(BaseORM):
__tablename__ = "agent_run_schedules"
id = Column(String, primary_key=True, default=orm_id)
Expand Down
Loading
Loading