Skip to content

Commit 6a30cea

Browse files
billy-the-fishbilly-the-fishatovpekojgpruitt
authored
chore: tiger agents doc, first draft. (#4482)
* chore: tiger agents doc, first draft. * chore: updates on review. * chore: updates on review. * Apply suggestions from code review Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> Signed-off-by: Iain Cox <iain@timescale.com> * chore: updates on review. * chore: updates on review. * chore: mcp config update. * chore: update for EON. * chore: update for EON. * chore: update the procedure. * chore: space. * Apply suggestions from code review Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> Signed-off-by: Iain Cox <iain@timescale.com> * chore: add something about persistent memory. * Apply suggestions from code review Co-authored-by: John Pruitt <jgpruitt@gmail.com> Signed-off-by: Iain Cox <iain@timescale.com> * chore: Updates on review. --------- Signed-off-by: Iain Cox <iain@timescale.com> Co-authored-by: billy-the-fish <iain@tigerdata.com> Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> Co-authored-by: John Pruitt <jgpruitt@gmail.com>
1 parent 1b3091b commit 6a30cea

File tree

4 files changed

+519
-1
lines changed

4 files changed

+519
-1
lines changed

‎_partials/_prereqs-cloud-project-and-self.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
To follow the procedure on this page you need to:
2+
3+
* Create a [$ACCOUNT_LONG][create-account].
4+
5+
This procedure also works for [$SELF_LONG][enable-timescaledb].
6+
7+
[create-account]: /getting-started/:currentVersion:/services/#create-a-tiger-account
8+
[enable-timescaledb]: /self-hosted/:currentVersion:/install/

‎ai/page-index/page-index.js‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,22 @@
11
module.exports = [
22
{
3-
title: "AI and Vector: pgai on Tiger",
3+
title: "AI and Vector",
44
href: "ai",
55
filePath: "index.md",
66
pageComponents: ["featured-cards"],
77
excerpt:
88
"Information about pgai on TigerData and how to use it.",
99
children: [
10+
{
11+
title: "Aggregate organizational data with AI agents",
12+
href: "tiger-eon",
13+
excerpt: "Unify company knowledge with slack-native AI agents",
14+
},
15+
{
16+
title: "Integrate a slack-native AI agent",
17+
href: "tiger-agents-for-work",
18+
excerpt: "Configure a Slack-native AI agent to do what you want",
19+
},
1020
{
1121
title: "Key vector database concepts",
1222
href: "key-vector-database-concepts-for-understanding-pgvector",

‎ai/tiger-agents-for-work.md‎

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
---
2+
title: Integrate a slack-native AI agent
3+
excerpt: Unify company knowledge with slack-native AI agents
4+
products: [cloud]
5+
keywords: [ai, vector, pgvector, TigerData vector, pgvectorizer]
6+
tags: [ai, vector, pgvectorizer]
7+
---
8+
9+
# Integrate a slack-native AI agent
10+
11+
import PrereqAccount from "versionContent/_partials/_prereqs-cloud-project-and-self.mdx";
12+
13+
$AGENTS_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your Slack
14+
history, docs, GitHub repositories, Salesforce and so on. You use your $AGENTS_SHORT to get instant answers for real
15+
business, technical, and operations questions in your Slack channels.
16+
17+
![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png)
18+
19+
$AGENTS_LONG can handle concurrent conversations with enterprise-grade reliability. They have the following features:
20+
21+
- **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions
22+
- **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load
23+
- **Immediate event processing**: $AGENTS_LONG provide real-time responsiveness. Events are processed within milliseconds of arrival rather than waiting for polling cycles
24+
- **Resilient retry logic**: automatic retry with visibility thresholds, plus stuck or expired event cleanup
25+
- **Horizontal scalability**: run multiple $AGENTS_SHORT instances simultaneously with coordinated work distribution across all instances
26+
- **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers
27+
- **Extensible architecture**: zero code integration for basic agents. For more specialized use cases, easily customize your agent using [Jinja templates][jinja-templates]
28+
- **Complete observability**: detailed tracing of event flow, worker activity, and database operations with full [Logfire][logfire] instrumentation
29+
30+
This page shows you how to install the $AGENTS_CLI, connect to the $COMPANY MCP server, and customize prompts for
31+
your specific needs.
32+
33+
## Prerequisites
34+
35+
<PrereqAccount />
36+
37+
* The [uv package manager][uv-install]
38+
* An [Anthropic API key][claude-api-key]
39+
* Optional: [Logfire token][logfire]
40+
41+
## Create a Slack app
42+
43+
Before installing $AGENTS_LONG, you need to create a Slack app that the $AGENTS_SHORT will connect to. This app
44+
provides the security tokens for Slack integration with your $AGENTS_SHORT:
45+
46+
<Procedure>
47+
48+
1. **Create a manifest for your Slack App**
49+
50+
1. In a temporary directory, download the $AGENTS_SHORT Slack manifest template:
51+
52+
```bash
53+
curl -O https://raw.githubusercontent.com/timescale/tiger-agents-for-work/main/slack-manifest.json
54+
```
55+
56+
1. Edit `slack-manifest.json` and customize your name and description of your Slack App. For example:
57+
58+
```json
59+
"display_information": {
60+
"name": "Tiger Agent",
61+
"description": "Tiger AI Agent helps you easily access your business information, and tune your Tiger services",
62+
"background_color": "#000000"
63+
},
64+
"features": {
65+
"bot_user": {
66+
"display_name": "Tiger Agent",
67+
"always_online": true
68+
}
69+
},
70+
```
71+
72+
1. Copy the contents of `slack-manifest.json` to the clipboard:
73+
74+
```shell
75+
cat slack-manifest.json| pbcopy
76+
```
77+
78+
1. **Create the Slack app**
79+
80+
1. Go to [api.slack.com/apps](https://api.slack.com/apps).
81+
1. Click `Create New App`.
82+
1. Select `From a manifest`.
83+
1. Choose your workspace, then click `Next`.
84+
1. Paste the contents of `slack-manifest.json` and click `Next`.
85+
1. Click `Create`.
86+
1. **Generate an app-level token**
87+
88+
1. In your app settings, go to `Basic Information`.
89+
1. Scroll to `App-Level Tokens`.
90+
1. Click `Generate Token and Scopes`.
91+
1. Add a `Token Name`, then click `Add Scope`, add `connections:write` then click `Generate`.
92+
1. Copy the `xapp-*` token locally and click `Done`.
93+
94+
1. **Install your app to a Slack workspace**
95+
96+
1. In the sidebar, under `Settings`, click `Install App`.
97+
1. Click `Install to <workspace name>`, then click `Allow`.
98+
1. Copy the `xoxb-` Bot User OAuth Token locally.
99+
100+
</Procedure>
101+
102+
You have created a Slack app and obtained the necessary tokens for $AGENTS_SHORT integration.
103+
104+
105+
## Install and configure your $AGENTS_SHORT instance
106+
107+
$AGENTS_LONG are a production-ready library and CLI written in Python that you use to create Slack-native AI agents.
108+
This section shows you how to configure a $AGENTS_SHORT to connect to your Slack app, and give them access to your
109+
data and analytics stored in $CLOUD_LONG.
110+
111+
<Procedure>
112+
113+
1. **Create a project directory**
114+
115+
```bash
116+
mkdir my-tiger-agent
117+
cd my-tiger-agent
118+
```
119+
120+
1. **Create a $AGENTS_SHORT environment with your Slack, AI Assistant, and database configuration**
121+
122+
1. Download `.env.sample` to a local `.env` file:
123+
```shell
124+
curl -L -o .env https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/.env.sample
125+
```
126+
1. In `.env`, add your Slack tokens and Anthropic API key:
127+
128+
```bash
129+
# Slack tokens (from the Slack app you created)
130+
SLACK_APP_TOKEN=xapp-your-app-token
131+
SLACK_BOT_TOKEN=xoxb-your-bot-token
132+
133+
# Anthropic API key
134+
ANTHROPIC_API_KEY=sk-ant-your-api-key
135+
136+
# Optional: Logfire token for enhanced logging
137+
LOGFIRE_TOKEN=your-logfire-token
138+
```
139+
1. Add the [connection details][connection-info] for the $SERVICE_LONG you are using for this $AGENTS_SHORT:
140+
```bash
141+
PGHOST=<host>
142+
PGDATABASE=tsdb
143+
PGPORT=<port>
144+
PGUSER=tsdbadmin
145+
PGPASSWORD=<password>
146+
```
147+
1. Save and close `.env`.
148+
149+
1. **Add the default $AGENTS_SHORT prompts to your project**
150+
```bash
151+
mkdir prompts
152+
curl -L -o prompts/system_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/system_prompt.md
153+
curl -L -o prompts/user_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/user_prompt.md
154+
```
155+
156+
1. **Install $AGENTS_LONG to manage and run your AI-powered Slack bots**
157+
158+
1. Install the $AGENTS_CLI using uv.
159+
160+
```bash
161+
uv tool install --from git+https://github.com/timescale/tiger-agents-for-work.git tiger-agent
162+
```
163+
`tiger-agent` is installed in `~/.local/bin/tiger-agent`. If necessary, add this folder to your `PATH`.
164+
165+
1. Verify the installation.
166+
167+
```bash
168+
tiger-agent --help
169+
```
170+
171+
You see the $AGENTS_CLI help output with the available commands and options.
172+
173+
174+
1. **Connect your $AGENTS_SHORT with Slack**
175+
176+
1. Run your $AGENTS_SHORT:
177+
```bash
178+
tiger-agent run --prompts prompts/ --env .env
179+
```
180+
If you open the explorer in [$CONSOLE][portal-ops-mode], you can see the tables used by your $AGENTS_SHORT.
181+
182+
1. In Slack, open a public channel app and ask $AGENTS_SHORT a couple of questions. You see the response in your
183+
public channel and log messages in the Terminal.
184+
185+
![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-terminal.png)
186+
187+
</Procedure>
188+
189+
## Add information from MCP servers to your $AGENTS_SHORT
190+
191+
To increase the amount of specialized information your AI Assistant can use, you can add MCP servers supplying data
192+
your users need. For example, to add the $COMPANY MCP server to your $AGENTS_SHORT:
193+
194+
<Procedure>
195+
196+
1. **Copy the example `mcp_config.json` to your project**
197+
198+
In `my-tiger-agent`, run the following command:
199+
200+
```bash
201+
curl -L -o mcp_config.json https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/examples/mcp_config.json
202+
```
203+
204+
1. **Configure your $AGENTS_SHORT to connect to the most useful MCP servers for your organization**
205+
206+
For example, to add the $COMPANY documentation MCP server to your $AGENTS_SHORT, update the docs entry to the
207+
following:
208+
```json
209+
"docs": {
210+
"tool_prefix": "docs",
211+
"url": "https://mcp.tigerdata.com/docs",
212+
"allow_sampling": false
213+
},
214+
```
215+
To avoid errors, delete all entries in `mcp_config.json` with invalid URLS. For example the `github` entry with `http://github-mcp-server/mcp`.
216+
217+
1. **Restart your $AGENTS_SHORT**
218+
```bash
219+
tiger-agent run --prompts prompts/ --mcp-config mcp_config.json
220+
```
221+
222+
</Procedure>
223+
224+
You have configured your $AGENTS_SHORT to connect to the $MCP_SHORT. For more information,
225+
see [MCP Server Configuration][mcp-configuration-docs].
226+
227+
## Customize prompts for personalization
228+
229+
$AGENTS_LONG uses Jinja2 templates for dynamic, context-aware prompt generation. This system allows for sophisticated
230+
prompts that adapt to conversation context, user preferences, and event metadata. $AGENTS_LONG uses the following
231+
templates:
232+
233+
- `system_prompt.md`: defines the AI Assistant's role, capabilities, and behavior patterns. This template sets the
234+
foundation for the way your $AGENTS_SHORT will respond and interact.
235+
- `user_prompt.md`: formats the user's request with relevant context, providing the AI Assistant with the
236+
information necessary to generate an appropriate response.
237+
238+
To change the way your $AGENTS_SHORTs interact with users in your Slack app:
239+
240+
<Procedure>
241+
242+
1. **Update the prompt**
243+
244+
For example, in `prompts/system_prompt.md`, add another item in the `Response Protocol` section to fine tune
245+
the behaviour of your $AGENTS_SHORTs. For example:
246+
```shell
247+
5. Be snarky but vaguely amusing
248+
```
249+
250+
1. **Test your configuration**
251+
252+
Run $AGENTS_SHORT with your custom prompt:
253+
254+
```bash
255+
tiger-agent run --mcp-config mcp_config.json --prompts prompts/
256+
```
257+
258+
</Procedure>
259+
260+
For more information, see [Prompt tempates][prompt-templates].
261+
262+
## Advanced configuration options
263+
264+
For additional customization, you can modify the following $AGENTS_SHORT parameters:
265+
266+
* `--model`: change AI model (default: `anthropic:claude-sonnet-4-20250514`)
267+
* `--num-workers`: adjust concurrent workers (default: `5`)
268+
* `--max-attempts`: set retry attempts per event (default: `3`)
269+
270+
Example with custom settings:
271+
272+
```bash
273+
tiger-agent run \
274+
--model claude-3-5-sonnet-latest \
275+
--mcp-config mcp_config.json \
276+
--prompts prompts/ \
277+
--num-workers 10 \
278+
--max-attempts 5
279+
```
280+
281+
Your $AGENTS_SHORTs are now configured with $COMPANY MCP server access and personalized prompts.
282+
283+
284+
285+
286+
[jinja-templates]: https://jinja.palletsprojects.com/en/stable/
287+
[logfire]: https://pydantic.dev/logfire
288+
[claude-api-key]: https://console.anthropic.com/settings/keys
289+
[create-a-service]: /getting-started/:currentVersion:/services
290+
[uv-install]: https://docs.astral.sh/uv/getting-started/installation/
291+
[connection-info]: /integrations/:currentVersion:/find-connection-details/
292+
[portal-ops-mode]: https://console.cloud.timescale.com/dashboard/services
293+
[mcp-configuration-docs]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/mcp_config.md
294+
[prompt-templates]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/prompt_templates.md

0 commit comments

Comments
 (0)