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 8ec63a7aa0..4bc352130d 100644 --- a/ai/page-index/page-index.js +++ b/ai/page-index/page-index.js @@ -1,12 +1,22 @@ module.exports = [ { - title: "AI and Vector: pgai on Tiger", + title: "AI and Vector", href: "ai", filePath: "index.md", pageComponents: ["featured-cards"], excerpt: "Information about pgai on TigerData and how to use it.", children: [ + { + 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.md b/ai/tiger-agents-for-work.md new file mode 100644 index 0000000000..6b3a7910aa --- /dev/null +++ b/ai/tiger-agents-for-work.md @@ -0,0 +1,294 @@ +--- +title: Integrate a slack-native AI agent +excerpt: Unify company knowledge with slack-native AI agents +products: [cloud] +keywords: [ai, vector, pgvector, TigerData vector, pgvectorizer] +tags: [ai, vector, pgvectorizer] +--- + +# Integrate a slack-native AI agent + +import PrereqAccount from "versionContent/_partials/_prereqs-cloud-project-and-self.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 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 +- **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 + + + +* 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** + + 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-eon.md b/ai/tiger-eon.md new file mode 100644 index 0000000000..2029bcc471 --- /dev/null +++ b/ai/tiger-eon.md @@ -0,0 +1,206 @@ +--- +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_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-eon-big-question.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 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 +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 + + + +- [Install Docker][install-docker] on your developer device +- Install [$CLI_LONG][tiger-cli] +- Have rights to create an [Anthropic API key][claude-api-key] +- 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 + +$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 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 + AI analysis on your data + +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. + + + +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. **Start the $EON_SHORT setup** + + ```shell + cd tiger-eon + ./setup-tiger-eon.sh + ``` + You see a summary 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 $EON_SHORT setup creates and runs $TIMESCALE_DB in a local Docker container. + +1. **Create the 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. + + $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`. + + 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. 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 $EON_SHORT Slack app** + + Follow the same procedure as you did for the ingest Slack app. + +1. **Integrate $EON_SHORT with Anthropic** + + 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** + + 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** + + 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 paste the GitHub token. + + 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) + + + +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 + +## Integrate $EON_SHORT in your Slack workspace + +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) + + +[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/ +[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