# Archer: AI Agent for Slack - Comprehensive Documentation

![archer](https://lh3.googleusercontent.com/fife/ALs6j_E10JB-RR6RBvn85qi0CKst4knk4ZbdoclCyJvB1YZlOllsiCit3tFPiMTNyMh9b3aVMi3Xtwnw6RBgYV8aBOLsHqaG2Fsuxr8EezgWCCORrpvhYuiTV7AvIxoSQb474CfR-UQKex9XH_J7b6g12EHGo1otorj4xTLYPENT1xDc0ZHb05uQrN4ovJvI82Jq4e-LjdZjWbBVMwE1GJe0pmk_TQ2ATKiKXj_MAmED5TuCzmDUQJYRpI_vp9IBjFmetHdhR7VV5W0K_Fq91akzzYblTu33vpIoML5YKwe78gdm6Eib6j_67FPeXx7YUrahRqu6NImfC26JH3YkKBCvIN8o5Kl1Q9f6vf68z2yvrG7n8Ukydx5SjLbMp4YjcmkimcWx59D1HrzwxcmwMosUaAMw_VXa-EWbEfchoFYB4O-JSPHyCWc3d3VAJ-pGEbxWRZW-HuwypGMFNGCLmBramPDTn8HCb_PPmWQH9eLOPZ1uBW_9ug1UcofNg2w2LdgS27ri4J8YYkgygnwMDciQgKA2NmH7xSroawLV6Bl2ibN6M0p7yth5RkLc6Mw-IShRqyUCsAfyKmgflUYjKRMQXypZdVXhkKZupZkYboUmZhL7mYBYxkuDkr5Q1pYh913QkPQq6iL4qe5-07zRBX_PUj9AVp3wePmlOupUpMAWIPFTi3bQHvz7c7qIFtVZmZV2k0Tkus3snyvH_EbiOCiawrssl7RxZ0aWJDFsObAYGcwacAjyHFUuN18OOAB90JrTjKnof5SDZgrhn3_hz3Ggq6RUDvuYeZo9r0UAEM0rjtefv9E9KnqHivURkeGR0zZOP8O1AIH7VOuZuZ-DyJeoh7eMwBRsLYeJE2tWoXsWWmD5GjcIQSkKVC2qPmkVpZch-kxgjN2YbYZ3o9DELSbfC7olgCDFhIVrTsv9xh1BFO_Vdcoenha0faVQd-oxiOpgXdNxb53TGvkyatBoUJCvbLXQmZTAK3CY-lqJyqOPd5AsibRxWfbP_2xNCDc8b0_87oyJKhEpB0sY_1ww7gdZR68r5R-TSfTcPmE=w1181-h967?auditContext=prefetch)

Archer: Agentic Slack Assistant

An intelligent AI agent that enhances productivity within Slack by performing actions on your behalf

## Table of Contents 1. [Overview](#overview) 2. [Architecture](#architecture) 3. [Features & Capabilities](#features--capabilities) 4. [Security & Authentication](#security--authentication) 5. [Workflows & Examples](#workflows--examples) 6. [Installation & Setup](#installation--setup) 7. [Configuration](#configuration) 8. [API Reference](#api-reference) 9. [Troubleshooting](#troubleshooting) --- ## Overview Archer is a sophisticated AI agent built for Slack that leverages the power of Arcade AI to provide seamless integration with multiple services and tools. It transforms Slack into a command center for managing emails, calendars, code repositories, web searches, and more - all through natural language conversations. ### Key Benefits - **Unified Interface**: Access multiple services from within Slack - **Natural Language Processing**: Communicate with tools using plain English - **Secure Authentication**: OAuth-based authorization for each service - **Conversation Memory**: Maintains context across interactions - **Parallel Tool Execution**: Handle multiple tasks simultaneously - **Error Recovery**: Robust error handling and retry mechanisms --- ## Architecture ### System Architecture ```mermaid graph TB subgraph "Slack Workspace" U[User] --> S[Slack Client] S --> SE[Slack Events] end subgraph "Archer Server" SE --> FH[FastAPI Handler] FH --> SA[Slack App] SA --> EL[Event Listeners] EL --> AG[Agent Manager] end subgraph "Agent Layer" AG --> LG[LangGraph Agent] LG --> LLM[Language Model] LG --> TM[Tool Manager] end subgraph "Arcade Integration" TM --> AT[Arcade Tool Manager] AT --> T1[GitHub Tools] AT --> T2[Google Tools] AT --> T3[Search Tools] AT --> T4[Web Tools] end subgraph "External Services" T1 --> GH[GitHub API] T2 --> GC[Google Calendar] T2 --> GM[Gmail] T3 --> SE2[Search Engine] T4 --> WC[Web Crawler] end subgraph "Storage" LG --> MS[Memory Store] MS --> FS[File Storage] end ``` ### Agent Workflow Graph ```mermaid stateDiagram-v2 [*] --> START START --> AGENT: User Message AGENT --> DECISION: Process Message DECISION --> TOOLS: Tool Calls Required DECISION --> AUTH_CHECK: Auth Required DECISION --> END: No Tools Needed AUTH_CHECK --> AUTH_INTERRUPT: Auth URLs Generated AUTH_CHECK --> TOOLS: All Tools Authorized AUTH_INTERRUPT --> [*]: Wait for User Auth TOOLS --> AGENT: Tool Results AGENT --> DECISION: Continue Processing ``` ### Event Processing Flow ```mermaid sequenceDiagram participant User participant Slack participant FastAPI participant EventHandler participant Agent participant Arcade participant ExternalAPI User->>Slack: Send Message Slack->>FastAPI: POST /slack/events FastAPI->>EventHandler: Process Event EventHandler->>Agent: Invoke Agent Agent->>Arcade: Request Tool Access Arcade->>ExternalAPI: API Call ExternalAPI-->>Arcade: Response Arcade-->>Agent: Tool Result Agent-->>EventHandler: Agent Response EventHandler-->>FastAPI: Send Reply FastAPI-->>Slack: Post Message Slack-->>User: Display Response ``` --- ## Features & Capabilities ### Core Toolkits Archer integrates with the following toolkits by default: #### 1. GitHub Integration - **Repository Management**: Create, read, update repositories - **Pull Request Operations**: Review, merge, comment on PRs - **Issue Tracking**: Create, update, assign issues - **Code Analysis**: Search code, view file contents - **Branch Management**: Create, delete, merge branches #### 2. Google Services - **Gmail Management**: Read, compose, send emails - **Calendar Operations**: Schedule meetings, view events - **Drive Access**: Upload, download, share files - **Docs Integration**: Create, edit documents #### 3. Search & Web Tools - **Web Search**: Google, Bing, DuckDuckGo integration - **Web Scraping**: Extract data from websites - **Content Analysis**: Summarize web pages - **Link Validation**: Check URL accessibility #### 4. Communication Tools - **Slack Integration**: Send messages, create channels - **Email Management**: Multi-provider email support - **Notification Systems**: Push notifications, alerts ### Advanced Features #### Conversation Memory - **Thread-based Context**: Maintains conversation history per thread - **State Persistence**: Saves agent state across sessions - **Context Awareness**: Remembers user preferences and past interactions #### Parallel Processing - **Multi-tool Execution**: Run multiple tools simultaneously - **Async Operations**: Non-blocking API calls - **Batch Processing**: Handle multiple requests efficiently #### Error Handling - **Graceful Degradation**: Continue operation despite tool failures - **Retry Mechanisms**: Automatic retry for transient failures - **Fallback Strategies**: Alternative approaches when primary methods fail --- ## Security & Authentication ### Authentication Architecture ```mermaid graph LR subgraph "User Authentication Flow" U[User] --> A[Agent Request] A --> AC[Auth Check] AC --> AU[Auth Required?] AU -->|Yes| AG[Generate Auth URLs] AU -->|No| EX[Execute Tools] AG --> UI[User Interface] UI --> UA[User Authorization] UA --> VC[Verify Credentials] VC --> EX end subgraph "Security Layers" SL[Slack Verification] SL --> SR[Request Signing] SR --> EV[Event Validation] EV --> AC end ``` ### Security Features #### 1. Request Verification - **Slack Signature Validation**: Verifies requests come from Slack - **Timestamp Validation**: Prevents replay attacks - **Event Deduplication**: Prevents duplicate processing #### 2. OAuth Integration - **Service-specific Tokens**: Each service has its own OAuth flow - **Token Encryption**: Secure storage of access tokens - **Scope Management**: Minimal required permissions #### 3. Data Protection - **Local Storage**: User data stored locally, not in cloud - **Encrypted Communication**: All API calls use HTTPS - **Token Rotation**: Automatic token refresh mechanisms ### Authorization Workflow ```mermaid sequenceDiagram participant User participant Agent participant Arcade participant Service participant Storage User->>Agent: Request requiring auth Agent->>Arcade: Check auth status Arcade->>Storage: Check existing tokens Storage-->>Arcade: No tokens found Arcade-->>Agent: Auth required Agent-->>User: Send auth URLs User->>Service: Authorize application Service-->>Arcade: OAuth callback Arcade->>Storage: Store tokens Arcade-->>Agent: Auth complete Agent->>Service: Execute request Service-->>Agent: Response Agent-->>User: Send results ``` --- ## Workflows & Examples ### Example 1: Email Management Workflow **User Request**: "Read my last 10 emails and summarize them" ```mermaid sequenceDiagram participant User participant Archer participant Gmail participant LLM User->>Archer: "Read my last 10 emails" Archer->>Archer: Check Gmail auth Archer->>User: "Please authorize Gmail access" User->>Gmail: Complete OAuth Gmail-->>Archer: Auth tokens Archer->>Gmail: Fetch last 10 emails Gmail-->>Archer: Email data Archer->>LLM: Summarize emails LLM-->>Archer: Summary Archer-->>User: Email summary ``` **Example Response**: ``` 📧 **Email Summary (Last 10)** 1. **Meeting Reminder** - Team standup tomorrow at 10 AM 2. **Project Update** - Q4 goals review from Sarah 3. **Invoice Received** - Payment confirmation for invoice #1234 4. **Code Review** - PR #567 needs your review 5. **Newsletter** - Weekly tech digest from TechCrunch 6. **Calendar Invite** - Client meeting on Friday 7. **System Alert** - Server maintenance scheduled 8. **Document Share** - New design specs shared by John 9. **Approval Request** - Expense report needs approval 10. **Welcome Email** - New team member onboarding **Key Actions Needed:** - Review PR #567 - Approve expense report - Prepare for client meeting ``` ### Example 2: GitHub Development Workflow **User Request**: "Show me recent PRs in the arcadeai/arcade-ai repository" ```mermaid sequenceDiagram participant User participant Archer participant GitHub participant LLM User->>Archer: "Show recent PRs" Archer->>Archer: Check GitHub auth Archer->>GitHub: Fetch PRs from arcadeai/arcade-ai GitHub-->>Archer: PR data Archer->>LLM: Format PR information LLM-->>Archer: Formatted response Archer-->>User: PR summary with links ``` **Example Response**: ``` 🔧 **Recent Pull Requests - arcadeai/arcade-ai** **Open PRs:** 1. **#1234** - Add new authentication flow - Author: @john-doe - Status: Ready for review - Changes: 15 files, +234 -45 lines 2. **#1235** - Fix memory leak in agent - Author: @jane-smith - Status: In progress - Changes: 3 files, +12 -8 lines 3. **#1236** - Update documentation - Author: @mike-wilson - Status: Draft - Changes: 8 files, +156 -23 lines **Recently Merged:** - **#1233** - Performance improvements (merged 2 hours ago) - **#1232** - Bug fix for edge case (merged 1 day ago) **Your Action Items:** - Review PR #1234 (assigned to you) - Check PR #1235 for potential conflicts ``` ### Example 3: Calendar Management Workflow **User Request**: "Schedule a meeting with the development team for tomorrow at 2 PM" ```mermaid sequenceDiagram participant User participant Archer participant Calendar participant Team participant LLM User->>Archer: "Schedule team meeting" Archer->>Calendar: Check availability Calendar-->>Archer: Available slots Archer->>LLM: Determine best time LLM-->>Archer: Suggested time Archer->>Calendar: Create event Calendar-->>Archer: Event created Archer->>Team: Send invites Archer-->>User: Confirmation ``` **Example Response**: ``` 📅 **Meeting Scheduled Successfully** **Event Details:** - **Title**: Development Team Meeting - **Date**: Tomorrow (Tuesday, March 5th) - **Time**: 2:00 PM - 3:00 PM EST - **Location**: Google Meet (link generated) - **Attendees**: - @john-doe (confirmed) - @jane-smith (pending) - @mike-wilson (pending) **Calendar Link**: [View in Calendar](https://calendar.google.com/event/...) **Next Steps:** - Meeting agenda will be shared 1 hour before - Recording will be available after the meeting - Follow-up tasks will be created based on discussion ``` ### Example 4: Multi-Service Integration Workflow **User Request**: "Find information about the latest React updates and create a summary document" ```mermaid sequenceDiagram participant User participant Archer participant Search participant Web participant Docs participant LLM User->>Archer: "Find React updates and create summary" Archer->>Search: Search for "React latest updates 2024" Search-->>Archer: Search results Archer->>Web: Scrape relevant articles Web-->>Archer: Article content Archer->>LLM: Analyze and summarize LLM-->>Archer: Summary content Archer->>Docs: Create document Docs-->>Archer: Document link Archer-->>User: Summary with document link ``` **Example Response**: ``` 🔍 **React Updates Summary** **Latest React 19 Features:** - **Concurrent Features**: Improved rendering performance - **Server Components**: Enhanced server-side rendering - **New Hooks**: use() hook for data fetching - **Compiler Improvements**: Better optimization **Key Changes:** - Automatic batching for all updates - Improved error boundaries - Better TypeScript support - Enhanced developer tools **Breaking Changes:** - Removed legacy context API - Updated event pooling behavior - Modified component lifecycle methods 📄 **Summary Document**: [React 19 Updates Summary](https://docs.google.com/document/...) **Sources:** - React Blog (official) - MDN Web Docs - React GitHub repository - Community discussions ``` --- ## Installation & Setup ### Prerequisites - **Python**: 3.10 or higher - **Poetry**: 1.8.4+ (for dependency management) - **OpenAI API Key**: For language model access - **Arcade API Key**: For tool integrations - **Slack App**: Configured with proper permissions ### Step-by-Step Installation #### 1. Clone and Install ```bash # Clone the repository git clone https://github.com/arcadeai/archer.git cd archer # Install dependencies make install ``` #### 2. Environment Configuration Create a `.env` file with the following variables: ```bash # Slack Configuration SLACK_BOT_TOKEN=xoxb-your-bot-token SLACK_SIGNING_SECRET=your-signing-secret # AI Services OPENAI_API_KEY=sk-your-openai-key ARCADE_API_KEY=your-arcade-key # Logging LOG_LEVEL=INFO # Optional: LangSmith for tracing LANGSMITH_TRACING=true LANGSMITH_ENDPOINT=https://api.smith.langchain.com LANGSMITH_API_KEY=your-langsmith-key LANGSMITH_PROJECT=archer ``` #### 3. Slack App Setup 1. **Create Slack App**: - Visit [https://api.slack.com/apps/new](https://api.slack.com/apps/new) - Choose "From an app manifest" - Upload the `config/manifest.json` file 2. **Configure Permissions**: ```json { "oauth_config": { "scopes": { "bot": [ "chat:write", "chat:write.public", "im:history", "im:read", "im:write", "users:read", "assistant:write" ] } } } ``` 3. **Set Event Subscriptions**: - Enable events for: `app_home_opened`, `message.im`, `assistant_thread_started` - Set request URL to your deployment endpoint #### 4. Deploy to Modal ```bash # Deploy the application make deploy # Modal will provide a URL like: https://your-app.modal.run ``` #### 5. Update Slack Configuration Replace the placeholder URLs in your Slack app configuration: - Event Subscriptions: `https://your-app.modal.run/slack/events` - Interactivity: `https://your-app.modal.run/slack/events` --- ## Configuration ### Agent Configuration The agent can be configured through the `archer/defaults.py` file: ```python # Available Models MODELS = { "gpt-4o": { "name": "GPT-4o", "provider": "OpenAI", "max_tokens": 128000, "parallel_tool_calling": True, }, "gpt-4o-mini": { "name": "GPT-4o mini", "provider": "OpenAI", "max_tokens": 128000, "parallel_tool_calling": True, } } # Available Toolkits TOOLKITS = ["github", "google", "search", "web"] ``` ### System Prompt Customization ```python SYSTEM_CONTENT = """ You are a versatile AI assistant named Archer. You were created by Arcade AI. Provide concise, relevant assistance tailored to each request from users. Key capabilities: - Email management and composition - Calendar scheduling and management - GitHub repository operations - Web search and content extraction - Document creation and editing Be professional, friendly, and efficient in your responses. """ ``` ### Storage Configuration Archer uses file-based storage by default. Configure storage options: ```python # File storage configuration STORAGE_CONFIG = { "type": "file", "base_dir": "./data", "users_dir": "./data/users", "states_dir": "./data/states" } ``` --- ## API Reference ### Event Handlers #### Message Events ```python @app.event("message") def handle_message_events(message, say, logger, context, client): """ Handle regular text messages in DMs and channels. Args: message: The message object from Slack say: Function to send messages logger: Logger instance context: Bolt context with channel info client: Slack Web API client """ ``` #### Assistant Events ```python @assistant.user_message def respond_in_assistant_thread(payload, logger, context, set_status, say, client): """ Handle messages in Slack's AI assistant threads. Args: payload: Message payload logger: Logger instance context: Bolt context set_status: Function to set assistant status say: Function to send messages client: Slack Web API client """ ``` ### Agent API #### Invoke Agent ```python from archer.agent import invoke_agent response = invoke_agent( user_id="U1234567890", prompt="Read my emails", context=conversation_history, thread_id="unique-thread-id" ) ``` #### Agent State Management ```python # Save agent state agent.save_state(thread_id, state_data) # Retrieve agent state state = agent.get_state(thread_id) ``` ### Storage API #### User Management ```python from archer.storage import get_storage storage = get_storage() # Save user identity storage.set_state({ "user_id": "U1234567890", "provider": "openai", "model": "gpt-4o" }) # Get user state user_state = storage.get_state("U1234567890") ``` --- ## Troubleshooting ### Common Issues #### 1. Authentication Errors **Problem**: "Authorization required for tools" **Solution**: ```bash # Check Arcade API key echo $ARCADE_API_KEY # Verify Slack tokens curl -H "Authorization: Bearer $SLACK_BOT_TOKEN" \ https://slack.com/api/auth.test ``` #### 2. Event Processing Issues **Problem**: Events not being processed **Solution**: ```python # Check event deduplication # Events are deduplicated to prevent double processing # Check logs for "Duplicate event detected" messages ``` #### 3. Tool Execution Failures **Problem**: Tools failing to execute **Solution**: ```python # Check tool configuration from archer.defaults import get_available_toolkits print(get_available_toolkits()) # Verify Arcade tool availability from langchain_arcade import ArcadeToolManager manager = ArcadeToolManager() tools = manager.get_tools() ``` #### 4. Memory Issues **Problem**: Agent losing context **Solution**: ```python # Check storage configuration # Ensure data directory is writable ls -la ./data/ # Verify thread_id consistency # Each conversation should have a unique thread_id ``` ### Debug Mode Enable debug logging: ```bash # Set environment variable export LOG_LEVEL=DEBUG # Or in .env file LOG_LEVEL=DEBUG ``` ### Performance Optimization #### 1. Model Selection ```python # Use faster models for simple tasks MODELS = { "gpt-4o-mini": { "name": "GPT-4o mini", "provider": "OpenAI", "max_tokens": 128000, "parallel_tool_calling": True, } } ``` #### 2. Tool Optimization ```python # Limit toolkits to essential ones TOOLKITS = ["github", "google"] # Remove unused toolkits ``` #### 3. Memory Management ```python # Configure memory limits MEMORY_CONFIG = { "max_events": 1000, "cleanup_interval": 3600 # Cleanup every hour } ``` --- ## Contributing ### Development Setup ```bash # Clone repository git clone https://github.com/arcadeai/archer.git cd archer # Install development dependencies poetry install --with dev # Run tests make test # Run linting make lint ``` ### Code Structure ``` archer/ ├── agent/ # Agent implementation ├── listeners/ # Event handlers ├── storage/ # Data persistence ├── utils/ # Utility functions ├── defaults.py # Configuration ├── env.py # Environment variables └── server.py # FastAPI server ``` ### Testing ```bash # Run unit tests pytest tests/ # Run integration tests pytest tests/integration/ # Run with coverage pytest --cov=archer tests/ ``` --- ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. --- ## Support - **Documentation**: [https://docs.arcade.dev](https://docs.arcade.dev) - **Issues**: [GitHub Issues](https://github.com/arcadeai/archer/issues) - **Discussions**: [GitHub Discussions](https://github.com/arcadeai/archer/discussions) - **Community**: [Arcade Discord](https://discord.gg/arcade) - **Github Repo**:[Mikey's Updated One](https://github.com/MikeySharma/SlackAgent-Arcade-Demo) ---

Built with ❤️ by the Arcade AI team and edited by Mikey Sharma

Archer: Transform Slack into an AI-Powered Command Center

Share: