From 676966b892f246a7a817e293b5bef627037279b3 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Mon, 6 Oct 2025 17:18:05 +0200 Subject: [PATCH 01/15] chore: tiger agents doc, first draft. --- ai/page-index/page-index.js | 5 + ai/tiger-agents-for-work.md | 286 ++++++++++++++++++++++++++++++++++++ 2 files changed, 291 insertions(+) create mode 100644 ai/tiger-agents-for-work.md diff --git a/ai/page-index/page-index.js b/ai/page-index/page-index.js index 4b3d2bc0f1..bd50240bc1 100644 --- a/ai/page-index/page-index.js +++ b/ai/page-index/page-index.js @@ -7,6 +7,11 @@ module.exports = [ excerpt: "Information about pgai on TigerData and how to use it.", children: [ + { + title: "Incorporate Slack-native AI agents", + href: "tiger-agents-for-work", + excerpt: "Unify company knowledge with slack-native AI agents", + }, { title: "Key vector database concepts", href: "key-vector-database-concepts-for-understanding-pgvector", diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md new file mode 100644 index 0000000000..ffb7b8b307 --- /dev/null +++ b/ai/tiger-agents-for-work.md @@ -0,0 +1,286 @@ +--- +title: Incorporate Slack-native AI agents +excerpt: Unify company knowledge with slack-native AI agents +products: [cloud] +keywords: [ai, vector, pgvector, TigerData vector, pgvectorizer] +tags: [ai, vector, pgvectorizer] +--- + +# Incorporate Slack-native AI agents + +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; + +$AGENTS_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your slack +history, docs, GitHub repositories, salesforce and so on. You use your agent to get instant answers for real business, +technical and progress questions. + +$AGENTS_SHORT is a production-ready library and CLI for building Slack-native agents. $AGENTS_SHORTs can +handle concurrent conversations with enterprise-grade reliability. It has the following features. + +- **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions +- **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load +- **Immediate event processing**: $AGENTS_SHORT provide real-time responsiveness, events are processed within milliseconds of arrival rather than waiting for polling cycles +- **Resilient retry logic**: automatic retry with visibility thresholds, and stuck or expired event cleanup +- **Horizontal scalability**: run multiple $AGENTS_SHORT instances simultaneously with coordinated work distribution across all instances +- **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers +- **Extensible architecture**: zero code integration for basic agents. For more specialized use cases, easily customize your agent using [Jinja templates][jinja-templates] +- **Complete Observability**: detailed tracing of event flow, worker activity, and database operations with full [Logfire][logfire] instrumentation + +This page shows you how to install the $AGENTS_CLI, connect to the $COMPANY MCP server, and customize prompts for +your specific needs. + +## Prerequisites + +* A [Tiger Cloud service][create-a-service] +* The [uv package manager][uv-install] +* An [Anthropic API key][claude-api-key] +* Optional: [Logfire token][logfire] + +## Create a Slack app + +Before installing $AGENTS_SHORT, you need to create a Slack app that the $AGENTS_SHORT will connect to. This app +provides the necessary tokens for Slack integration. + + + +1. **Create a manifest for your Slack App** + + 1. In a temporary directory, download the $AGENTS_SHORT Slack manifest template: + + ```bash + curl -O https://raw.githubusercontent.com/timescale/tiger-agents-for-work/main/slack-manifest.json + ``` + + 1. Edit `slack-manifest.json` to change the app name and description. For example: + + ```json + "display_information": { + "name": "Tiger Agents in Slack", + "description": "Tiger documentation showing how to install and configure a Tiger Agent", + "background_color": "#000000" + }, + "features": { + "bot_user": { + "display_name": "Tiger Agents in Slack", + "always_online": true + } + }, + ``` + + 1. Copy the contents of `slack-manifest.json` to the clipboard: + + ```shell + cat slack-manifest.json| pbcopy + ``` + +1. **Create the Slack app** + + 1. Go to [api.slack.com/apps](https://api.slack.com/apps). + 1. Click `Create New App`. + 1. Select `From an app manifest`. + 1. Choose your workspace, then click `Next`. + 1. Paste the contents of `slack-manifest.json` and click `Next`. + 1. Click `Create`. + +1. **Enable slash commands in your app** + 1. In the left menu, open `App Home` + 1. Enable `Allow users to send Slash commands and messages from the App Home`. + +1. **Generate an app-level token** + + 1. In your app settings, go to `Basic Information`. + 1. Scroll to `App-Level Tokens`. + 1. Click `Generate Token and Scopes`. + 1. Add a `Token Name`, then click `Scope`, add `connections:write` then click `Generate`. + 1. Copy the `xapp-*` token locally and click `Done`. + +1. **Install your app to a Slack workspace** + + 1. In the sidebar, under `Settings`, click `Install App`. + 1. Click `Install to `, then click `Allow`. + 1. Copy the `xoxb-` Bot User OAuth Token locally. + + + +You have created a Slack app and obtained the necessary tokens for $AGENTS_SHORT integration. + + +## Install and configure your $AGENTS_SHORT instance + +$AGENTS_SHORT is a production-ready library and CLI written in Python that you use to create Slack-native AI agents. +This section shows you how to configure $AGENTS_SHORT to connect to your Slack app, and give it access to +data and analytics stored in $CLOUD_LONG. + + + +1. **Create a project directory** + + ```bash + mkdir my-tiger-agent + cd my-tiger-agent + ``` + +1. **Create an $AGENTS_SHORT environment with your Slack, AI Assistant and database configuration** + + 1. Download `.env.sample` to a local `,env` file: + ```shell + curl -L -o .env https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/.env.sample + ``` + 1. In `.env`, add your Slack tokens and Anthropic API key: + + ```bash + # Slack tokens (from the Slack app you created) + SLACK_APP_TOKEN=xapp-your-app-token + SLACK_BOT_TOKEN=xoxb-your-bot-token + + # Anthropic API key + ANTHROPIC_API_KEY=sk-ant-your-api-key + + # Optional: Logfire token for enhanced logging + LOGFIRE_TOKEN=your-logfire-token + ``` + 1. Add the [connection details][connection-info] for the $SERVICE_LONG you are using for this $AGENTS_SHORT: + ```bash + PGHOST= + PGDATABASE=tsdb + PGPORT= + PGUSER=tsdbadmin + PGPASSWORD= + ``` + 1. Save and close `.env`. + +1. **Add the default $AGENTS_SHORT prompts to your project** + ```bash + mkdir prompts + curl -L -o prompts/system_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/system_prompt.md + curl -L -o prompts/user_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/user_prompt.md + ``` + +1. **Install $AGENTS_CLI to manage and run your AI-powered Slack bots** + + 1. Install $AGENTS_SHORT using uv + + ```bash + uv tool install --from git+https://github.com/timescale/tiger-agent.git tiger-agent + ``` + + 1. Verify the installation + + ```bash + tiger-agent --help + ``` + + You see the $AGENTS_CLI help output with available commands and options. + + +1. **Connect your $AGENTS_SHORT with Slack** + + 1. Run your $AGENTS_SHORT: + ```bash + tiger-agent run --prompts prompts/ + ``` + If you open the explorer in [$CONSOLE][portal-ops-mode], you can see the tables used by your $AGENTS_SHORT. + + 1. In Slack, open your app and ask it a couple of questions, enjoy. + +## Add information from MCP servers to your $AGENTS_SHORT + +To increase the amount of specialized information your AI Assistant can use, you can add MCP servers supplying data +your users need. For example, to add the $COMPANY MCP server to your $AGENTS_SHORT: + + + +1. **Copy the example `mcp_config.json` to your project** + + In `my-tiger-agent`, run the following command. + ```bash + curl -L -o mcp_config.json https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/examples/mcp_config.json + ``` + +1. **Configure your $AGENTS_SHORT to connect to the most useful MCP servers for your organization** + + For example, to add the $COMPANY documentation MCP server to your $AGENTS_SHORT, update the docs entry to the + following: + ```json + "docs": { + "tool_prefix": "docs", + "url": "https://mcp.tigerdata.com/docs", + "allow_sampling": false + }, + ``` + +1. **Restart your $AGENTS_SHORT** + ```bash + tiger-agent run --prompts prompts/ --mcp-config mcp_config.json + ``` + + + +You have configured your $AGENTS_SHORT to connect to the $MCP_SHORT. For more information, +see [MCP Server Configuration][mcp-configuration-docs]. + +## Customize prompts for personalization + +$AGENTS_SHORT uses Jinja2 templates for dynamic, context-aware prompt generation. This system allows for sophisticated +prompts that adapt to conversation context, user preferences, and event metadata. $AGENTS_SHORT uses the following templates: + +- `system_prompt.md`: defines the AI Assistant;s role, capabilities, and behavior patterns. This template sets the + foundation for the way your $AGENTS_SHORT will respond and interact. +- `user_prompt.md`: formats the user's request with relevant context, providing the AI Assistant with the + information necessary to generate an appropriate response. + +To change the way your $AGENTS_SHORT interacts with users in your Slack app: + +1. **Update the prompt** + + For example, in `prompts/system_prompt.md`, add another item in the `Response Protocol` section to fine tune + the behaviour of $AGENTS_SHORT. For example: + ```shell + 5. Be snarky but vaguely amusing + ``` + +1. **Test your configuration** + + Run $AGENTS_SHORT with your custom prompt: + + ```bash + tiger-agent run --mcp-config mcp_config.json --prompts prompts/ + ``` + + + +For more information, see [Prompt tempates][prompt-templates]. + +## Advanced configuration options + +For additional customization, you can modify the following $AGENTS_SHORT parameters: + +* `--model`: Change AI model (default: `anthropic:claude-sonnet-4-20250514`) +* `--num-workers`: Adjust concurrent workers (default: 5) +* `--max-attempts`: Set retry attempts per event (default: 3) + +Example with custom settings: + +```bash +tiger-agent run \ + --model claude-3-5-sonnet-latest \ + --mcp-config mcp_config.json \ + --prompts prompts/ \ + --num-workers 10 \ + --max-attempts 5 +``` + +Your $AGENTS_SHORT is now configured with TigerData MCP server access and personalized prompts, ready to help users analyze data from your Tiger Cloud service. + + + + +[jinja-templates]: https://jinja.palletsprojects.com/en/stable/ +[logfire]: https://pydantic.dev/logfire +[claude-api-key]: https://console.anthropic.com/settings/keys +[create-a-service]: /getting-started/:currentVersion:/services +[uv-install]: https://docs.astral.sh/uv/getting-started/installation/ +[connection-info]: /integrations/:currentVersion:/find-connection-details/ +[portal-ops-mode]: https://console.cloud.timescale.com/dashboard/services +[mcp-configuration-docs]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/mcp_config.md +[prompt-templates]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/prompt_templates.md \ No newline at end of file From 78adedb49390fc38d77cced9e412114dc3ad6f9b Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 7 Oct 2025 11:41:27 +0200 Subject: [PATCH 02/15] chore: updates on review. --- ai/tiger-agents-for-work.md | 55 +++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md index ffb7b8b307..f6468fbdc1 100644 --- a/ai/tiger-agents-for-work.md +++ b/ai/tiger-agents-for-work.md @@ -10,17 +10,19 @@ tags: [ai, vector, pgvectorizer] import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; -$AGENTS_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your slack -history, docs, GitHub repositories, salesforce and so on. You use your agent to get instant answers for real business, -technical and progress questions. +$AGENTS_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your Slack +history, docs, GitHub repositories, Salesforce and so on. You use your $AGENTS_LONG to get instant answers for real +business, technical, and operations questions in your Slack channels. + +![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png) $AGENTS_SHORT is a production-ready library and CLI for building Slack-native agents. $AGENTS_SHORTs can -handle concurrent conversations with enterprise-grade reliability. It has the following features. +handle concurrent conversations with enterprise-grade reliability. It has the following features: - **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions - **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load -- **Immediate event processing**: $AGENTS_SHORT provide real-time responsiveness, events are processed within milliseconds of arrival rather than waiting for polling cycles -- **Resilient retry logic**: automatic retry with visibility thresholds, and stuck or expired event cleanup +- **Immediate event processing**: $AGENTS_SHORT provide real-time responsiveness. Events are processed within milliseconds of arrival rather than waiting for polling cycles +- **Resilient retry logic**: automatic retry with visibility thresholds, plus stuck or expired event cleanup - **Horizontal scalability**: run multiple $AGENTS_SHORT instances simultaneously with coordinated work distribution across all instances - **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers - **Extensible architecture**: zero code integration for basic agents. For more specialized use cases, easily customize your agent using [Jinja templates][jinja-templates] @@ -39,7 +41,7 @@ your specific needs. ## Create a Slack app Before installing $AGENTS_SHORT, you need to create a Slack app that the $AGENTS_SHORT will connect to. This app -provides the necessary tokens for Slack integration. +provides the security tokens for Slack integration with your $AGENTS_SHORT: @@ -51,17 +53,17 @@ provides the necessary tokens for Slack integration. curl -O https://raw.githubusercontent.com/timescale/tiger-agents-for-work/main/slack-manifest.json ``` - 1. Edit `slack-manifest.json` to change the app name and description. For example: + 1. Edit `slack-manifest.json` and customize your name and description of your Slack App app. For example: ```json "display_information": { - "name": "Tiger Agents in Slack", - "description": "Tiger documentation showing how to install and configure a Tiger Agent", + "name": "Tiger Agent", + "description": "Tiger AI Agent helps you easily access your business information, and tune your Tiger services", "background_color": "#000000" }, "features": { "bot_user": { - "display_name": "Tiger Agents in Slack", + "display_name": "Tiger Agent", "always_online": true } }, @@ -77,21 +79,16 @@ provides the necessary tokens for Slack integration. 1. Go to [api.slack.com/apps](https://api.slack.com/apps). 1. Click `Create New App`. - 1. Select `From an app manifest`. + 1. Select `From a manifest`. 1. Choose your workspace, then click `Next`. 1. Paste the contents of `slack-manifest.json` and click `Next`. 1. Click `Create`. - -1. **Enable slash commands in your app** - 1. In the left menu, open `App Home` - 1. Enable `Allow users to send Slash commands and messages from the App Home`. - 1. **Generate an app-level token** 1. In your app settings, go to `Basic Information`. 1. Scroll to `App-Level Tokens`. 1. Click `Generate Token and Scopes`. - 1. Add a `Token Name`, then click `Scope`, add `connections:write` then click `Generate`. + 1. Add a `Token Name`, then click `Add Scope`, add `connections:write` then click `Generate`. 1. Copy the `xapp-*` token locally and click `Done`. 1. **Install your app to a Slack workspace** @@ -108,7 +105,7 @@ You have created a Slack app and obtained the necessary tokens for $AGENTS_SHORT ## Install and configure your $AGENTS_SHORT instance $AGENTS_SHORT is a production-ready library and CLI written in Python that you use to create Slack-native AI agents. -This section shows you how to configure $AGENTS_SHORT to connect to your Slack app, and give it access to +This section shows you how to configure $AGENTS_SHORT to connect to your Slack app, and give it access to your data and analytics stored in $CLOUD_LONG. @@ -161,8 +158,9 @@ data and analytics stored in $CLOUD_LONG. 1. Install $AGENTS_SHORT using uv ```bash - uv tool install --from git+https://github.com/timescale/tiger-agent.git tiger-agent + uv tool install --from git+https://github.com/timescale/tiger-agents-for-work.git tiger-agent ``` + `tiger-agent` is installed in `~/.local/bin/tiger-agent`. If necessary, add this folder to your `PATH`. 1. Verify the installation @@ -170,18 +168,22 @@ data and analytics stored in $CLOUD_LONG. tiger-agent --help ``` - You see the $AGENTS_CLI help output with available commands and options. + You see the $AGENTS_CLI help output with the available commands and options. 1. **Connect your $AGENTS_SHORT with Slack** 1. Run your $AGENTS_SHORT: ```bash - tiger-agent run --prompts prompts/ + tiger-agent run --prompts prompts/ --env .env ``` If you open the explorer in [$CONSOLE][portal-ops-mode], you can see the tables used by your $AGENTS_SHORT. - 1. In Slack, open your app and ask it a couple of questions, enjoy. + 1. In Slack, open a public channel app and ask $AGENT_SHORT a couple of questions. You see the response in your + public channel, the output and from the $AGENTS_CLI in the Terminal and your $SERVICE_LONG. + + ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-terminal.png) + ## Add information from MCP servers to your $AGENTS_SHORT @@ -193,9 +195,10 @@ your users need. For example, to add the $COMPANY MCP server to your $AGENTS_SHO 1. **Copy the example `mcp_config.json` to your project** In `my-tiger-agent`, run the following command. - ```bash - curl -L -o mcp_config.json https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/examples/mcp_config.json - ``` + + ```bash + curl -L -o mcp_config.json https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/examples/mcp_config.json + ``` 1. **Configure your $AGENTS_SHORT to connect to the most useful MCP servers for your organization** From d537eb4868d89f2163b6ab8916ac76da5ff37b2f Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 7 Oct 2025 11:51:25 +0200 Subject: [PATCH 03/15] chore: updates on review. --- ai/tiger-agents-for-work.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md index f6468fbdc1..c37f18db4e 100644 --- a/ai/tiger-agents-for-work.md +++ b/ai/tiger-agents-for-work.md @@ -8,16 +8,15 @@ tags: [ai, vector, pgvectorizer] # Incorporate Slack-native AI agents -import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-only.mdx"; $AGENTS_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your Slack -history, docs, GitHub repositories, Salesforce and so on. You use your $AGENTS_LONG to get instant answers for real +history, docs, GitHub repositories, Salesforce and so on. You use your $AGENTS_SHORT to get instant answers for real business, technical, and operations questions in your Slack channels. ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png) -$AGENTS_SHORT is a production-ready library and CLI for building Slack-native agents. $AGENTS_SHORTs can -handle concurrent conversations with enterprise-grade reliability. It has the following features: +$AGENTS_LONG can handle concurrent conversations with enterprise-grade reliability. It has the following features: - **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions - **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load @@ -179,7 +178,7 @@ data and analytics stored in $CLOUD_LONG. ``` If you open the explorer in [$CONSOLE][portal-ops-mode], you can see the tables used by your $AGENTS_SHORT. - 1. In Slack, open a public channel app and ask $AGENT_SHORT a couple of questions. You see the response in your + 1. In Slack, open a public channel app and ask $AGENTS_SHORT a couple of questions. You see the response in your public channel, the output and from the $AGENTS_CLI in the Terminal and your $SERVICE_LONG. ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-terminal.png) From 2ff2646ff12545316275d50956a65cdfb1049b53 Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Tue, 7 Oct 2025 12:49:57 +0200 Subject: [PATCH 04/15] Apply suggestions from code review Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> Signed-off-by: Iain Cox --- ai/tiger-agents-for-work.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md index c37f18db4e..53addb43ba 100644 --- a/ai/tiger-agents-for-work.md +++ b/ai/tiger-agents-for-work.md @@ -25,7 +25,7 @@ $AGENTS_LONG can handle concurrent conversations with enterprise-grade reliabili - **Horizontal scalability**: run multiple $AGENTS_SHORT instances simultaneously with coordinated work distribution across all instances - **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers - **Extensible architecture**: zero code integration for basic agents. For more specialized use cases, easily customize your agent using [Jinja templates][jinja-templates] -- **Complete Observability**: detailed tracing of event flow, worker activity, and database operations with full [Logfire][logfire] instrumentation +- **Complete observability**: detailed tracing of event flow, worker activity, and database operations with full [Logfire][logfire] instrumentation This page shows you how to install the $AGENTS_CLI, connect to the $COMPANY MCP server, and customize prompts for your specific needs. @@ -103,7 +103,7 @@ You have created a Slack app and obtained the necessary tokens for $AGENTS_SHORT ## Install and configure your $AGENTS_SHORT instance -$AGENTS_SHORT is a production-ready library and CLI written in Python that you use to create Slack-native AI agents. +$AGENTS_SHORT are a production-ready library and CLI written in Python that you use to create Slack-native AI agents. This section shows you how to configure $AGENTS_SHORT to connect to your Slack app, and give it access to your data and analytics stored in $CLOUD_LONG. @@ -116,9 +116,9 @@ data and analytics stored in $CLOUD_LONG. cd my-tiger-agent ``` -1. **Create an $AGENTS_SHORT environment with your Slack, AI Assistant and database configuration** +1. **Create a $AGENTS_SHORT environment with your Slack, AI Assistant, and database configuration** - 1. Download `.env.sample` to a local `,env` file: + 1. Download `.env.sample` to a local `.env` file: ```shell curl -L -o .env https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/.env.sample ``` @@ -193,7 +193,7 @@ your users need. For example, to add the $COMPANY MCP server to your $AGENTS_SHO 1. **Copy the example `mcp_config.json` to your project** - In `my-tiger-agent`, run the following command. + In `my-tiger-agent`, run the following command: ```bash curl -L -o mcp_config.json https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/examples/mcp_config.json @@ -224,14 +224,14 @@ see [MCP Server Configuration][mcp-configuration-docs]. ## Customize prompts for personalization $AGENTS_SHORT uses Jinja2 templates for dynamic, context-aware prompt generation. This system allows for sophisticated -prompts that adapt to conversation context, user preferences, and event metadata. $AGENTS_SHORT uses the following templates: +prompts that adapt to conversation context, user preferences, and event metadata. $AGENTS_SHORT use the following templates: -- `system_prompt.md`: defines the AI Assistant;s role, capabilities, and behavior patterns. This template sets the +- `system_prompt.md`: defines the AI Assistant's role, capabilities, and behavior patterns. This template sets the foundation for the way your $AGENTS_SHORT will respond and interact. - `user_prompt.md`: formats the user's request with relevant context, providing the AI Assistant with the information necessary to generate an appropriate response. -To change the way your $AGENTS_SHORT interacts with users in your Slack app: +To change the way your $AGENTS_SHORT interact with users in your Slack app: 1. **Update the prompt** @@ -257,9 +257,9 @@ For more information, see [Prompt tempates][prompt-templates]. For additional customization, you can modify the following $AGENTS_SHORT parameters: -* `--model`: Change AI model (default: `anthropic:claude-sonnet-4-20250514`) -* `--num-workers`: Adjust concurrent workers (default: 5) -* `--max-attempts`: Set retry attempts per event (default: 3) +* `--model`: change AI model (default: `anthropic:claude-sonnet-4-20250514`) +* `--num-workers`: adjust concurrent workers (default: `5`) +* `--max-attempts`: set retry attempts per event (default: `3`) Example with custom settings: @@ -272,7 +272,7 @@ tiger-agent run \ --max-attempts 5 ``` -Your $AGENTS_SHORT is now configured with TigerData MCP server access and personalized prompts, ready to help users analyze data from your Tiger Cloud service. +Your $AGENTS_SHORT are now configured with $COMPANY MCP server access and personalized prompts, ready to help users analyze data from your $SERVICE_LONG. From 8f5c84843b76fabe125d6f8dfffb20d5e417cf0c Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 7 Oct 2025 12:55:15 +0200 Subject: [PATCH 05/15] chore: updates on review. --- ai/tiger-agents-for-work.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md index 53addb43ba..14f5e99a63 100644 --- a/ai/tiger-agents-for-work.md +++ b/ai/tiger-agents-for-work.md @@ -16,7 +16,7 @@ business, technical, and operations questions in your Slack channels. ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png) -$AGENTS_LONG can handle concurrent conversations with enterprise-grade reliability. It has the following features: +$AGENTS_LONG can handle concurrent conversations with enterprise-grade reliability. They has the following features: - **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions - **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load @@ -52,7 +52,7 @@ provides the security tokens for Slack integration with your $AGENTS_SHORT: curl -O https://raw.githubusercontent.com/timescale/tiger-agents-for-work/main/slack-manifest.json ``` - 1. Edit `slack-manifest.json` and customize your name and description of your Slack App app. For example: + 1. Edit `slack-manifest.json` and customize your name and description of your Slack App. For example: ```json "display_information": { @@ -104,7 +104,7 @@ You have created a Slack app and obtained the necessary tokens for $AGENTS_SHORT ## Install and configure your $AGENTS_SHORT instance $AGENTS_SHORT are a production-ready library and CLI written in Python that you use to create Slack-native AI agents. -This section shows you how to configure $AGENTS_SHORT to connect to your Slack app, and give it access to your +This section shows you how to configure $AGENTS_SHORT to connect to your Slack app, and give them access to your data and analytics stored in $CLOUD_LONG. @@ -179,10 +179,11 @@ data and analytics stored in $CLOUD_LONG. If you open the explorer in [$CONSOLE][portal-ops-mode], you can see the tables used by your $AGENTS_SHORT. 1. In Slack, open a public channel app and ask $AGENTS_SHORT a couple of questions. You see the response in your - public channel, the output and from the $AGENTS_CLI in the Terminal and your $SERVICE_LONG. + public channel and log messages in the Terminal. ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-terminal.png) - + + ## Add information from MCP servers to your $AGENTS_SHORT @@ -233,6 +234,8 @@ prompts that adapt to conversation context, user preferences, and event metadata To change the way your $AGENTS_SHORT interact with users in your Slack app: + + 1. **Update the prompt** For example, in `prompts/system_prompt.md`, add another item in the `Response Protocol` section to fine tune From 9ab978008be4a9fd68806188a8465dc8b4020e4f Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 7 Oct 2025 13:01:57 +0200 Subject: [PATCH 06/15] chore: updates on review. --- ai/tiger-agents-for-work.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md index 14f5e99a63..de0d393b98 100644 --- a/ai/tiger-agents-for-work.md +++ b/ai/tiger-agents-for-work.md @@ -20,7 +20,7 @@ $AGENTS_LONG can handle concurrent conversations with enterprise-grade reliabili - **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions - **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load -- **Immediate event processing**: $AGENTS_SHORT provide real-time responsiveness. Events are processed within milliseconds of arrival rather than waiting for polling cycles +- **Immediate event processing**: $AGENTS_LONG provide real-time responsiveness. Events are processed within milliseconds of arrival rather than waiting for polling cycles - **Resilient retry logic**: automatic retry with visibility thresholds, plus stuck or expired event cleanup - **Horizontal scalability**: run multiple $AGENTS_SHORT instances simultaneously with coordinated work distribution across all instances - **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers @@ -39,7 +39,7 @@ your specific needs. ## Create a Slack app -Before installing $AGENTS_SHORT, you need to create a Slack app that the $AGENTS_SHORT will connect to. This app +Before installing $AGENTS_LONG, you need to create a Slack app that the $AGENTS_SHORT will connect to. This app provides the security tokens for Slack integration with your $AGENTS_SHORT: @@ -103,8 +103,8 @@ You have created a Slack app and obtained the necessary tokens for $AGENTS_SHORT ## Install and configure your $AGENTS_SHORT instance -$AGENTS_SHORT are a production-ready library and CLI written in Python that you use to create Slack-native AI agents. -This section shows you how to configure $AGENTS_SHORT to connect to your Slack app, and give them access to your +$AGENTS_LONG are a production-ready library and CLI written in Python that you use to create Slack-native AI agents. +This section shows you how to configure a $AGENTS_SHORT to connect to your Slack app, and give them access to your data and analytics stored in $CLOUD_LONG. @@ -152,16 +152,16 @@ data and analytics stored in $CLOUD_LONG. curl -L -o prompts/user_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/user_prompt.md ``` -1. **Install $AGENTS_CLI to manage and run your AI-powered Slack bots** +1. **Install $AGENTS_LONG to manage and run your AI-powered Slack bots** - 1. Install $AGENTS_SHORT using uv + 1. Install the $AGENTS_CLI using uv. ```bash uv tool install --from git+https://github.com/timescale/tiger-agents-for-work.git tiger-agent ``` `tiger-agent` is installed in `~/.local/bin/tiger-agent`. If necessary, add this folder to your `PATH`. - 1. Verify the installation + 1. Verify the installation. ```bash tiger-agent --help @@ -224,22 +224,23 @@ see [MCP Server Configuration][mcp-configuration-docs]. ## Customize prompts for personalization -$AGENTS_SHORT uses Jinja2 templates for dynamic, context-aware prompt generation. This system allows for sophisticated -prompts that adapt to conversation context, user preferences, and event metadata. $AGENTS_SHORT use the following templates: +$AGENTS_LONG uses Jinja2 templates for dynamic, context-aware prompt generation. This system allows for sophisticated +prompts that adapt to conversation context, user preferences, and event metadata. $AGENTS_LONG uses the following +templates: - `system_prompt.md`: defines the AI Assistant's role, capabilities, and behavior patterns. This template sets the foundation for the way your $AGENTS_SHORT will respond and interact. - `user_prompt.md`: formats the user's request with relevant context, providing the AI Assistant with the information necessary to generate an appropriate response. -To change the way your $AGENTS_SHORT interact with users in your Slack app: +To change the way your $AGENTS_SHORTs interact with users in your Slack app: 1. **Update the prompt** For example, in `prompts/system_prompt.md`, add another item in the `Response Protocol` section to fine tune - the behaviour of $AGENTS_SHORT. For example: + the behaviour of your $AGENTS_SHORTs. For example: ```shell 5. Be snarky but vaguely amusing ``` @@ -275,7 +276,7 @@ tiger-agent run \ --max-attempts 5 ``` -Your $AGENTS_SHORT are now configured with $COMPANY MCP server access and personalized prompts, ready to help users analyze data from your $SERVICE_LONG. +Your $AGENTS_SHORTs are now configured with $COMPANY MCP server access and personalized prompts. From 422112040e61d6b95fcb39c327c390f71d8c1505 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 7 Oct 2025 16:00:52 +0200 Subject: [PATCH 07/15] chore: mcp config update. --- ai/tiger-agents-for-work.md | 1 + 1 file changed, 1 insertion(+) diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md index de0d393b98..27140bcfe6 100644 --- a/ai/tiger-agents-for-work.md +++ b/ai/tiger-agents-for-work.md @@ -211,6 +211,7 @@ your users need. For example, to add the $COMPANY MCP server to your $AGENTS_SHO "allow_sampling": false }, ``` + To avoid errors, delete all entries in `mcp_config.json` with invalid URLS. For example the `github` entry with `http://github-mcp-server/mcp`. 1. **Restart your $AGENTS_SHORT** ```bash From fad0eca6ce0fdc7f121fd3c9f4c1d497057cca7b Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 14 Oct 2025 18:16:58 +0200 Subject: [PATCH 08/15] chore: update for EON. --- ai/tiger-agents-for-work-old.md | 300 ++++++++++++++++++++++++++++++ ai/tiger-agents-for-work.md | 318 +++++++++----------------------- 2 files changed, 390 insertions(+), 228 deletions(-) create mode 100644 ai/tiger-agents-for-work-old.md diff --git a/ai/tiger-agents-for-work-old.md b/ai/tiger-agents-for-work-old.md new file mode 100644 index 0000000000..faad7b9822 --- /dev/null +++ b/ai/tiger-agents-for-work-old.md @@ -0,0 +1,300 @@ +--- +title: Incorporate Slack-native AI agents +excerpt: Unify company knowledge with slack-native AI agents +products: [cloud] +keywords: [ai, vector, pgvector, TigerData vector, pgvectorizer] +tags: [ai, vector, pgvectorizer] +--- + +# Incorporate Slack-native AI agents + +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-only.mdx"; + +$AGENTS_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your Slack +history, docs, GitHub repositories, Salesforce and so on. You use your $AGENTS_SHORT to get instant answers for real +business, technical, and operations questions in your Slack channels. + +![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png) + +$AGENTS_LONG can handle concurrent conversations with enterprise-grade reliability. They has the following features: + +- **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions +- **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load +- **Immediate event processing**: $AGENTS_LONG provide real-time responsiveness. Events are processed within milliseconds of arrival rather than waiting for polling cycles +- **Resilient retry logic**: automatic retry with visibility thresholds, plus stuck or expired event cleanup +- **Horizontal scalability**: run multiple $AGENTS_SHORT instances simultaneously with coordinated work distribution across all instances +- **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers +- **Extensible architecture**: zero code integration for basic agents. For more specialized use cases, easily customize your agent using [Jinja templates][jinja-templates] +- **Complete observability**: detailed tracing of event flow, worker activity, and database operations with full [Logfire][logfire] instrumentation + +This page shows you how to install the $AGENTS_CLI, connect to the $COMPANY MCP server, and customize prompts for +your specific needs. + +## Prerequisites + +* A [Tiger Cloud service][create-a-service] +* The [uv package manager][uv-install] +* An [Anthropic API key][claude-api-key] +* Optional: [Logfire token][logfire] + + + + +## Manual install + +IAIN: to update + +### Create a Slack app + +Before installing $AGENTS_LONG, you need to create a Slack app that the $AGENTS_SHORT will connect to. This app +provides the security tokens for Slack integration with your $AGENTS_SHORT: + + + +1. **Create a manifest for your Slack App** + + 1. In a temporary directory, download the $AGENTS_SHORT Slack manifest template: + + ```bash + curl -O https://raw.githubusercontent.com/timescale/tiger-agents-for-work/main/slack-manifest.json + ``` + + 1. Edit `slack-manifest.json` and customize your name and description of your Slack App. For example: + + ```json + "display_information": { + "name": "Tiger Agent", + "description": "Tiger AI Agent helps you easily access your business information, and tune your Tiger services", + "background_color": "#000000" + }, + "features": { + "bot_user": { + "display_name": "Tiger Agent", + "always_online": true + } + }, + ``` + + 1. Copy the contents of `slack-manifest.json` to the clipboard: + + ```shell + cat slack-manifest.json| pbcopy + ``` + +1. **Create the Slack app** + + 1. Go to [api.slack.com/apps](https://api.slack.com/apps). + 1. Click `Create New App`. + 1. Select `From a manifest`. + 1. Choose your workspace, then click `Next`. + 1. Paste the contents of `slack-manifest.json` and click `Next`. + 1. Click `Create`. +1. **Generate an app-level token** + + 1. In your app settings, go to `Basic Information`. + 1. Scroll to `App-Level Tokens`. + 1. Click `Generate Token and Scopes`. + 1. Add a `Token Name`, then click `Add Scope`, add `connections:write` then click `Generate`. + 1. Copy the `xapp-*` token locally and click `Done`. + +1. **Install your app to a Slack workspace** + + 1. In the sidebar, under `Settings`, click `Install App`. + 1. Click `Install to `, then click `Allow`. + 1. Copy the `xoxb-` Bot User OAuth Token locally. + + + +You have created a Slack app and obtained the necessary tokens for $AGENTS_SHORT integration. + + +### Install and configure your $AGENTS_SHORT instance + +$AGENTS_LONG are a production-ready library and CLI written in Python that you use to create Slack-native AI agents. +This section shows you how to configure a $AGENTS_SHORT to connect to your Slack app, and give them access to your +data and analytics stored in $CLOUD_LONG. + + + +1. **Create a project directory** + + ```bash + mkdir my-tiger-agent + cd my-tiger-agent + ``` + +1. **Create a $AGENTS_SHORT environment with your Slack, AI Assistant, and database configuration** + + 1. Download `.env.sample` to a local `.env` file: + ```shell + curl -L -o .env https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/.env.sample + ``` + 1. In `.env`, add your Slack tokens and Anthropic API key: + + ```bash + # Slack tokens (from the Slack app you created) + SLACK_APP_TOKEN=xapp-your-app-token + SLACK_BOT_TOKEN=xoxb-your-bot-token + + # Anthropic API key + ANTHROPIC_API_KEY=sk-ant-your-api-key + + # Optional: Logfire token for enhanced logging + LOGFIRE_TOKEN=your-logfire-token + ``` + 1. Add the [connection details][connection-info] for the $SERVICE_LONG you are using for this $AGENTS_SHORT: + ```bash + PGHOST= + PGDATABASE=tsdb + PGPORT= + PGUSER=tsdbadmin + PGPASSWORD= + ``` + 1. Save and close `.env`. + +1. **Add the default $AGENTS_SHORT prompts to your project** + ```bash + mkdir prompts + curl -L -o prompts/system_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/system_prompt.md + curl -L -o prompts/user_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/user_prompt.md + ``` + +1. **Install $AGENTS_LONG to manage and run your AI-powered Slack bots** + + 1. Install the $AGENTS_CLI using uv. + + ```bash + uv tool install --from git+https://github.com/timescale/tiger-agents-for-work.git tiger-agent + ``` + `tiger-agent` is installed in `~/.local/bin/tiger-agent`. If necessary, add this folder to your `PATH`. + + 1. Verify the installation. + + ```bash + tiger-agent --help + ``` + + You see the $AGENTS_CLI help output with the available commands and options. + + +1. **Connect your $AGENTS_SHORT with Slack** + + 1. Run your $AGENTS_SHORT: + ```bash + tiger-agent run --prompts prompts/ --env .env + ``` + If you open the explorer in [$CONSOLE][portal-ops-mode], you can see the tables used by your $AGENTS_SHORT. + + 1. In Slack, open a public channel app and ask $AGENTS_SHORT a couple of questions. You see the response in your + public channel and log messages in the Terminal. + + ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-terminal.png) + + + +### Add information from MCP servers to your $AGENTS_SHORT + +To increase the amount of specialized information your AI Assistant can use, you can add MCP servers supplying data +your users need. For example, to add the $COMPANY MCP server to your $AGENTS_SHORT: + + + +1. **Copy the example `mcp_config.json` to your project** + + In `my-tiger-agent`, run the following command: + + ```bash + curl -L -o mcp_config.json https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/examples/mcp_config.json + ``` + +1. **Configure your $AGENTS_SHORT to connect to the most useful MCP servers for your organization** + + For example, to add the $COMPANY documentation MCP server to your $AGENTS_SHORT, update the docs entry to the + following: + ```json + "docs": { + "tool_prefix": "docs", + "url": "https://mcp.tigerdata.com/docs", + "allow_sampling": false + }, + ``` + To avoid errors, delete all entries in `mcp_config.json` with invalid URLS. For example the `github` entry with `http://github-mcp-server/mcp`. + +1. **Restart your $AGENTS_SHORT** + ```bash + tiger-agent run --prompts prompts/ --mcp-config mcp_config.json + ``` + + + +You have configured your $AGENTS_SHORT to connect to the $MCP_SHORT. For more information, +see [MCP Server Configuration][mcp-configuration-docs]. + +### Customize prompts for personalization + +$AGENTS_LONG uses Jinja2 templates for dynamic, context-aware prompt generation. This system allows for sophisticated +prompts that adapt to conversation context, user preferences, and event metadata. $AGENTS_LONG uses the following +templates: + +- `system_prompt.md`: defines the AI Assistant's role, capabilities, and behavior patterns. This template sets the + foundation for the way your $AGENTS_SHORT will respond and interact. +- `user_prompt.md`: formats the user's request with relevant context, providing the AI Assistant with the + information necessary to generate an appropriate response. + +To change the way your $AGENTS_SHORTs interact with users in your Slack app: + + + +1. **Update the prompt** + + For example, in `prompts/system_prompt.md`, add another item in the `Response Protocol` section to fine tune + the behaviour of your $AGENTS_SHORTs. For example: + ```shell + 5. Be snarky but vaguely amusing + ``` + +1. **Test your configuration** + + Run $AGENTS_SHORT with your custom prompt: + + ```bash + tiger-agent run --mcp-config mcp_config.json --prompts prompts/ + ``` + + + +For more information, see [Prompt tempates][prompt-templates]. + +## Advanced configuration options + +For additional customization, you can modify the following $AGENTS_SHORT parameters: + +* `--model`: change AI model (default: `anthropic:claude-sonnet-4-20250514`) +* `--num-workers`: adjust concurrent workers (default: `5`) +* `--max-attempts`: set retry attempts per event (default: `3`) + +Example with custom settings: + +```bash +tiger-agent run \ + --model claude-3-5-sonnet-latest \ + --mcp-config mcp_config.json \ + --prompts prompts/ \ + --num-workers 10 \ + --max-attempts 5 +``` + +Your $AGENTS_SHORTs are now configured with $COMPANY MCP server access and personalized prompts. + + + + +[jinja-templates]: https://jinja.palletsprojects.com/en/stable/ +[logfire]: https://pydantic.dev/logfire +[claude-api-key]: https://console.anthropic.com/settings/keys +[create-a-service]: /getting-started/:currentVersion:/services +[uv-install]: https://docs.astral.sh/uv/getting-started/installation/ +[connection-info]: /integrations/:currentVersion:/find-connection-details/ +[portal-ops-mode]: https://console.cloud.timescale.com/dashboard/services +[mcp-configuration-docs]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/mcp_config.md +[prompt-templates]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/prompt_templates.md \ No newline at end of file diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md index 27140bcfe6..53919d9c03 100644 --- a/ai/tiger-agents-for-work.md +++ b/ai/tiger-agents-for-work.md @@ -1,284 +1,142 @@ --- title: Incorporate Slack-native AI agents excerpt: Unify company knowledge with slack-native AI agents -products: [cloud] +products: [cloud, self_hosted] keywords: [ai, vector, pgvector, TigerData vector, pgvectorizer] tags: [ai, vector, pgvectorizer] --- -# Incorporate Slack-native AI agents +import ImportPrerequisites from "versionContent/_partials/_prereqs-cloud-and-self.mdx"; -import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-only.mdx"; +# Incorporate Slack-native AI agents -$AGENTS_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your Slack -history, docs, GitHub repositories, Salesforce and so on. You use your $AGENTS_SHORT to get instant answers for real -business, technical, and operations questions in your Slack channels. +$EON_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your Slack +history, docs, GitHub repositories, Salesforce and so on. You use $EON_SHORT to get instant answers for real +business, technical, and operations questions in your Slack channels. ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png) -$AGENTS_LONG can handle concurrent conversations with enterprise-grade reliability. They has the following features: +$EON_LONG can handle concurrent conversations with enterprise-grade reliability. It has the following features: - **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions - **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load -- **Immediate event processing**: $AGENTS_LONG provide real-time responsiveness. Events are processed within milliseconds of arrival rather than waiting for polling cycles +- **Immediate event processing**: $EON_LONG provide real-time responsiveness. Events are processed within milliseconds of arrival rather than waiting for polling cycles - **Resilient retry logic**: automatic retry with visibility thresholds, plus stuck or expired event cleanup -- **Horizontal scalability**: run multiple $AGENTS_SHORT instances simultaneously with coordinated work distribution across all instances -- **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers -- **Extensible architecture**: zero code integration for basic agents. For more specialized use cases, easily customize your agent using [Jinja templates][jinja-templates] -- **Complete observability**: detailed tracing of event flow, worker activity, and database operations with full [Logfire][logfire] instrumentation +- **Horizontal scalability**: run multiple $EON_SHORT instances simultaneously with coordinated work distribution across all instances +- **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers +- **Extensible architecture**: zero code integration for basic agents. For more specialized use cases, easily customize your agent using [Jinja templates][jinja-templates] +- **Complete observability**: detailed tracing of event flow, worker activity, and database operations with full [Logfire][logfire] instrumentation This page shows you how to install the $AGENTS_CLI, connect to the $COMPANY MCP server, and customize prompts for your specific needs. ## Prerequisites -* A [Tiger Cloud service][create-a-service] -* The [uv package manager][uv-install] -* An [Anthropic API key][claude-api-key] -* Optional: [Logfire token][logfire] - -## Create a Slack app - -Before installing $AGENTS_LONG, you need to create a Slack app that the $AGENTS_SHORT will connect to. This app -provides the security tokens for Slack integration with your $AGENTS_SHORT: - - - -1. **Create a manifest for your Slack App** - - 1. In a temporary directory, download the $AGENTS_SHORT Slack manifest template: - - ```bash - curl -O https://raw.githubusercontent.com/timescale/tiger-agents-for-work/main/slack-manifest.json - ``` - - 1. Edit `slack-manifest.json` and customize your name and description of your Slack App. For example: - - ```json - "display_information": { - "name": "Tiger Agent", - "description": "Tiger AI Agent helps you easily access your business information, and tune your Tiger services", - "background_color": "#000000" - }, - "features": { - "bot_user": { - "display_name": "Tiger Agent", - "always_online": true - } - }, - ``` - - 1. Copy the contents of `slack-manifest.json` to the clipboard: - - ```shell - cat slack-manifest.json| pbcopy - ``` + -1. **Create the Slack app** +- [Install Docker][install-docker] on your developer device - 1. Go to [api.slack.com/apps](https://api.slack.com/apps). - 1. Click `Create New App`. - 1. Select `From a manifest`. - 1. Choose your workspace, then click `Next`. - 1. Paste the contents of `slack-manifest.json` and click `Next`. - 1. Click `Create`. -1. **Generate an app-level token** - - 1. In your app settings, go to `Basic Information`. - 1. Scroll to `App-Level Tokens`. - 1. Click `Generate Token and Scopes`. - 1. Add a `Token Name`, then click `Add Scope`, add `connections:write` then click `Generate`. - 1. Copy the `xapp-*` token locally and click `Done`. - -1. **Install your app to a Slack workspace** +* IAIN, let's see. An [Anthropic API key][claude-api-key] +* Optional: [Logfire token][logfire] - 1. In the sidebar, under `Settings`, click `Install App`. - 1. Click `Install to `, then click `Allow`. - 1. Copy the `xoxb-` Bot User OAuth Token locally. - +## Interactive setup -You have created a Slack app and obtained the necessary tokens for $AGENTS_SHORT integration. +$EON_LONG is a production-ready repository running [$CLI_LONG][tiger-cli] and [$AGENTS_LONG][tiger-agents] that creates +and runs the following components for you: +- An ingest Slack app that receive all messages and reactions from the public channels in your Slack workspace +- A listener Slack App for the agent that receive @mentions to it +- A $SERVICE_LONG instance that stores data from the Slack apps -## Install and configure your $AGENTS_SHORT instance +If [$CLI_LONG][tiger-cli] and [$AGENTS_LONG][tiger-agents] are installed locally, $EON_LONG calls the local apps. If not, +$EON_LONG runs them in Docker. -$AGENTS_LONG are a production-ready library and CLI written in Python that you use to create Slack-native AI agents. -This section shows you how to configure a $AGENTS_SHORT to connect to your Slack app, and give them access to your +This section shows you how to configure $EON_SHORT to connect to your Slack app, and give them access to your data and analytics stored in $CLOUD_LONG. -1. **Create a project directory** - - ```bash - mkdir my-tiger-agent - cd my-tiger-agent - ``` - -1. **Create a $AGENTS_SHORT environment with your Slack, AI Assistant, and database configuration** - - 1. Download `.env.sample` to a local `.env` file: - ```shell - curl -L -o .env https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/.env.sample - ``` - 1. In `.env`, add your Slack tokens and Anthropic API key: +1. **Install $EON_LONG to manage and run your AI-powered Slack bots** - ```bash - # Slack tokens (from the Slack app you created) - SLACK_APP_TOKEN=xapp-your-app-token - SLACK_BOT_TOKEN=xoxb-your-bot-token - - # Anthropic API key - ANTHROPIC_API_KEY=sk-ant-your-api-key - - # Optional: Logfire token for enhanced logging - LOGFIRE_TOKEN=your-logfire-token - ``` - 1. Add the [connection details][connection-info] for the $SERVICE_LONG you are using for this $AGENTS_SHORT: - ```bash - PGHOST= - PGDATABASE=tsdb - PGPORT= - PGUSER=tsdbadmin - PGPASSWORD= - ``` - 1. Save and close `.env`. - -1. **Add the default $AGENTS_SHORT prompts to your project** - ```bash - mkdir prompts - curl -L -o prompts/system_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/system_prompt.md - curl -L -o prompts/user_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/user_prompt.md - ``` - -1. **Install $AGENTS_LONG to manage and run your AI-powered Slack bots** - - 1. Install the $AGENTS_CLI using uv. - - ```bash - uv tool install --from git+https://github.com/timescale/tiger-agents-for-work.git tiger-agent - ``` - `tiger-agent` is installed in `~/.local/bin/tiger-agent`. If necessary, add this folder to your `PATH`. - - 1. Verify the installation. - - ```bash - tiger-agent --help - ``` - - You see the $AGENTS_CLI help output with the available commands and options. - - -1. **Connect your $AGENTS_SHORT with Slack** + In a local folder, run the following command from the terminal. + ```shell + git clone git@github.com:timescale/tiger-eon.git + ``` - 1. Run your $AGENTS_SHORT: - ```bash - tiger-agent run --prompts prompts/ --env .env - ``` - If you open the explorer in [$CONSOLE][portal-ops-mode], you can see the tables used by your $AGENTS_SHORT. +1. **Configure $EON_SHORT** - 1. In Slack, open a public channel app and ask $AGENTS_SHORT a couple of questions. You see the response in your - public channel and log messages in the Terminal. + The interactive setup creates and configures the Slack apps and the $SERVICE_LONG for $EON_SHORT to run correctly: - ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-terminal.png) - - - -## Add information from MCP servers to your $AGENTS_SHORT - -To increase the amount of specialized information your AI Assistant can use, you can add MCP servers supplying data -your users need. For example, to add the $COMPANY MCP server to your $AGENTS_SHORT: - - - -1. **Copy the example `mcp_config.json` to your project** - - In `my-tiger-agent`, run the following command: - - ```bash - curl -L -o mcp_config.json https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/examples/mcp_config.json - ``` - -1. **Configure your $AGENTS_SHORT to connect to the most useful MCP servers for your organization** - - For example, to add the $COMPANY documentation MCP server to your $AGENTS_SHORT, update the docs entry to the - following: - ```json - "docs": { - "tool_prefix": "docs", - "url": "https://mcp.tigerdata.com/docs", - "allow_sampling": false - }, - ``` - To avoid errors, delete all entries in `mcp_config.json` with invalid URLS. For example the `github` entry with `http://github-mcp-server/mcp`. - -1. **Restart your $AGENTS_SHORT** - ```bash - tiger-agent run --prompts prompts/ --mcp-config mcp_config.json +1. **Start the interactive setup** + + ```shell + cd tiger-eon + ./setup-tiger-eon.sh ``` + You see a resume of the setup procedure. Type `y` and press `Enter`. + +1. **Create the $SERVICE_LONG to use with $EON_SHORT** + + You see `Do you want to use a free tier Tiger Cloud Database? [y/N]:`. Press `Y` to create a free + $SERVICE_LONG. - - -You have configured your $AGENTS_SHORT to connect to the $MCP_SHORT. For more information, -see [MCP Server Configuration][mcp-configuration-docs]. - -## Customize prompts for personalization - -$AGENTS_LONG uses Jinja2 templates for dynamic, context-aware prompt generation. This system allows for sophisticated -prompts that adapt to conversation context, user preferences, and event metadata. $AGENTS_LONG uses the following -templates: - -- `system_prompt.md`: defines the AI Assistant's role, capabilities, and behavior patterns. This template sets the - foundation for the way your $AGENTS_SHORT will respond and interact. -- `user_prompt.md`: formats the user's request with relevant context, providing the AI Assistant with the - information necessary to generate an appropriate response. - -To change the way your $AGENTS_SHORTs interact with users in your Slack app: - - + $EON_SHORT opens the $CLOUD_LONG authentication page in your browser. Click `Authorize`. $EON_SHORT creates a + $SERVICE_LONG called [tiger-eon][services-portal] and stores the credentials in your local keychain. -1. **Update the prompt** + If you press `N`, the interactive setup creates and runs $TIMESCALE_DB in a local Docker container. - For example, in `prompts/system_prompt.md`, add another item in the `Response Protocol` section to fine tune - the behaviour of your $AGENTS_SHORTs. For example: - ```shell - 5. Be snarky but vaguely amusing - ``` +1. **Create the ingest Slack app** -1. **Test your configuration** + 1. In terminal, name your ingest Slack app: - Run $AGENTS_SHORT with your custom prompt: + 1. $EON_SHORT proposes to create an ingest app called `tiger-slack-ingest`, press `Enter`. + 1. Do the same for the App description. - ```bash - tiger-agent run --mcp-config mcp_config.json --prompts prompts/ - ``` + $EON_SHORT opens `Your Apps` in `api.slack.com`. + + 1. Start configuring your ingest app in Slack: + In the Slack `Your Apps` page: + 1. Click `Create New App`, click `From an manifest`, then select a workspace. + 1. Click `Next`. Slack opens `Create app from manifest`. + + 1. Add the Slack app manifest: + 1. In terminal press `Enter`. The setup prints the Slack app manifest to terminal. + 1. In the Slack `Create app from manifest` window, paste the manifest, + 1. Click `Next`, then click `Create`. - + 1. Configure an app-level token -For more information, see [Prompt tempates][prompt-templates]. + 1. In your app settings, go to `Basic Information`. + 1. Scroll to `App-Level Tokens`. + 1. Click `Generate Token and Scopes`. + 1. Add a `Token Name`, then click `Add Scope`, add `connections:write` then click `Generate`. + 1. Copy the `xapp-*` token and click `Done`. + 1. In terminal, paste the token, then press `Enter`. -## Advanced configuration options + 1. Configure a bot user OAuth token: -For additional customization, you can modify the following $AGENTS_SHORT parameters: + 1. In your app settings, under `Features`, click `App Home`. + 1. Scroll down, then enable `Allow users to send Slash commands and messages from the messages tab`. + 1. In your app settings, under `Settings`, click `Install App`. + 1. Click `Install to `, then click `Allow`. + 1. Copy the `xoxb-` Bot User OAuth Token locally. + 1. In terminal, paste the token, then press `Enter`. -* `--model`: change AI model (default: `anthropic:claude-sonnet-4-20250514`) -* `--num-workers`: adjust concurrent workers (default: `5`) -* `--max-attempts`: set retry attempts per event (default: `3`) +1. **Create the $AGENT_SHORT Slack app** -Example with custom settings: + Follow the same procedure as you did for the ingest Slack app. -```bash -tiger-agent run \ - --model claude-3-5-sonnet-latest \ - --mcp-config mcp_config.json \ - --prompts prompts/ \ - --num-workers 10 \ - --max-attempts 5 -``` +1. **Add your Anthropic API key** -Your $AGENTS_SHORTs are now configured with $COMPANY MCP server access and personalized prompts. + The interactive setup opens https://console.anthropic.com/settings/keys. Create a Claude Code key, then + paste it in the terminal. +1. **Add your Logfire token** + + If you would like to integrate logfire with $EON_SHORT, paste your token and press `Enter`. If not, press `Enter`. + + @@ -290,4 +148,8 @@ Your $AGENTS_SHORTs are now configured with $COMPANY MCP server access and perso [connection-info]: /integrations/:currentVersion:/find-connection-details/ [portal-ops-mode]: https://console.cloud.timescale.com/dashboard/services [mcp-configuration-docs]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/mcp_config.md -[prompt-templates]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/prompt_templates.md \ No newline at end of file +[prompt-templates]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/prompt_templates.md +[install-docker]: https://docs.docker.com/engine/install/ +[tiger-cli]: https://github.com/timescale/tiger-cli/ +[tiger-agents]: https://github.com/timescale/tiger-agents-for-work +[services-portal]: https://console.cloud.timescale.com/dashboard/services \ No newline at end of file From b60727765e45b20c01008dd968f902affcbd41e8 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Wed, 15 Oct 2025 11:51:18 +0200 Subject: [PATCH 09/15] chore: update for EON. --- _partials/_prereqs-cloud-project-and-self.md | 8 + ai/page-index/page-index.js | 11 +- ai/tiger-agents-for-work-old.md | 300 ----------------- ai/tiger-agents-for-work.md | 320 +++++++++++++------ ai/tiger-eon.md | 182 +++++++++++ 5 files changed, 427 insertions(+), 394 deletions(-) create mode 100644 _partials/_prereqs-cloud-project-and-self.md delete mode 100644 ai/tiger-agents-for-work-old.md create mode 100644 ai/tiger-eon.md diff --git a/_partials/_prereqs-cloud-project-and-self.md b/_partials/_prereqs-cloud-project-and-self.md new file mode 100644 index 0000000000..846e6defbc --- /dev/null +++ b/_partials/_prereqs-cloud-project-and-self.md @@ -0,0 +1,8 @@ +To follow the procedure on this page you need to: + +* Create a [$ACCOUNT_LONG][create-account]. + + This procedure also works for [$SELF_LONG][enable-timescaledb]. + +[create-account]: /getting-started/:currentVersion:/services/#create-a-tiger-account +[enable-timescaledb]: /self-hosted/:currentVersion:/install/ diff --git a/ai/page-index/page-index.js b/ai/page-index/page-index.js index bd50240bc1..4bc352130d 100644 --- a/ai/page-index/page-index.js +++ b/ai/page-index/page-index.js @@ -1,6 +1,6 @@ module.exports = [ { - title: "AI and Vector: pgai on Tiger Cloud", + title: "AI and Vector", href: "ai", filePath: "index.md", pageComponents: ["featured-cards"], @@ -8,10 +8,15 @@ module.exports = [ "Information about pgai on TigerData and how to use it.", children: [ { - title: "Incorporate Slack-native AI agents", - href: "tiger-agents-for-work", + title: "Aggregate organizational data with AI agents", + href: "tiger-eon", excerpt: "Unify company knowledge with slack-native AI agents", }, + { + title: "Integrate a slack-native AI agent", + href: "tiger-agents-for-work", + excerpt: "Configure a Slack-native AI agent to do what you want", + }, { title: "Key vector database concepts", href: "key-vector-database-concepts-for-understanding-pgvector", diff --git a/ai/tiger-agents-for-work-old.md b/ai/tiger-agents-for-work-old.md deleted file mode 100644 index faad7b9822..0000000000 --- a/ai/tiger-agents-for-work-old.md +++ /dev/null @@ -1,300 +0,0 @@ ---- -title: Incorporate Slack-native AI agents -excerpt: Unify company knowledge with slack-native AI agents -products: [cloud] -keywords: [ai, vector, pgvector, TigerData vector, pgvectorizer] -tags: [ai, vector, pgvectorizer] ---- - -# Incorporate Slack-native AI agents - -import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-only.mdx"; - -$AGENTS_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your Slack -history, docs, GitHub repositories, Salesforce and so on. You use your $AGENTS_SHORT to get instant answers for real -business, technical, and operations questions in your Slack channels. - -![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png) - -$AGENTS_LONG can handle concurrent conversations with enterprise-grade reliability. They has the following features: - -- **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions -- **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load -- **Immediate event processing**: $AGENTS_LONG provide real-time responsiveness. Events are processed within milliseconds of arrival rather than waiting for polling cycles -- **Resilient retry logic**: automatic retry with visibility thresholds, plus stuck or expired event cleanup -- **Horizontal scalability**: run multiple $AGENTS_SHORT instances simultaneously with coordinated work distribution across all instances -- **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers -- **Extensible architecture**: zero code integration for basic agents. For more specialized use cases, easily customize your agent using [Jinja templates][jinja-templates] -- **Complete observability**: detailed tracing of event flow, worker activity, and database operations with full [Logfire][logfire] instrumentation - -This page shows you how to install the $AGENTS_CLI, connect to the $COMPANY MCP server, and customize prompts for -your specific needs. - -## Prerequisites - -* A [Tiger Cloud service][create-a-service] -* The [uv package manager][uv-install] -* An [Anthropic API key][claude-api-key] -* Optional: [Logfire token][logfire] - - - - -## Manual install - -IAIN: to update - -### Create a Slack app - -Before installing $AGENTS_LONG, you need to create a Slack app that the $AGENTS_SHORT will connect to. This app -provides the security tokens for Slack integration with your $AGENTS_SHORT: - - - -1. **Create a manifest for your Slack App** - - 1. In a temporary directory, download the $AGENTS_SHORT Slack manifest template: - - ```bash - curl -O https://raw.githubusercontent.com/timescale/tiger-agents-for-work/main/slack-manifest.json - ``` - - 1. Edit `slack-manifest.json` and customize your name and description of your Slack App. For example: - - ```json - "display_information": { - "name": "Tiger Agent", - "description": "Tiger AI Agent helps you easily access your business information, and tune your Tiger services", - "background_color": "#000000" - }, - "features": { - "bot_user": { - "display_name": "Tiger Agent", - "always_online": true - } - }, - ``` - - 1. Copy the contents of `slack-manifest.json` to the clipboard: - - ```shell - cat slack-manifest.json| pbcopy - ``` - -1. **Create the Slack app** - - 1. Go to [api.slack.com/apps](https://api.slack.com/apps). - 1. Click `Create New App`. - 1. Select `From a manifest`. - 1. Choose your workspace, then click `Next`. - 1. Paste the contents of `slack-manifest.json` and click `Next`. - 1. Click `Create`. -1. **Generate an app-level token** - - 1. In your app settings, go to `Basic Information`. - 1. Scroll to `App-Level Tokens`. - 1. Click `Generate Token and Scopes`. - 1. Add a `Token Name`, then click `Add Scope`, add `connections:write` then click `Generate`. - 1. Copy the `xapp-*` token locally and click `Done`. - -1. **Install your app to a Slack workspace** - - 1. In the sidebar, under `Settings`, click `Install App`. - 1. Click `Install to `, then click `Allow`. - 1. Copy the `xoxb-` Bot User OAuth Token locally. - - - -You have created a Slack app and obtained the necessary tokens for $AGENTS_SHORT integration. - - -### Install and configure your $AGENTS_SHORT instance - -$AGENTS_LONG are a production-ready library and CLI written in Python that you use to create Slack-native AI agents. -This section shows you how to configure a $AGENTS_SHORT to connect to your Slack app, and give them access to your -data and analytics stored in $CLOUD_LONG. - - - -1. **Create a project directory** - - ```bash - mkdir my-tiger-agent - cd my-tiger-agent - ``` - -1. **Create a $AGENTS_SHORT environment with your Slack, AI Assistant, and database configuration** - - 1. Download `.env.sample` to a local `.env` file: - ```shell - curl -L -o .env https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/.env.sample - ``` - 1. In `.env`, add your Slack tokens and Anthropic API key: - - ```bash - # Slack tokens (from the Slack app you created) - SLACK_APP_TOKEN=xapp-your-app-token - SLACK_BOT_TOKEN=xoxb-your-bot-token - - # Anthropic API key - ANTHROPIC_API_KEY=sk-ant-your-api-key - - # Optional: Logfire token for enhanced logging - LOGFIRE_TOKEN=your-logfire-token - ``` - 1. Add the [connection details][connection-info] for the $SERVICE_LONG you are using for this $AGENTS_SHORT: - ```bash - PGHOST= - PGDATABASE=tsdb - PGPORT= - PGUSER=tsdbadmin - PGPASSWORD= - ``` - 1. Save and close `.env`. - -1. **Add the default $AGENTS_SHORT prompts to your project** - ```bash - mkdir prompts - curl -L -o prompts/system_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/system_prompt.md - curl -L -o prompts/user_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/user_prompt.md - ``` - -1. **Install $AGENTS_LONG to manage and run your AI-powered Slack bots** - - 1. Install the $AGENTS_CLI using uv. - - ```bash - uv tool install --from git+https://github.com/timescale/tiger-agents-for-work.git tiger-agent - ``` - `tiger-agent` is installed in `~/.local/bin/tiger-agent`. If necessary, add this folder to your `PATH`. - - 1. Verify the installation. - - ```bash - tiger-agent --help - ``` - - You see the $AGENTS_CLI help output with the available commands and options. - - -1. **Connect your $AGENTS_SHORT with Slack** - - 1. Run your $AGENTS_SHORT: - ```bash - tiger-agent run --prompts prompts/ --env .env - ``` - If you open the explorer in [$CONSOLE][portal-ops-mode], you can see the tables used by your $AGENTS_SHORT. - - 1. In Slack, open a public channel app and ask $AGENTS_SHORT a couple of questions. You see the response in your - public channel and log messages in the Terminal. - - ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-terminal.png) - - - -### Add information from MCP servers to your $AGENTS_SHORT - -To increase the amount of specialized information your AI Assistant can use, you can add MCP servers supplying data -your users need. For example, to add the $COMPANY MCP server to your $AGENTS_SHORT: - - - -1. **Copy the example `mcp_config.json` to your project** - - In `my-tiger-agent`, run the following command: - - ```bash - curl -L -o mcp_config.json https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/examples/mcp_config.json - ``` - -1. **Configure your $AGENTS_SHORT to connect to the most useful MCP servers for your organization** - - For example, to add the $COMPANY documentation MCP server to your $AGENTS_SHORT, update the docs entry to the - following: - ```json - "docs": { - "tool_prefix": "docs", - "url": "https://mcp.tigerdata.com/docs", - "allow_sampling": false - }, - ``` - To avoid errors, delete all entries in `mcp_config.json` with invalid URLS. For example the `github` entry with `http://github-mcp-server/mcp`. - -1. **Restart your $AGENTS_SHORT** - ```bash - tiger-agent run --prompts prompts/ --mcp-config mcp_config.json - ``` - - - -You have configured your $AGENTS_SHORT to connect to the $MCP_SHORT. For more information, -see [MCP Server Configuration][mcp-configuration-docs]. - -### Customize prompts for personalization - -$AGENTS_LONG uses Jinja2 templates for dynamic, context-aware prompt generation. This system allows for sophisticated -prompts that adapt to conversation context, user preferences, and event metadata. $AGENTS_LONG uses the following -templates: - -- `system_prompt.md`: defines the AI Assistant's role, capabilities, and behavior patterns. This template sets the - foundation for the way your $AGENTS_SHORT will respond and interact. -- `user_prompt.md`: formats the user's request with relevant context, providing the AI Assistant with the - information necessary to generate an appropriate response. - -To change the way your $AGENTS_SHORTs interact with users in your Slack app: - - - -1. **Update the prompt** - - For example, in `prompts/system_prompt.md`, add another item in the `Response Protocol` section to fine tune - the behaviour of your $AGENTS_SHORTs. For example: - ```shell - 5. Be snarky but vaguely amusing - ``` - -1. **Test your configuration** - - Run $AGENTS_SHORT with your custom prompt: - - ```bash - tiger-agent run --mcp-config mcp_config.json --prompts prompts/ - ``` - - - -For more information, see [Prompt tempates][prompt-templates]. - -## Advanced configuration options - -For additional customization, you can modify the following $AGENTS_SHORT parameters: - -* `--model`: change AI model (default: `anthropic:claude-sonnet-4-20250514`) -* `--num-workers`: adjust concurrent workers (default: `5`) -* `--max-attempts`: set retry attempts per event (default: `3`) - -Example with custom settings: - -```bash -tiger-agent run \ - --model claude-3-5-sonnet-latest \ - --mcp-config mcp_config.json \ - --prompts prompts/ \ - --num-workers 10 \ - --max-attempts 5 -``` - -Your $AGENTS_SHORTs are now configured with $COMPANY MCP server access and personalized prompts. - - - - -[jinja-templates]: https://jinja.palletsprojects.com/en/stable/ -[logfire]: https://pydantic.dev/logfire -[claude-api-key]: https://console.anthropic.com/settings/keys -[create-a-service]: /getting-started/:currentVersion:/services -[uv-install]: https://docs.astral.sh/uv/getting-started/installation/ -[connection-info]: /integrations/:currentVersion:/find-connection-details/ -[portal-ops-mode]: https://console.cloud.timescale.com/dashboard/services -[mcp-configuration-docs]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/mcp_config.md -[prompt-templates]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/prompt_templates.md \ No newline at end of file diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md index 53919d9c03..7f46f3ab7b 100644 --- a/ai/tiger-agents-for-work.md +++ b/ai/tiger-agents-for-work.md @@ -1,142 +1,284 @@ --- -title: Incorporate Slack-native AI agents +title: Integrate a slack-native AI agent excerpt: Unify company knowledge with slack-native AI agents -products: [cloud, self_hosted] +products: [cloud] keywords: [ai, vector, pgvector, TigerData vector, pgvectorizer] tags: [ai, vector, pgvectorizer] --- -import ImportPrerequisites from "versionContent/_partials/_prereqs-cloud-and-self.mdx"; +# Integrate a slack-native AI agent -# Incorporate Slack-native AI agents +import PrereqAccount from "versionContent/_partials/_prereqs-cloud-project-and-self.mdx"; -$EON_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your Slack -history, docs, GitHub repositories, Salesforce and so on. You use $EON_SHORT to get instant answers for real -business, technical, and operations questions in your Slack channels. +$AGENTS_LONG is a Slack-native AI agent that you use to unify the knowledge in your company. This includes your Slack +history, docs, GitHub repositories, Salesforce and so on. You use your $AGENTS_SHORT to get instant answers for real +business, technical, and operations questions in your Slack channels. ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png) -$EON_LONG can handle concurrent conversations with enterprise-grade reliability. It has the following features: +$AGENTS_LONG can handle concurrent conversations with enterprise-grade reliability. They has the following features: - **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions - **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load -- **Immediate event processing**: $EON_LONG provide real-time responsiveness. Events are processed within milliseconds of arrival rather than waiting for polling cycles +- **Immediate event processing**: $AGENTS_LONG provide real-time responsiveness. Events are processed within milliseconds of arrival rather than waiting for polling cycles - **Resilient retry logic**: automatic retry with visibility thresholds, plus stuck or expired event cleanup -- **Horizontal scalability**: run multiple $EON_SHORT instances simultaneously with coordinated work distribution across all instances -- **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers -- **Extensible architecture**: zero code integration for basic agents. For more specialized use cases, easily customize your agent using [Jinja templates][jinja-templates] -- **Complete observability**: detailed tracing of event flow, worker activity, and database operations with full [Logfire][logfire] instrumentation +- **Horizontal scalability**: run multiple $AGENTS_SHORT instances simultaneously with coordinated work distribution across all instances +- **AI-Powered Responses**: use the AI model of your choice, you can also integrate with MCP servers +- **Extensible architecture**: zero code integration for basic agents. For more specialized use cases, easily customize your agent using [Jinja templates][jinja-templates] +- **Complete observability**: detailed tracing of event flow, worker activity, and database operations with full [Logfire][logfire] instrumentation This page shows you how to install the $AGENTS_CLI, connect to the $COMPANY MCP server, and customize prompts for your specific needs. ## Prerequisites - + +* The [uv package manager][uv-install] +* An [Anthropic API key][claude-api-key] +* Optional: [Logfire token][logfire] -- [Install Docker][install-docker] on your developer device +## Create a Slack app -* IAIN, let's see. An [Anthropic API key][claude-api-key] -* Optional: [Logfire token][logfire] +Before installing $AGENTS_LONG, you need to create a Slack app that the $AGENTS_SHORT will connect to. This app +provides the security tokens for Slack integration with your $AGENTS_SHORT: + + + +1. **Create a manifest for your Slack App** + + 1. In a temporary directory, download the $AGENTS_SHORT Slack manifest template: + + ```bash + curl -O https://raw.githubusercontent.com/timescale/tiger-agents-for-work/main/slack-manifest.json + ``` + + 1. Edit `slack-manifest.json` and customize your name and description of your Slack App. For example: + + ```json + "display_information": { + "name": "Tiger Agent", + "description": "Tiger AI Agent helps you easily access your business information, and tune your Tiger services", + "background_color": "#000000" + }, + "features": { + "bot_user": { + "display_name": "Tiger Agent", + "always_online": true + } + }, + ``` + + 1. Copy the contents of `slack-manifest.json` to the clipboard: + + ```shell + cat slack-manifest.json| pbcopy + ``` + +1. **Create the Slack app** + 1. Go to [api.slack.com/apps](https://api.slack.com/apps). + 1. Click `Create New App`. + 1. Select `From a manifest`. + 1. Choose your workspace, then click `Next`. + 1. Paste the contents of `slack-manifest.json` and click `Next`. + 1. Click `Create`. +1. **Generate an app-level token** -## Interactive setup + 1. In your app settings, go to `Basic Information`. + 1. Scroll to `App-Level Tokens`. + 1. Click `Generate Token and Scopes`. + 1. Add a `Token Name`, then click `Add Scope`, add `connections:write` then click `Generate`. + 1. Copy the `xapp-*` token locally and click `Done`. -$EON_LONG is a production-ready repository running [$CLI_LONG][tiger-cli] and [$AGENTS_LONG][tiger-agents] that creates -and runs the following components for you: +1. **Install your app to a Slack workspace** -- An ingest Slack app that receive all messages and reactions from the public channels in your Slack workspace -- A listener Slack App for the agent that receive @mentions to it -- A $SERVICE_LONG instance that stores data from the Slack apps + 1. In the sidebar, under `Settings`, click `Install App`. + 1. Click `Install to `, then click `Allow`. + 1. Copy the `xoxb-` Bot User OAuth Token locally. -If [$CLI_LONG][tiger-cli] and [$AGENTS_LONG][tiger-agents] are installed locally, $EON_LONG calls the local apps. If not, -$EON_LONG runs them in Docker. + -This section shows you how to configure $EON_SHORT to connect to your Slack app, and give them access to your +You have created a Slack app and obtained the necessary tokens for $AGENTS_SHORT integration. + + +## Install and configure your $AGENTS_SHORT instance + +$AGENTS_LONG are a production-ready library and CLI written in Python that you use to create Slack-native AI agents. +This section shows you how to configure a $AGENTS_SHORT to connect to your Slack app, and give them access to your data and analytics stored in $CLOUD_LONG. -1. **Install $EON_LONG to manage and run your AI-powered Slack bots** +1. **Create a project directory** - In a local folder, run the following command from the terminal. - ```shell - git clone git@github.com:timescale/tiger-eon.git - ``` + ```bash + mkdir my-tiger-agent + cd my-tiger-agent + ``` -1. **Configure $EON_SHORT** +1. **Create a $AGENTS_SHORT environment with your Slack, AI Assistant, and database configuration** - The interactive setup creates and configures the Slack apps and the $SERVICE_LONG for $EON_SHORT to run correctly: - -1. **Start the interactive setup** + 1. Download `.env.sample` to a local `.env` file: + ```shell + curl -L -o .env https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/.env.sample + ``` + 1. In `.env`, add your Slack tokens and Anthropic API key: + + ```bash + # Slack tokens (from the Slack app you created) + SLACK_APP_TOKEN=xapp-your-app-token + SLACK_BOT_TOKEN=xoxb-your-bot-token + + # Anthropic API key + ANTHROPIC_API_KEY=sk-ant-your-api-key + + # Optional: Logfire token for enhanced logging + LOGFIRE_TOKEN=your-logfire-token + ``` + 1. Add the [connection details][connection-info] for the $SERVICE_LONG you are using for this $AGENTS_SHORT: + ```bash + PGHOST= + PGDATABASE=tsdb + PGPORT= + PGUSER=tsdbadmin + PGPASSWORD= + ``` + 1. Save and close `.env`. + +1. **Add the default $AGENTS_SHORT prompts to your project** + ```bash + mkdir prompts + curl -L -o prompts/system_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/system_prompt.md + curl -L -o prompts/user_prompt.md https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/prompts/user_prompt.md + ``` + +1. **Install $AGENTS_LONG to manage and run your AI-powered Slack bots** + + 1. Install the $AGENTS_CLI using uv. + + ```bash + uv tool install --from git+https://github.com/timescale/tiger-agents-for-work.git tiger-agent + ``` + `tiger-agent` is installed in `~/.local/bin/tiger-agent`. If necessary, add this folder to your `PATH`. + + 1. Verify the installation. + + ```bash + tiger-agent --help + ``` + + You see the $AGENTS_CLI help output with the available commands and options. + + +1. **Connect your $AGENTS_SHORT with Slack** + + 1. Run your $AGENTS_SHORT: + ```bash + tiger-agent run --prompts prompts/ --env .env + ``` + If you open the explorer in [$CONSOLE][portal-ops-mode], you can see the tables used by your $AGENTS_SHORT. + + 1. In Slack, open a public channel app and ask $AGENTS_SHORT a couple of questions. You see the response in your + public channel and log messages in the Terminal. - ```shell - cd tiger-eon - ./setup-tiger-eon.sh + ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-terminal.png) + + + +## Add information from MCP servers to your $AGENTS_SHORT + +To increase the amount of specialized information your AI Assistant can use, you can add MCP servers supplying data +your users need. For example, to add the $COMPANY MCP server to your $AGENTS_SHORT: + + + +1. **Copy the example `mcp_config.json` to your project** + + In `my-tiger-agent`, run the following command: + + ```bash + curl -L -o mcp_config.json https://raw.githubusercontent.com/timescale/tiger-agent/refs/heads/main/examples/mcp_config.json + ``` + +1. **Configure your $AGENTS_SHORT to connect to the most useful MCP servers for your organization** + + For example, to add the $COMPANY documentation MCP server to your $AGENTS_SHORT, update the docs entry to the + following: + ```json + "docs": { + "tool_prefix": "docs", + "url": "https://mcp.tigerdata.com/docs", + "allow_sampling": false + }, + ``` + To avoid errors, delete all entries in `mcp_config.json` with invalid URLS. For example the `github` entry with `http://github-mcp-server/mcp`. + +1. **Restart your $AGENTS_SHORT** + ```bash + tiger-agent run --prompts prompts/ --mcp-config mcp_config.json ``` - You see a resume of the setup procedure. Type `y` and press `Enter`. - -1. **Create the $SERVICE_LONG to use with $EON_SHORT** - - You see `Do you want to use a free tier Tiger Cloud Database? [y/N]:`. Press `Y` to create a free - $SERVICE_LONG. - $EON_SHORT opens the $CLOUD_LONG authentication page in your browser. Click `Authorize`. $EON_SHORT creates a - $SERVICE_LONG called [tiger-eon][services-portal] and stores the credentials in your local keychain. + - If you press `N`, the interactive setup creates and runs $TIMESCALE_DB in a local Docker container. +You have configured your $AGENTS_SHORT to connect to the $MCP_SHORT. For more information, +see [MCP Server Configuration][mcp-configuration-docs]. -1. **Create the ingest Slack app** +## Customize prompts for personalization - 1. In terminal, name your ingest Slack app: +$AGENTS_LONG uses Jinja2 templates for dynamic, context-aware prompt generation. This system allows for sophisticated +prompts that adapt to conversation context, user preferences, and event metadata. $AGENTS_LONG uses the following +templates: - 1. $EON_SHORT proposes to create an ingest app called `tiger-slack-ingest`, press `Enter`. - 1. Do the same for the App description. +- `system_prompt.md`: defines the AI Assistant's role, capabilities, and behavior patterns. This template sets the + foundation for the way your $AGENTS_SHORT will respond and interact. +- `user_prompt.md`: formats the user's request with relevant context, providing the AI Assistant with the + information necessary to generate an appropriate response. - $EON_SHORT opens `Your Apps` in `api.slack.com`. - - 1. Start configuring your ingest app in Slack: - In the Slack `Your Apps` page: - 1. Click `Create New App`, click `From an manifest`, then select a workspace. - 1. Click `Next`. Slack opens `Create app from manifest`. - - 1. Add the Slack app manifest: - 1. In terminal press `Enter`. The setup prints the Slack app manifest to terminal. - 1. In the Slack `Create app from manifest` window, paste the manifest, - 1. Click `Next`, then click `Create`. +To change the way your $AGENTS_SHORTs interact with users in your Slack app: + + + +1. **Update the prompt** + + For example, in `prompts/system_prompt.md`, add another item in the `Response Protocol` section to fine tune + the behaviour of your $AGENTS_SHORTs. For example: + ```shell + 5. Be snarky but vaguely amusing + ``` + +1. **Test your configuration** + + Run $AGENTS_SHORT with your custom prompt: + + ```bash + tiger-agent run --mcp-config mcp_config.json --prompts prompts/ + ``` - 1. Configure an app-level token + - 1. In your app settings, go to `Basic Information`. - 1. Scroll to `App-Level Tokens`. - 1. Click `Generate Token and Scopes`. - 1. Add a `Token Name`, then click `Add Scope`, add `connections:write` then click `Generate`. - 1. Copy the `xapp-*` token and click `Done`. - 1. In terminal, paste the token, then press `Enter`. +For more information, see [Prompt tempates][prompt-templates]. - 1. Configure a bot user OAuth token: +## Advanced configuration options - 1. In your app settings, under `Features`, click `App Home`. - 1. Scroll down, then enable `Allow users to send Slash commands and messages from the messages tab`. - 1. In your app settings, under `Settings`, click `Install App`. - 1. Click `Install to `, then click `Allow`. - 1. Copy the `xoxb-` Bot User OAuth Token locally. - 1. In terminal, paste the token, then press `Enter`. +For additional customization, you can modify the following $AGENTS_SHORT parameters: -1. **Create the $AGENT_SHORT Slack app** +* `--model`: change AI model (default: `anthropic:claude-sonnet-4-20250514`) +* `--num-workers`: adjust concurrent workers (default: `5`) +* `--max-attempts`: set retry attempts per event (default: `3`) - Follow the same procedure as you did for the ingest Slack app. +Example with custom settings: -1. **Add your Anthropic API key** +```bash +tiger-agent run \ + --model claude-3-5-sonnet-latest \ + --mcp-config mcp_config.json \ + --prompts prompts/ \ + --num-workers 10 \ + --max-attempts 5 +``` - The interactive setup opens https://console.anthropic.com/settings/keys. Create a Claude Code key, then - paste it in the terminal. +Your $AGENTS_SHORTs are now configured with $COMPANY MCP server access and personalized prompts. -1. **Add your Logfire token** - - If you would like to integrate logfire with $EON_SHORT, paste your token and press `Enter`. If not, press `Enter`. - - @@ -148,8 +290,4 @@ data and analytics stored in $CLOUD_LONG. [connection-info]: /integrations/:currentVersion:/find-connection-details/ [portal-ops-mode]: https://console.cloud.timescale.com/dashboard/services [mcp-configuration-docs]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/mcp_config.md -[prompt-templates]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/prompt_templates.md -[install-docker]: https://docs.docker.com/engine/install/ -[tiger-cli]: https://github.com/timescale/tiger-cli/ -[tiger-agents]: https://github.com/timescale/tiger-agents-for-work -[services-portal]: https://console.cloud.timescale.com/dashboard/services \ No newline at end of file +[prompt-templates]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/prompt_templates.md \ No newline at end of file diff --git a/ai/tiger-eon.md b/ai/tiger-eon.md new file mode 100644 index 0000000000..d9794cc66f --- /dev/null +++ b/ai/tiger-eon.md @@ -0,0 +1,182 @@ +--- +title: Aggregate organizational data with AI agents +excerpt: Unify company knowledge with slack-native AI agents +products: [cloud, self_hosted] +keywords: [ai, vector, pgvector, TigerData vector, pgvectorizer] +tags: [ai, vector, pgvectorizer] +--- + +import PrereqAccount from "versionContent/_partials/_prereqs-cloud-project-and-self.mdx"; + +# Aggregate organizational data with AI agents + +Your business already has the answers in Slack threads, GitHub pull requests, Linear tasks, your own docs, Salesforce +service tickets, anywhere you store data. However, those answers are scattered, hard to find, and often forgotten. +$EON_LONG automatically integrates $AGENTS_LONG with your organizational data so you can let AI assistants analyse your +company data and give you the answers you need. For example: +- What did we ship last week? +- What's blocking the release? +- Summarize the latest GitHub pull requests. + +Eon responds instantly, pulling from the tools you already use. No new UI, no new workflow — just answers in Slack. + +![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png) + +$EON_LONG: + +- **Unlocks hidden value**: your data in Slack, GitHub, and Linear already contain the insights you need. $EON_SHORT makes them accessible. +- **Enables faster decisions**: no need to search or ask around, you get answers in seconds. +- **Is easy to use**: $EON_SHORT runs a $AGENTS_SHORT and MCP servers statelessly in a lightweight Docker container. +- **Integrates seamless with $CLOUD_LONG**: $EON_SHORT creates a free $SERVICE_LONG so you securely and reliably store + your company data. Prefer to self-host? Use a [$PG instance with $TIMESCALE_DB][install-self-hosted]. + +This page shows you how to install and run $EON_SHORT. + +## Prerequisites + + + +- [Install Docker][install-docker] on your developer device +- Rights to create an [Anthropic API key][claude-api-key] +- Rights to create a [GitHub token][github-token] + +## Interactive setup + +$EON_LONG is a production-ready repository running [$CLI_LONG][tiger-cli] and [$AGENTS_LONG][tiger-agents] that creates +and runs the following components for you: + +- An ingest Slack app that consumes all messages and reactions from public channels in your Slack workspace +- A [$AGENTS_SHORT][tiger-agents] that analyse your company data for you +- A $SERVICE_LONG instance that stores data from the Slack apps +- MCP servers that connect data sources to $EON_SHORT +- A listener Slack app that passes questions to the $AGENTS_SHORT when you @tag it in a public channel, and returns the + AI analysis on your data + +All local components are run in a lightweight Docker container. + +This section shows you how to run the interactive setup to configure $EON_SHORT to connect to your Slack app, and give them access to your +data and analytics stored in $CLOUD_LONG. + + + +1. **Install $EON_LONG to manage and run your AI-powered Slack bots** + + In a local folder, run the following command from the terminal. + ```shell + git clone git@github.com:timescale/tiger-eon.git + ``` + +1. **Configure $EON_SHORT** + + The interactive setup creates and configures the Slack apps and the $SERVICE_LONG for $EON_SHORT to run correctly: + +1. **Start the interactive setup** + + ```shell + cd tiger-eon + ./setup-tiger-eon.sh + ``` + You see a resume of the setup procedure. Type `y` and press `Enter`. + +1. **Create the $SERVICE_LONG to use with $EON_SHORT** + + You see `Do you want to use a free tier Tiger Cloud Database? [y/N]:`. Press `Y` to create a free + $SERVICE_LONG. + + $EON_SHORT opens the $CLOUD_LONG authentication page in your browser. Click `Authorize`. $EON_SHORT creates a + $SERVICE_LONG called [tiger-eon][services-portal] and stores the credentials in your local keychain. + + If you press `N`, the interactive setup creates and runs $TIMESCALE_DB in a local Docker container. + +1. **Create the ingest Slack app** + + 1. In terminal, name your ingest Slack app: + + 1. $EON_SHORT proposes to create an ingest app called `tiger-slack-ingest`, press `Enter`. + 1. Do the same for the App description. + + $EON_SHORT opens `Your Apps` in `api.slack.com`. + + 1. Start configuring your ingest app in Slack: + In the Slack `Your Apps` page: + 1. Click `Create New App`, click `From an manifest`, then select a workspace. + 1. Click `Next`. Slack opens `Create app from manifest`. + + 1. Add the Slack app manifest: + 1. In terminal press `Enter`. The setup prints the Slack app manifest to terminal. + 1. In the Slack `Create app from manifest` window, paste the manifest, + 1. Click `Next`, then click `Create`. + + 1. Configure an app-level token + + 1. In your app settings, go to `Basic Information`. + 1. Scroll to `App-Level Tokens`. + 1. Click `Generate Token and Scopes`. + 1. Add a `Token Name`, then click `Add Scope`, add `connections:write` then click `Generate`. + 1. Copy the `xapp-*` token and click `Done`. + 1. In terminal, paste the token, then press `Enter`. + + 1. Configure a bot user OAuth token: + + 1. In your app settings, under `Features`, click `App Home`. + 1. Scroll down, then enable `Allow users to send Slash commands and messages from the messages tab`. + 1. In your app settings, under `Settings`, click `Install App`. + 1. Click `Install to `, then click `Allow`. + 1. Copy the `xoxb-` Bot User OAuth Token locally. + 1. In terminal, paste the token, then press `Enter`. + +1. **Create the $AGENT_SHORT Slack app** + + Follow the same procedure as you did for the ingest Slack app. + +1. **Integrate $EON_SHORT with Anthropic** + + The interactive setup opens https://console.anthropic.com/settings/keys. Create a Claude Code key, then + paste it in the terminal. + +1. **Integrate $EON_SHORT with Logfire** + + If you would like to integrate logfire with $EON_SHORT, paste your token and press `Enter`. If not, press `Enter`. + +1. **Integrate $EON_SHORT with Github** + + The interactive setup asks if you would like to `Enable github MCP server?". For $EON_SHORT to answer questions + about the activity in your Github organization, press `y`. + + + +## Run $EON_SHORT + + +## Manual configuration + +$EON_LONG is a production-ready repository running [$CLI_LONG][tiger-cli] and [$AGENTS_LONG][tiger-agents] that creates +and runs the following components for you: + +- An ingest Slack app that consumes all messages and reactions from public channels in your Slack workspace +- A [$AGENTS_SHORT][tiger-agents] that analyse your company data for you +- A $SERVICE_LONG instance that stores data from the Slack apps +- MCP servers that connect data sources to $EON_SHORT +- A listener Slack app that passes questions to the $AGENTS_SHORT when you @tag it in a public channel, and returns the + AI analysis on your data + +All local components are run in a lightweight Docker container. + +This section shows you how to manually configure $EON_SHORT and . + + +[jinja-templates]: https://jinja.palletsprojects.com/en/stable/ +[logfire]: https://pydantic.dev/logfire +[claude-api-key]: https://console.anthropic.com/settings/keys +[github-token]: https://github.com/settings/tokens/new?description=Tiger%20Agent&scopes=repo,read:org +[create-a-service]: /getting-started/:currentVersion:/services +[uv-install]: https://docs.astral.sh/uv/getting-started/installation/ +[connection-info]: /integrations/:currentVersion:/find-connection-details/ +[portal-ops-mode]: https://console.cloud.timescale.com/dashboard/services +[mcp-configuration-docs]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/mcp_config.md +[prompt-templates]: https://github.com/timescale/tiger-agents-for-work/blob/main/docs/prompt_templates.md +[install-docker]: https://docs.docker.com/engine/install/ +[tiger-cli]: https://github.com/timescale/tiger-cli/ +[tiger-agents]: https://github.com/timescale/tiger-agents-for-work +[services-portal]: https://console.cloud.timescale.com/dashboard/services +[install-self-hosted]: /self-hosted/:currentVersion:/install/ \ No newline at end of file From 0a020b77d78cfd81345d5edf4590840ecca96100 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Mon, 20 Oct 2025 15:11:20 +0200 Subject: [PATCH 10/15] chore: update the procedure. --- ai/tiger-eon.md | 61 +++++++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 27 deletions(-) diff --git a/ai/tiger-eon.md b/ai/tiger-eon.md index d9794cc66f..514b9b9258 100644 --- a/ai/tiger-eon.md +++ b/ai/tiger-eon.md @@ -18,9 +18,9 @@ company data and give you the answers you need. For example: - What's blocking the release? - Summarize the latest GitHub pull requests. -Eon responds instantly, pulling from the tools you already use. No new UI, no new workflow — just answers in Slack. +$EON_SHORT responds instantly, pulling from the tools you already use. No new UI, no new workflow — just answers in Slack. -![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png) +![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-eon-big-question.png) $EON_LONG: @@ -54,7 +54,7 @@ and runs the following components for you: All local components are run in a lightweight Docker container. -This section shows you how to run the interactive setup to configure $EON_SHORT to connect to your Slack app, and give them access to your +This section shows you how to run the $EON_SHORT setup to configure $EON_SHORT to connect to your Slack app, and give them access to your data and analytics stored in $CLOUD_LONG. @@ -68,9 +68,9 @@ data and analytics stored in $CLOUD_LONG. 1. **Configure $EON_SHORT** - The interactive setup creates and configures the Slack apps and the $SERVICE_LONG for $EON_SHORT to run correctly: + The $EON_SHORT setup creates and configures the Slack apps and the $SERVICE_LONG for $EON_SHORT to run correctly: -1. **Start the interactive setup** +1. **Start the $EON_SHORT setup** ```shell cd tiger-eon @@ -86,7 +86,7 @@ data and analytics stored in $CLOUD_LONG. $EON_SHORT opens the $CLOUD_LONG authentication page in your browser. Click `Authorize`. $EON_SHORT creates a $SERVICE_LONG called [tiger-eon][services-portal] and stores the credentials in your local keychain. - If you press `N`, the interactive setup creates and runs $TIMESCALE_DB in a local Docker container. + If you press `N`, the $EON_SHORT setup creates and runs $TIMESCALE_DB in a local Docker container. 1. **Create the ingest Slack app** @@ -95,7 +95,7 @@ data and analytics stored in $CLOUD_LONG. 1. $EON_SHORT proposes to create an ingest app called `tiger-slack-ingest`, press `Enter`. 1. Do the same for the App description. - $EON_SHORT opens `Your Apps` in `api.slack.com`. + $EON_SHORT opens `Your Apps` in https://api.slack.com/apps/. 1. Start configuring your ingest app in Slack: In the Slack `Your Apps` page: @@ -103,7 +103,7 @@ data and analytics stored in $CLOUD_LONG. 1. Click `Next`. Slack opens `Create app from manifest`. 1. Add the Slack app manifest: - 1. In terminal press `Enter`. The setup prints the Slack app manifest to terminal. + 1. In terminal press `Enter`. The setup prints the Slack app manifest to terminal and adds it to your clipboard. 1. In the Slack `Create app from manifest` window, paste the manifest, 1. Click `Next`, then click `Create`. @@ -112,7 +112,7 @@ data and analytics stored in $CLOUD_LONG. 1. In your app settings, go to `Basic Information`. 1. Scroll to `App-Level Tokens`. 1. Click `Generate Token and Scopes`. - 1. Add a `Token Name`, then click `Add Scope`, add `connections:write` then click `Generate`. + 1. Add a `Token Name`, then click `Add Scope` add `connections:write` then click `Generate`. 1. Copy the `xapp-*` token and click `Done`. 1. In terminal, paste the token, then press `Enter`. @@ -125,44 +125,51 @@ data and analytics stored in $CLOUD_LONG. 1. Copy the `xoxb-` Bot User OAuth Token locally. 1. In terminal, paste the token, then press `Enter`. -1. **Create the $AGENT_SHORT Slack app** +1. **Create the $EON_SHORT Slack app** Follow the same procedure as you did for the ingest Slack app. 1. **Integrate $EON_SHORT with Anthropic** - The interactive setup opens https://console.anthropic.com/settings/keys. Create a Claude Code key, then + The $EON_SHORT setup opens https://console.anthropic.com/settings/keys. Create a Claude Code key, then paste it in the terminal. 1. **Integrate $EON_SHORT with Logfire** If you would like to integrate logfire with $EON_SHORT, paste your token and press `Enter`. If not, press `Enter`. -1. **Integrate $EON_SHORT with Github** +1. **Integrate $EON_SHORT with GitHub** - The interactive setup asks if you would like to `Enable github MCP server?". For $EON_SHORT to answer questions - about the activity in your Github organization, press `y`. + The $EON_SHORT setup asks if you would like to `Enable github MCP server?". For $EON_SHORT to answer questions + about the activity in your Github organization`. Press `y` to integrate with GitHub. - +1. **Integrate $EON_SHORT with Linear** -## Run $EON_SHORT + The $EON_SHORT setup asks if you would like to `Enable linear MCP server? [y/N]:`. Press `y` to integrate with Linear. +1. **Give $EON_SHORT access to private repositories** + + 1. The setup asks if you would like to `include access to private repositories`. Press `y`. + 1. Follow the GitHub token creation process. + 1. In the $EON_SHORT setup add your organization name, then past the GitHub token. -## Manual configuration + The setup sets up a new $SERVICE_LONG for you called `tiger-eon` then starts $EON_SHORT in Docker. -$EON_LONG is a production-ready repository running [$CLI_LONG][tiger-cli] and [$AGENTS_LONG][tiger-agents] that creates -and runs the following components for you: + ![Eon running in Docker](https://assets.timescale.com/docs/images/tiger-eon-docker-services.png) + + -- An ingest Slack app that consumes all messages and reactions from public channels in your Slack workspace -- A [$AGENTS_SHORT][tiger-agents] that analyse your company data for you -- A $SERVICE_LONG instance that stores data from the Slack apps -- MCP servers that connect data sources to $EON_SHORT -- A listener Slack app that passes questions to the $AGENTS_SHORT when you @tag it in a public channel, and returns the - AI analysis on your data +You have created: +* The $EON_SHORT ingest and chat apps in Slack +* A private MCP server connecting $EON_SHORT to your data in GitHub +* A $SERVICE_LONG that securely stores the data used by $EON_SHORT -All local components are run in a lightweight Docker container. +## Integrate $EON_SHORT in your Slack workspace + +To enable your AI assistant to analyse your data for you when you ask a question, open a public channel, +invite `@eon` to join, then ask a question: -This section shows you how to manually configure $EON_SHORT and . +![Eon running in Docker](https://assets.timescale.com/docs/images/tiger-eon-slack-channel-add.png) [jinja-templates]: https://jinja.palletsprojects.com/en/stable/ From 14e568bc451f51476b24145e145880dffffbe785 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Mon, 20 Oct 2025 15:51:55 +0200 Subject: [PATCH 11/15] chore: space. --- ai/tiger-agents-for-work.md | 1 + 1 file changed, 1 insertion(+) diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md index 7f46f3ab7b..830a807fd8 100644 --- a/ai/tiger-agents-for-work.md +++ b/ai/tiger-agents-for-work.md @@ -33,6 +33,7 @@ your specific needs. ## Prerequisites + * The [uv package manager][uv-install] * An [Anthropic API key][claude-api-key] * Optional: [Logfire token][logfire] From b8c3714947f67401a5c0eed717972c152ec2ca98 Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Mon, 20 Oct 2025 16:27:35 +0200 Subject: [PATCH 12/15] Apply suggestions from code review Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> Signed-off-by: Iain Cox --- ai/tiger-agents-for-work.md | 2 +- ai/tiger-eon.md | 24 ++++++++++++------------ 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/ai/tiger-agents-for-work.md b/ai/tiger-agents-for-work.md index 830a807fd8..6b3a7910aa 100644 --- a/ai/tiger-agents-for-work.md +++ b/ai/tiger-agents-for-work.md @@ -16,7 +16,7 @@ business, technical, and operations questions in your Slack channels. ![Query Tiger Agent](https://assets.timescale.com/docs/images/tiger-agent/query-in-slack.png) -$AGENTS_LONG can handle concurrent conversations with enterprise-grade reliability. They has the following features: +$AGENTS_LONG can handle concurrent conversations with enterprise-grade reliability. They have the following features: - **Durable and atomic event handling**: $PG-backed event claiming ensures exactly-once processing, even under high concurrency and failure conditions - **Bounded concurrency**: fixed worker pools prevent resource exhaustion while maintaining predictable performance under load diff --git a/ai/tiger-eon.md b/ai/tiger-eon.md index 514b9b9258..a7a8b15e6c 100644 --- a/ai/tiger-eon.md +++ b/ai/tiger-eon.md @@ -27,7 +27,7 @@ $EON_LONG: - **Unlocks hidden value**: your data in Slack, GitHub, and Linear already contain the insights you need. $EON_SHORT makes them accessible. - **Enables faster decisions**: no need to search or ask around, you get answers in seconds. - **Is easy to use**: $EON_SHORT runs a $AGENTS_SHORT and MCP servers statelessly in a lightweight Docker container. -- **Integrates seamless with $CLOUD_LONG**: $EON_SHORT creates a free $SERVICE_LONG so you securely and reliably store +- **Integrates seamlessly with $CLOUD_LONG**: $EON_SHORT creates a free $SERVICE_LONG so you securely and reliably store your company data. Prefer to self-host? Use a [$PG instance with $TIMESCALE_DB][install-self-hosted]. This page shows you how to install and run $EON_SHORT. @@ -37,8 +37,8 @@ This page shows you how to install and run $EON_SHORT. - [Install Docker][install-docker] on your developer device -- Rights to create an [Anthropic API key][claude-api-key] -- Rights to create a [GitHub token][github-token] +- Have rights to create an [Anthropic API key][claude-api-key] +- Have rights to create a [GitHub token][github-token] ## Interactive setup @@ -46,7 +46,7 @@ $EON_LONG is a production-ready repository running [$CLI_LONG][tiger-cli] and [$ and runs the following components for you: - An ingest Slack app that consumes all messages and reactions from public channels in your Slack workspace -- A [$AGENTS_SHORT][tiger-agents] that analyse your company data for you +- A [$AGENTS_SHORT][tiger-agents] that analyzes your company data for you - A $SERVICE_LONG instance that stores data from the Slack apps - MCP servers that connect data sources to $EON_SHORT - A listener Slack app that passes questions to the $AGENTS_SHORT when you @tag it in a public channel, and returns the @@ -61,7 +61,7 @@ data and analytics stored in $CLOUD_LONG. 1. **Install $EON_LONG to manage and run your AI-powered Slack bots** - In a local folder, run the following command from the terminal. + In a local folder, run the following command from the terminal: ```shell git clone git@github.com:timescale/tiger-eon.git ``` @@ -90,7 +90,7 @@ data and analytics stored in $CLOUD_LONG. 1. **Create the ingest Slack app** - 1. In terminal, name your ingest Slack app: + 1. In the terminal, name your ingest Slack app: 1. $EON_SHORT proposes to create an ingest app called `tiger-slack-ingest`, press `Enter`. 1. Do the same for the App description. @@ -104,7 +104,7 @@ data and analytics stored in $CLOUD_LONG. 1. Add the Slack app manifest: 1. In terminal press `Enter`. The setup prints the Slack app manifest to terminal and adds it to your clipboard. - 1. In the Slack `Create app from manifest` window, paste the manifest, + 1. In the Slack `Create app from manifest` window, paste the manifest. 1. Click `Next`, then click `Create`. 1. Configure an app-level token @@ -112,7 +112,7 @@ data and analytics stored in $CLOUD_LONG. 1. In your app settings, go to `Basic Information`. 1. Scroll to `App-Level Tokens`. 1. Click `Generate Token and Scopes`. - 1. Add a `Token Name`, then click `Add Scope` add `connections:write` then click `Generate`. + 1. Add a `Token Name`, then click `Add Scope` add `connections:write`, then click `Generate`. 1. Copy the `xapp-*` token and click `Done`. 1. In terminal, paste the token, then press `Enter`. @@ -149,11 +149,11 @@ data and analytics stored in $CLOUD_LONG. 1. **Give $EON_SHORT access to private repositories** - 1. The setup asks if you would like to `include access to private repositories`. Press `y`. + 1. The setup asks if you would like to include access to private repositories. Press `y`. 1. Follow the GitHub token creation process. - 1. In the $EON_SHORT setup add your organization name, then past the GitHub token. + 1. In the $EON_SHORT setup add your organization name, then paste the GitHub token. - The setup sets up a new $SERVICE_LONG for you called `tiger-eon` then starts $EON_SHORT in Docker. + The setup sets up a new $SERVICE_LONG for you called `tiger-eon`, then starts $EON_SHORT in Docker. ![Eon running in Docker](https://assets.timescale.com/docs/images/tiger-eon-docker-services.png) @@ -166,7 +166,7 @@ You have created: ## Integrate $EON_SHORT in your Slack workspace -To enable your AI assistant to analyse your data for you when you ask a question, open a public channel, +To enable your AI Assistant to analyze your data for you when you ask a question, open a public channel, invite `@eon` to join, then ask a question: ![Eon running in Docker](https://assets.timescale.com/docs/images/tiger-eon-slack-channel-add.png) From f6ebeab293117d3a17f2f016b3915bbbaf481fe2 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Mon, 20 Oct 2025 17:01:16 +0200 Subject: [PATCH 13/15] chore: add something about persistent memory. --- ai/tiger-eon.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/ai/tiger-eon.md b/ai/tiger-eon.md index a7a8b15e6c..d572e9e0fa 100644 --- a/ai/tiger-eon.md +++ b/ai/tiger-eon.md @@ -30,6 +30,20 @@ $EON_LONG: - **Integrates seamlessly with $CLOUD_LONG**: $EON_SHORT creates a free $SERVICE_LONG so you securely and reliably store your company data. Prefer to self-host? Use a [$PG instance with $TIMESCALE_DB][install-self-hosted]. +$EON_LONGs real-time ingestion system connects to Slack and captures everything: every message, reaction, edit, and +channel update. It can also process historical Slack exports. $EON_SHORT had instant access to years +of institutional knowledge from the very beginning. + +All of this data is stored in your $SERVICE_LONG as time-series data: conversations are events unfolding over time, +and $CLOUD_LONG is purpose-built for precisely this. Your data is optimized by + +- Automatically partitioning the data into 7-day chunks for efficient queries +- Compressing the data after 45 days to save space +- Segmenting by channel for faster retrieval + +When someone asks $EON_SHORT a question, it uses simple SQL to instantly retrieve the full thread context, related +conversations, and historical decisions. No rate limits. No API quotas. Just direct access to your data. + This page shows you how to install and run $EON_SHORT. ## Prerequisites From cc46500867673f0718337dd5fec543f0c47089a5 Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Mon, 20 Oct 2025 17:04:43 +0200 Subject: [PATCH 14/15] Apply suggestions from code review Co-authored-by: John Pruitt Signed-off-by: Iain Cox --- ai/tiger-eon.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ai/tiger-eon.md b/ai/tiger-eon.md index d572e9e0fa..3a0f8a2402 100644 --- a/ai/tiger-eon.md +++ b/ai/tiger-eon.md @@ -26,8 +26,8 @@ $EON_LONG: - **Unlocks hidden value**: your data in Slack, GitHub, and Linear already contain the insights you need. $EON_SHORT makes them accessible. - **Enables faster decisions**: no need to search or ask around, you get answers in seconds. -- **Is easy to use**: $EON_SHORT runs a $AGENTS_SHORT and MCP servers statelessly in a lightweight Docker container. -- **Integrates seamlessly with $CLOUD_LONG**: $EON_SHORT creates a free $SERVICE_LONG so you securely and reliably store +- **Is easy to use**: $EON_SHORT runs a $AGENTS_SHORT and MCP servers statelessly in lightweight Docker containers. +- **Integrates seamlessly with $CLOUD_LONG**: $EON_SHORT uses a $SERVICE_LONG so you securely and reliably store your company data. Prefer to self-host? Use a [$PG instance with $TIMESCALE_DB][install-self-hosted]. $EON_LONGs real-time ingestion system connects to Slack and captures everything: every message, reaction, edit, and @@ -66,7 +66,7 @@ and runs the following components for you: - A listener Slack app that passes questions to the $AGENTS_SHORT when you @tag it in a public channel, and returns the AI analysis on your data -All local components are run in a lightweight Docker container. +All local components are run in lightweight Docker containers via Docker Compose. This section shows you how to run the $EON_SHORT setup to configure $EON_SHORT to connect to your Slack app, and give them access to your data and analytics stored in $CLOUD_LONG. From 666cdcbdd316df53ec004af98dffb33d2db1fb3e Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Mon, 20 Oct 2025 17:14:34 +0200 Subject: [PATCH 15/15] chore: Updates on review. --- ai/tiger-eon.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/ai/tiger-eon.md b/ai/tiger-eon.md index 3a0f8a2402..2029bcc471 100644 --- a/ai/tiger-eon.md +++ b/ai/tiger-eon.md @@ -51,8 +51,12 @@ This page shows you how to install and run $EON_SHORT. - [Install Docker][install-docker] on your developer device +- Install [$CLI_LONG][tiger-cli] - Have rights to create an [Anthropic API key][claude-api-key] -- Have rights to create a [GitHub token][github-token] +- Optionally: + - Have rights to create a [GitHub token][github-token] + - Have rights to create a [Logfire token][logfire-token] + - Have rights to create a [Linear token][linear-token] ## Interactive setup @@ -79,18 +83,14 @@ data and analytics stored in $CLOUD_LONG. ```shell git clone git@github.com:timescale/tiger-eon.git ``` - -1. **Configure $EON_SHORT** - - The $EON_SHORT setup creates and configures the Slack apps and the $SERVICE_LONG for $EON_SHORT to run correctly: - + 1. **Start the $EON_SHORT setup** ```shell cd tiger-eon ./setup-tiger-eon.sh ``` - You see a resume of the setup procedure. Type `y` and press `Enter`. + You see a summary of the setup procedure. Type `y` and press `Enter`. 1. **Create the $SERVICE_LONG to use with $EON_SHORT** @@ -112,6 +112,7 @@ data and analytics stored in $CLOUD_LONG. $EON_SHORT opens `Your Apps` in https://api.slack.com/apps/. 1. Start configuring your ingest app in Slack: + In the Slack `Your Apps` page: 1. Click `Create New App`, click `From an manifest`, then select a workspace. 1. Click `Next`. Slack opens `Create app from manifest`. @@ -200,4 +201,6 @@ invite `@eon` to join, then ask a question: [tiger-cli]: https://github.com/timescale/tiger-cli/ [tiger-agents]: https://github.com/timescale/tiger-agents-for-work [services-portal]: https://console.cloud.timescale.com/dashboard/services -[install-self-hosted]: /self-hosted/:currentVersion:/install/ \ No newline at end of file +[install-self-hosted]: /self-hosted/:currentVersion:/install/ +[logfire-token]: http://logfire.pydantic.dev/docs/how-to-guides/create-write-tokens/ +[linear-token]: https://linear.app/docs/api-and-webhooks#api-keys \ No newline at end of file