Skip to content

Commit 108e4c6

Browse files
zimegClaude
andauthored
feat: add the team agent to the Pydantic AI app (#7)
Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
1 parent eda828a commit 108e4c6

20 files changed

Lines changed: 611 additions & 140 deletions

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This file provides guidance to coding agents when working with code in this repo
44

55
## What This Is
66

7-
A monorepo with three functionally identical implementations of the Starter Agent for Slack built with Bolt for Python, each self-contained with its own `AGENTS.md`:
7+
A monorepo with three functionally identical implementations of the Team Agent for Slack built with Bolt for Python, each self-contained with its own `AGENTS.md`. The agent keeps a team's runbooks (Slack canvases titled `Runbook: <topic>`) current from channel messages and answers requests from them:
88

99
- `claude-agent-sdk/`: Claude Agent SDK
1010
- `openai-agents-sdk/`: OpenAI Agents SDK

‎README.md‎

Lines changed: 7 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Starter Agent for Slack
1+
# Team Agent for Slack
22

3-
A minimal starter template for building AI-powered Slack agents with [Bolt for Python](https://docs.slack.dev/tools/bolt-python/). Works with the [Slack MCP Server](https://github.com/slackapi/slack-mcp-server) to search messages, read channels, send messages, and manage canvases — all from within your agent. Includes one example tool (emoji reactions), giving you a clean foundation to build on.
3+
A sample Slack agent built with [Bolt for Python](https://docs.slack.dev/tools/bolt-python/) that keeps your team's runbooks current and helps route the requests that come in. Runbooks are Slack canvases titled `Runbook: <topic>`. The agent answers from them, and it learns from the messages in your team's channels, so the runbooks it writes are the ones it answers from next time.
44

55
## Choose Your Framework
66

@@ -56,26 +56,14 @@ npx skills add slackapi/slack-skills-plugin -y -a opencode
5656

5757
## What It Can Do
5858

59-
The starter agent interacts with users through four entry points:
59+
The team agent interacts with users through five entry points:
6060

6161
* **App Home** — Displays a welcome message with instructions on how to interact.
62-
* **Direct Messages** — Users message the agent directly. It responds in-thread, maintaining context across follow-ups.
63-
* **Channel @mentions** — Mention the agent in any channel to get a response without leaving the conversation.
62+
* **Direct Messages** — Users message the agent directly to find a runbook or triage a request. It responds in-thread, maintaining context across follow-ups.
63+
* **Channel @mentions** — Mention the agent in a team channel with a request. It answers from a runbook when one covers it, or offers to start one.
64+
* **Channel messages** — The agent follows along in channels it's a member of. When a message settles something worth keeping, the agent adds it to the team's runbooks on its own.
6465
* **Assistant Panel** — Users click _Add Agent_ in Slack, select the agent, and pick from suggested prompts or type a message.
6566

66-
When connected to the [Slack MCP Server](https://github.com/slackapi/slack-mcp-server), the agent can search messages and files, read channel history and threads, send and schedule messages, and create and update canvases. The template also includes one example tool (emoji reactions). Add your own tools to customize the agent for your use case.
67-
68-
## Using the App
69-
70-
Once the agent is running, there are several ways to interact:
71-
72-
* **App Home** — Open the agent in Slack and click the _Home_ tab to see a welcome message.
73-
* **Direct Messages** — Open a DM with the agent. Pick a suggested prompt or type your own message, and the agent will reply in a thread.
74-
* **Channel @mentions** — Invite the agent to a channel by typing `/invite @agent-name`, then @mention it with your message. It responds in a thread so the channel stays clean.
75-
* **Assistant Panel** — Click _Add Agent_ in the top-right corner of Slack, select the agent, and choose a suggested prompt like _Write a Message_, _Summarize_, or _Brainstorm_.
67+
With the bot token, the agent lists, reads, and creates runbooks. A person who connects the [Slack MCP Server](https://github.com/slackapi/slack-mcp-server) from the Home tab has the agent work with runbooks as them instead, which can also update existing runbooks. When the agent changes a runbook, it tells the message's author with an ephemeral message only they can see.
7668

7769
For full setup instructions, pick a framework above and follow the README in that directory.
78-
79-
## Local Development
80-
81-
This repo uses [`slack-bolt`](https://pypi.org/project/slack-bolt/) from PyPI.

‎pydantic-ai/AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This file provides guidance to coding agents when working with code in this repo
44

55
## What This Is
66

7-
A **Starter Agent** for Slack built with Bolt for Python and **Pydantic AI**. This is a minimal starter template. It includes one example tool (emoji reactions) and optional Slack MCP Server integration.
7+
A **Team Agent** for Slack built with Bolt for Python and **Pydantic AI**. It keeps a team's runbooks current and helps route requests. Runbooks are Slack canvases titled `Runbook: <topic>`. With the bot token, the agent lists, reads, and creates them with tools in `agent/tools/` (`files.list`, `canvases.getContent`, `canvases.create`). When the person has connected the Slack MCP Server, it uses the MCP runbook tools instead, which can also edit runbooks. The same agent learns from each channel message (`listeners/events/message.py`), adding anything it settles to a runbook. It also includes one app tool (emoji reactions).
88

99
## Slack Plugin
1010

‎pydantic-ai/README.md‎

Lines changed: 33 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,34 @@
1-
# Starter Agent for Slack (Bolt for Python and Pydantic AI)
1+
# Team Agent for Slack (Bolt for Python and Pydantic AI)
22

3-
A minimal starter template for building AI-powered Slack agents with [Bolt for Python](https://docs.slack.dev/tools/bolt-python/) and [Pydantic AI](https://ai.pydantic.dev/) using models from [Anthropic](https://anthropic.com) or [OpenAI](https://openai.com). Works with the [Slack MCP Server](https://github.com/slackapi/slack-mcp-server) to search messages, read channels, send messages, and manage canvases — all from within your agent.
3+
A team agent template built with [Bolt for Python](https://docs.slack.dev/tools/bolt-python/) and [Pydantic AI](https://ai.pydantic.dev/) using models from [Anthropic](https://anthropic.com) or [OpenAI](https://openai.com). It keeps your team's runbooks current as threads wrap up and helps route the requests that come in. Runbooks are Slack canvases that the agent reads and writes through the [Slack MCP Server](https://github.com/slackapi/slack-mcp-server).
44

55
## App Overview
66

7-
The starter agent interacts with users through four entry points:
7+
The team agent interacts with users through five entry points:
88

99
* **App Home** — Displays a welcome message with instructions on how to interact.
10-
* **Direct Messages** — Users message the agent directly. It responds in-thread, maintaining context across follow-ups.
11-
* **Channel @mentions** — Mention the agent in any channel to get a response without leaving the conversation.
10+
* **Direct Messages** — Users message the agent directly to find a runbook or triage a request. It responds in-thread, maintaining context across follow-ups.
11+
* **Channel @mentions** — Mention the agent in a team channel with a request. It answers from a runbook when one covers it, or offers to start one.
12+
* **Channel messages** — The agent follows along in channels it's a member of. When a message settles something worth keeping, the agent adds it to the team's runbooks on its own.
1213
* **Assistant Panel** — Users click _Add Agent_ in Slack, select the agent, and pick from suggested prompts or type a message.
1314

14-
The template also includes one example tool (emoji reactions). Add your own tools to customize it for your use case.
15+
The agent works with runbooks through three app tools that call the Web API with the bot token: `list_runbooks`, `read_runbook`, and `create_runbook`. When a person has connected the [Slack MCP Server](https://github.com/slackapi/slack-mcp-server), the agent uses its runbook tools as that person instead, which can also edit existing runbooks section by section. One more app tool (emoji reactions) shows a request was picked up. Add your own tools to customize it for your use case.
16+
17+
### Runbooks
18+
19+
Runbooks are Slack canvases titled `Runbook: <topic>`. Each one holds how the team does something: the steps, who owns it, and who to escalate to. Anyone can read and edit them in Slack, and the agent does too:
20+
21+
* **Reading** — When a request comes in, the agent finds the runbook that covers it and answers from it.
22+
* **Writing on request** — Ask the agent to write a runbook and it creates one. With the Slack MCP Server connected, it can also fix the runbook that covers the topic.
23+
* **Learning from messages** — The same agent reads each channel message. If the message fixed a problem, named an owner, made a decision, or corrected a runbook, the agent creates a runbook for it, or, with the Slack MCP Server connected, updates the one that covers it. Most messages settle nothing worth keeping, and the agent leaves those alone.
24+
25+
This is the loop the template is built to show: the runbooks the agent writes from messages are the runbooks it answers from next time.
26+
27+
When the agent changes a runbook, it tells the message's author with an ephemeral message only they can see. Nothing is posted to the channel. New runbooks are added as a tab in the channel they were learned in, so the whole team can read and edit them. The agent only gets runbook tools, so it can't send messages or read threads.
1528

1629
### Slack MCP Server
1730

18-
When connected to the [Slack MCP Server](https://github.com/slackapi/slack-mcp-server), the agent can search messages and files, read channel history and threads, send and schedule messages, and create and update canvases. When deployed with OAuth (HTTP mode), the agent automatically connects to the Slack MCP Server using the user's token.
31+
Connecting the [Slack MCP Server](https://github.com/slackapi/slack-mcp-server) is optional. When deployed with OAuth (HTTP mode), a person who connects it from the Home tab has the agent work with runbooks as them: it finds runbooks with Slack search and reads and writes canvases with their access, so edits show their name. Everyone else gets the bot token's runbook tools.
1932

2033
## Setup
2134

@@ -83,8 +96,8 @@ slack login
8396
#### Initializing the project
8497

8598
```sh
86-
slack create my-starter-agent --template slack-samples/bolt-python-starter-agent --subdir pydantic-ai
87-
cd my-starter-agent
99+
slack create my-team-agent --template slack-samples/bolt-python-team-agent --subdir pydantic-ai
100+
cd my-team-agent
88101
```
89102

90103
</details>
@@ -119,8 +132,8 @@ SLACK_APP_TOKEN=YOUR_SLACK_APP_TOKEN
119132
#### Initializing the project
120133

121134
```sh
122-
git clone https://github.com/slack-samples/bolt-python-starter-agent.git my-starter-agent
123-
cd my-starter-agent
135+
git clone https://github.com/slack-samples/bolt-python-team-agent.git my-team-agent
136+
cd my-team-agent/pydantic-ai
124137
```
125138

126139
</details>
@@ -144,7 +157,7 @@ This app supports both Anthropic and OpenAI as AI providers. Set at least one AP
144157

145158
### Anthropic Setup
146159

147-
Uses Anthropic's `claude-sonnet-4-6` model through Pydantic AI.
160+
Uses Anthropic's `claude-sonnet-5-5` model through Pydantic AI.
148161

149162
1. Create an API key from your [Anthropic dashboard](https://console.anthropic.com/settings/keys).
150163
1. Rename `.env.sample` to `.env`.
@@ -156,7 +169,7 @@ ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
156169

157170
### OpenAI Setup
158171

159-
Uses OpenAI's `gpt-4.1-mini` model through Pydantic AI.
172+
Uses OpenAI's `gpt-6.1-sol` model through Pydantic AI.
160173

161174
1. Create an API key from your [OpenAI dashboard](https://platform.openai.com/api-keys).
162175
1. Rename `.env.sample` to `.env`.
@@ -285,9 +298,11 @@ Once the agent is running, there are several ways to interact:
285298

286299
**App Home** — Open the agent in Slack and click the _Home_ tab. You'll see a welcome message with instructions on how to interact.
287300

288-
**Direct Messages** — Open a DM with the agent. You'll see suggested prompts like _Write a Message_, _Summarize_, and _Brainstorm_ — pick one or type your own message. The agent replies in a thread. Send follow-up messages in the same thread and the agent will maintain the full conversation context.
301+
**Direct Messages** — Open a DM with the agent. You'll see suggested prompts like _Find a Runbook_, _Triage a Request_, and _Write a Runbook_ — pick one or type your own message. The agent replies in a thread. Send follow-up messages in the same thread and the agent will maintain the full conversation context.
302+
303+
**Channel @mentions** — Invite the agent to your team channel by typing `/invite @agent-name` in the message box, then @mention it followed by your request. The agent responds in a thread so the channel stays clean.
289304

290-
**Channel @mentions** — Invite the agent to a channel by typing `/invite @agent-name` in the message box, then @mention it followed by your message. The agent responds in a thread so the channel stays clean.
305+
**Channel messages** — Talk through a problem in your team channel. When you post the fix, the agent adds it to a runbook and sends you an ephemeral note with the link. Ask about the same problem later and it answers from that runbook.
291306

292307
**Assistant Panel** — Click _Add Agent_ in the top-right corner of Slack, select the agent from the list, then pick a suggested prompt or type a message.
293308

@@ -323,7 +338,7 @@ Every incoming request is routed to a "listener". This directory groups each lis
323338

324339
- `app_home_opened.py` — Publishes the App Home view with a welcome message and MCP status.
325340
- `app_mentioned.py` — Responds to @mentions in channels.
326-
- `message.py` — Responds to direct messages from users.
341+
- `message.py` — Responds to direct messages and learns from channel messages by connected users.
327342

328343
**`/listeners/actions`** — Handles interactive components:
329344

@@ -336,11 +351,11 @@ Every incoming request is routed to a "listener". This directory groups each lis
336351

337352
### `/agent`
338353

339-
The `agent.py` file defines the Pydantic AI Agent with a system prompt, personality, and tool configuration.
354+
The `agent.py` file defines the team agent with a system prompt, personality, and tool configuration. `run_agent()` gives it the bot token's runbook tools, or the Slack MCP Server's runbook tools when the person has connected it.
340355

341356
The `deps.py` file defines the `AgentDeps` dataclass passed to the agent at runtime, providing access to the Slack client and conversation context.
342357

343-
The `tools` directory contains one example tool (emoji reaction) that the agent can call during a conversation.
358+
The `tools` directory contains the runbook tools, which call `files.list`, `canvases.getContent`, and `canvases.create` with the bot token, and one example tool (emoji reaction).
344359

345360
### `/thread_context`
346361

‎pydantic-ai/agent/__init__.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
from .agent import agent, get_model, run_agent
1+
from .agent import agent, run_agent
22
from .deps import AgentDeps
33

4-
__all__ = ["AgentDeps", "agent", "get_model", "run_agent"]
4+
__all__ = ["AgentDeps", "agent", "run_agent"]

0 commit comments

Comments
 (0)