Skip to content

Commit aae04d8

Browse files
lukegalbraithrusselllukegalbraithrussell
committed
go
1 parent 7f9c231 commit aae04d8

File tree

2 files changed

+238
-47
lines changed

2 files changed

+238
-47
lines changed

‎docs/english/concepts/adding-agent-features.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,9 @@ def handle_feedback_button(
379379

380380
Putting all those concepts together results in a dynamic agent ready to helpfully respond.
381381

382+
383+
<details>
384+
<summary Full example></summary>
382385
<Tabs>
383386
<TabItem value="pydantic" label = "Pydantic">
384387

@@ -670,3 +673,71 @@ def handle_app_mentioned(
670673

671674
</TabItem>
672675
</Tabs>
676+
</details>
677+
678+
---
679+
680+
## Onward: adding custom tools
681+
682+
Casey comes with test tools and simulated systems. You can extend it with custom tools to make it a fully functioning Slack agent.
683+
684+
In this example, we'll add a tool that makes live calls to check the GitHub status.
685+
686+
1. Create `agent/tools/{tool-name}.py` and define the tool with the `@tool` decorator:
687+
688+
```python title="agent/tools/check_github_status.py"
689+
from claude_agent_sdk import tool
690+
import httpx
691+
692+
@tool(
693+
name="check_github_status",
694+
description="Check GitHub's current operational status",
695+
input_schema={},
696+
)
697+
async def check_github_status_tool(args):
698+
"""Check if GitHub is operational."""
699+
async with httpx.AsyncClient() as client:
700+
response = await client.get("https://www.githubstatus.com/api/v2/status.json")
701+
data = response.json()
702+
status = data["status"]["indicator"]
703+
description = data["status"]["description"]
704+
705+
return {
706+
"content": [
707+
{
708+
"type": "text",
709+
"text": f"**GitHub Status** — {status}\n{description}",
710+
}
711+
]
712+
}
713+
```
714+
715+
2. Import the tool in `agent/casey.py`:
716+
717+
```python title="agent/casey.py"
718+
from agent.tools import check_github_status_tool
719+
```
720+
721+
3. Register in `casey_tools_server`:
722+
723+
```python title="agent/casey.py"
724+
casey_tools_server = create_sdk_mcp_server(
725+
name="casey-tools",
726+
version="1.0.0",
727+
tools=[
728+
check_github_status_tool, # Add here
729+
# ... other tools
730+
],
731+
)
732+
```
733+
734+
4. Add to `CASEY_TOOLS`:
735+
736+
```python title="agent/casey.py"
737+
CASEY_TOOLS = [
738+
"check_github_status", # Add here
739+
# ... other tools
740+
]
741+
```
742+
743+
Use this example as a jumping off point for building out an agent with the capabilities you need!

‎docs/english/getting-started.md‎

Lines changed: 167 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -18,56 +18,70 @@ In search of the complete guide to building an app from scratch? Check out the [
1818

1919
#### Prerequisites
2020

21-
A few tools are needed for the following steps:
22-
* A workspace where development can happen is also needed. We recommend using [developer sandboxes](/tools/developer-sandboxes) to avoid disruptions where real work gets done.
23-
* Git
24-
* [Python 3.7 or later](https://www.python.org/downloads/). Refer to [Python's setup and building guide](https://devguide.python.org/getting-started/setup-building/) for more details.
25-
26-
27-
import QuickstartGuide from '@site/src/components/QuickstartGuide';
28-
29-
<QuickstartGuide
30-
steps={[
31-
{
32-
number: 1,
33-
title: 'Install the Slack CLI',
34-
description: 'Download the command-line tool for developing Slack apps.',
35-
commands: {
36-
macos: 'curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash',
37-
windows: 'irm https://downloads.slack-edge.com/slack-cli/install-windows.ps1 | iex'
38-
}
39-
},
40-
{
41-
number: 2,
42-
title: 'Connect to your workspace',
43-
description: 'Log in and authenticate with your Slack workspace.',
44-
commands: {
45-
macos: 'slack login',
46-
windows: 'slack login'
47-
}
48-
},
49-
{
50-
number: 3,
51-
title: 'Use Casey as a template',
52-
description: 'Create a project using the starter template sample app',
53-
commands: {
54-
macos: 'slack create first-slack-agent --template slack-samples/bolt-python-starter-template',
55-
windows: 'slack create first-slack-agent --template slack-samples/bolt-python-starter-template'
56-
}
57-
}
58-
]}
59-
/>
60-
61-
62-
You now have the Slack CLI and the starter sample app ready for use. Open up the app in your editor of choice and let's explore what the agent can actually do.
63-
64-
65-
## Setting up your environment
66-
67-
After the project is created you'll have a `requirements.txt` file for app dependencies and a `.slack` directory for Slack CLI configuration.
21+
A few tools are needed for the following steps. We recommend using the [**Slack CLI**](/tools/slack-cli/) for the smoothest experience, but other options remain available.
22+
23+
You can also begin by installing git and downloading [Python 3.7 or later](https://www.python.org/downloads/), or the latest stable version of Python. Refer to [Python's setup and building guide](https://devguide.python.org/getting-started/setup-building/) for more details.
24+
25+
Install the latest version of the Slack CLI to get started:
26+
27+
- [Slack CLI for macOS & Linux](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux)
28+
- [Slack CLI for Windows](/tools/slack-cli/guides/installing-the-slack-cli-for-windows)
29+
30+
Then confirm a successful installation with the following command:
31+
32+
```sh
33+
$ slack version
34+
```
35+
36+
An authenticated login is also required if this hasn't been done before:
37+
38+
```sh
39+
$ slack login
40+
```
41+
42+
:::info[A place to belong]
43+
44+
A workspace where development can happen is also needed.
45+
46+
We recommend using [developer sandboxes](/tools/developer-sandboxes) to avoid disruptions where real work gets done.
47+
48+
:::
49+
50+
## Creating a project {#creating-a-project}
51+
52+
With the toolchain configured, it's time to set up a new Bolt project. This contains the code that handles logic for your app.
53+
54+
If you don’t already have a project, let’s create a new one!
55+
56+
<Tabs groupId="cli-or-terminal">
57+
<TabItem value="cli" label="Slack CLI">
58+
59+
A starter template can be used to start with project scaffolding:
60+
61+
```sh
62+
$ slack create first-bolt-app --template slack-samples/bolt-python-getting-started-app
63+
$ cd first-bolt-app
64+
```
65+
66+
After a project is created you'll have a `requirements.txt` file for app dependencies and a `.slack` directory for Slack CLI configuration.
6867

6968
A few other files exist too, but we'll visit these later.
7069

70+
</TabItem>
71+
<TabItem value="terminal" label="Terminal">
72+
73+
A starter template can be cloned to start with project scaffolding:
74+
75+
```sh
76+
$ git clone https://github.com/slack-samples/bolt-python-getting-started-app first-bolt-app
77+
$ cd first-bolt-app
78+
```
79+
80+
Outlines of a project are taking shape, so we can move on to running the app!
81+
82+
</TabItem>
83+
</Tabs>
84+
7185
We recommend using a [Python virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) to manage your project's dependencies. This is a great way to prevent conflicts with your system's Python packages. Let's create and activate a new virtual environment with [Python 3.7 or later](https://www.python.org/downloads/):
7286

7387
```sh
@@ -87,6 +101,9 @@ $ which python3
87101

88102
Before you can start developing with Bolt, you will want a running Slack app.
89103

104+
<Tabs groupId="cli-or-terminal">
105+
<TabItem value="cli" label="Slack CLI">
106+
90107
The getting started app template contains a `manifest.json` file with details about an app that we will use to get started. Use the following command and select "Create a new app" to install the app to the team of choice:
91108

92109
```sh
@@ -103,6 +120,69 @@ With the app running, you can test it out with the following steps in Slack:
103120

104121
After confirming the app responds, celebrate, then interrupt the process by pressing `CTRL+C` in the terminal to stop your app from running.
105122

123+
</TabItem>
124+
<TabItem value="terminal" label="Browser">
125+
126+
Navigate to your list of apps and [create a new Slack app](https://api.slack.com/apps/new) using the "from a manifest" option:
127+
128+
1. Select the workspace to develop your app in.
129+
2. Copy and paste the `manifest.json` file contents to create your app.
130+
3. Confirm the app features and click "Create".
131+
132+
You'll then land on your app's **Basic Information** page, which is an overview of your app and which contains important credentials:
133+
134+
![Basic Information page](/img/bolt-python/basic-information-page.png "Basic Information page")
135+
136+
To listen for events happening in Slack (such as a new posted message) without opening a port or exposing an endpoint, we will use [Socket Mode](/tools/bolt-python/concepts/socket-mode). This connection requires a specific app token:
137+
138+
1. On the **Basic Information** page, scroll to the **App-Level Tokens** section and click **Generate Token and Scopes**.
139+
2. Name the token "Development" or something similar and add the `connections:write` scope, then click **Generate**.
140+
3. Save the generated `xapp` token as an environment variable within your project:
141+
142+
```sh
143+
$ export SLACK_APP_TOKEN=<your-app-level-token>
144+
```
145+
146+
The above command works on Linux and macOS but [similar commands are available on Windows](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153).
147+
148+
:::warning[Keep it secret. Keep it safe.]
149+
150+
Treat your tokens like a password and [keep it safe](/security). Your app uses these to retrieve and send information to Slack.
151+
152+
:::
153+
154+
A bot token is also needed to interact with the Web API methods as your app's bot user. We can gather this as follows:
155+
156+
1. Navigate to the **OAuth & Permissions** on the left sidebar and install your app to your workspace to generate a token.
157+
2. After authorizing the installation, you'll return to the **OAuth & Permissions** page and find a **Bot User OAuth Token**:
158+
159+
![OAuth Tokens](/img/bolt-python/bot-token.png "Bot OAuth Token")
160+
161+
3. Copy the bot token beginning with `xoxb` from the **OAuth & Permissions page** and then store it in a new environment variable:
162+
163+
```sh
164+
$ export SLACK_BOT_TOKEN=xoxb-<your-bot-token>
165+
```
166+
167+
After saving tokens for the app you created, it is time to run it:
168+
169+
```sh
170+
$ python3 app.py
171+
...
172+
⚡️ Bolt app is running!
173+
```
174+
175+
With the app running, you can test it out with the following steps in Slack:
176+
177+
1. Open a direct message with your app or invite the bot `@BoltApp` to a public channel.
178+
2. Send "hello" to the current conversation and wait for a response.
179+
3. Click the attached button labelled "Click Me" to post another reply.
180+
181+
After confirming the app responds, celebrate, then interrupt the process by pressing `CTRL+C` in the terminal to stop your app from running.
182+
183+
</TabItem>
184+
</Tabs>
185+
106186
## Updating the app
107187

108188
At this point, you've successfully run the getting started Bolt for Python [app](https://github.com/slack-samples/bolt-python-getting-started-app)!
@@ -127,6 +207,9 @@ def message_goodbye(say):
127207

128208
Once the file is updated, save the changes and then we'll make sure those changes are being used.
129209

210+
<Tabs groupId="cli-or-terminal">
211+
<TabItem value="cli" label="Slack CLI">
212+
130213
Run the following command and select the app created earlier to start, or restart, your app with the latest changes:
131214

132215
```sh
@@ -143,10 +226,35 @@ After finding the above output appears, open Slack to perform these steps:
143226

144227
Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats.
145228

229+
</TabItem>
230+
<TabItem value="terminal" label="Terminal">
231+
232+
Run the following command to start, or restart, your app with the latest changes:
233+
234+
```sh
235+
$ python3 app.py
236+
...
237+
⚡️ Bolt app is running!
238+
```
239+
240+
After finding the above output appears, open Slack to perform these steps:
241+
242+
1. Return to the direct message or public channel with your bot.
243+
2. Send "goodbye" to the conversation.
244+
3. Receive a parting response from before and repeat "goodbye" to find another one.
245+
246+
Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats.
247+
248+
</TabItem>
249+
</Tabs>
250+
146251
#### Customizing app settings
147252

148253
The created app will have some placeholder values and a small set of [scopes](/reference/scopes) to start, but we recommend exploring the customizations possible on app settings.
149254

255+
<Tabs groupId="cli-or-terminal">
256+
<TabItem value="cli" label="Slack CLI">
257+
150258
Open app settings for your app with the following command:
151259

152260
```sh
@@ -157,6 +265,18 @@ This will open the following page in a web browser:
157265

158266
![Basic Information page](/img/bolt-python/basic-information-page.png "Basic Information page")
159267

268+
</TabItem>
269+
<TabItem value="terminal" label="Browser">
270+
271+
Browse to https://api.slack.com/apps and select your app "Getting Started Bolt App" from the list.
272+
273+
This will open the following page:
274+
275+
![Basic Information page](/img/bolt-python/basic-information-page.png "Basic Information page")
276+
277+
</TabItem>
278+
</Tabs>
279+
160280
On these pages you're free to make changes such as updating your app icon, configuring app features, and perhaps even distributing your app!
161281

162282
## Next steps {#next-steps}

0 commit comments

Comments
 (0)