Agent SDK

Appearance

Put a minimal agent in Slack ​

Slack agent is the smallest channel example. It has one runtime config, one instruction file, and one authored channel. A teammate mentions the agent, the local runtime harness runs a turn, and the answer returns to the same Slack thread.

Use it to learn the minimum needed for a Slack agent before adding tools, workflows, or a dedicated app.

Browse the Slack agent source.

Keep the Slack channel small ​

Slack agent delegates transport details to the host connection. The authored file selects the account-linked transport, gives the agent a single-token router name and icon, and supplies suggested prompts.

The complete channel lives in agent/channels/slack.ts. The framework supplies message intake, thread-scoped sessions, delivery, status updates, and suggested prompts.

Follow a Slack message ​

  1. A user mentions the agent or sends the host app a direct message naming it.
  2. The Slack relay selects this channel by its single-token agentName.
  3. The Agent SDK maps the Slack channel and thread timestamp to a continuation key.
  4. The local harness runs with instructions.md.
  5. The response returns to the triggering thread.
  6. A later message in the same thread resumes the durable session.

The prompt asks for concise threaded replies. It doesn't define domain policy or tool routing.

Map the Slack agent files ​

FilePurpose
package.jsonDeclares the example package and Agent SDK dependency.
agent/agent.tsNames the agent and selects the model. The omitted runtime defaults to local.
agent/instructions.mdSets the always-on response style.
agent/channels/slack.tsConnects the signed-in host account to Slack.
agent/storage.tsPersists sessions and events with cursorHostedStorage.

There are no authored tools, skills, MCP connections, subagents, schedules, hooks, A/B experiments, or evals. This small surface is the lesson.

Connect the host ​

You need:

  • Node 22.13 or newer.
  • An agent-runtime credential.
  • Slack connected through the selected channel transport.

Sign in and confirm the active account:

bash
agent-sdk login
agent-sdk whoami

The selected transport owns Slack credential setup. See the Slack guide for account-linked and dedicated-app options.

Validate and start the server ​

bash
agent-sdk validate --dir examples/slack-agent
agent-sdk info --dir examples/slack-agent --json
agent-sdk dev examples/slack-agent

The dev command prints the playground URL. It also mounts the Slack channel and waits for relayed messages.

In Slack, address the configured host app and router name, then send:

<host-app mention> <router name> Explain the Agent SDK in three bullets.

Reply in the generated thread:

Make the second bullet simpler.

The second message reaches the same session. You can open that session in the playground to inspect the received message, model events, final reply, and usage.

Test without Slack ​

Every project gets the built-in HTTP channel even when no HTTP file exists. Run a one-shot turn through it:

bash
agent-sdk run --dir examples/slack-agent \
  --message "Explain the Agent SDK simply."

The same project also exposes an MCP endpoint. Since this agent has no server tools, its MCP surface contains ask and check, but not call_tool.

These automatic surfaces let you test the prompt from the CLI and let another agent delegate to it later. The authored Slack channel only changes how work arrives and where replies go.

Know when to add a dedicated app ​

An account-linked Slack transport is a fit for mentions, direct messages, thread continuity, and agent-branded replies. Move to a dedicated Socket Mode channel when you need:

  • top-level channel watching,
  • interactive approval buttons,
  • a separate bot identity, or
  • Slack app events unsupported by the account-linked relay.

Compare this example with Playbook router, which adds allowlisted channel watching, and Weather agent, which adds approval buttons through a second Slack channel.

Turn the channel into your own Slack agent ​

Copy the three authored files, then change:

  • name in agent.ts for the harness identity,
  • agentName in slack.ts for the single-token router name,
  • the instructions for your domain, and
  • suggested prompts for the tasks teammates should try.

Keep agentName free of whitespace. Use PascalCase for multiword names.

Where to go next ​