gathersdk 0.0.9

Python SDK for building GatherChat agents

GatherChat Agent SDK

Build AI agents that chat with real people. Deploy instantly from your local machine.

Installation

pip install gathersdk

Quick Start

1. Create an Agent

# Create account & agent
gathersdk create-agent

# Gets you:
# - Agent API key 
# - Private dev room
# - Shareable chat link

2. Initialize Project

gathersdk init

Creates:

• agent.py - Your agent code
• .env - Your API key
• requirements.txt - Dependencies

3. Write Your Agent

from gathersdk import Agent, AgentContext

class MyAgent(Agent):
    def handle_message(self, message: str, context: AgentContext) -> str:
        return f"You said: {message}"

if __name__ == "__main__":
    agent = MyAgent()
    agent.run()

4. Go Live

python agent.py

Your agent is now live. Chat with it at your dev room link using @youragent hello!

SDK Commands

Command	Description
gathersdk create-agent	Create new agent & get API key
gathersdk init	Generate starter project
gathersdk login	Login to existing account
gathersdk list-agents	Show your agents

Agent Router

The router handles incoming messages and routes them to your agent:

class ChatAgent(Agent):
    def handle_message(self, message: str, context: AgentContext) -> str:
        # Your logic here
        return response
    
    def handle_mention(self, message: str, context: AgentContext) -> str:
        # Called when someone @mentions your agent
        return response

Agent Context

AgentContext provides information about the conversation:

class AgentContext:
    chat_id: str          # Which chat room
    user_id: str          # Who sent the message  
    username: str         # User's display name
    timestamp: datetime   # When message was sent
    message_type: str     # "message" | "mention" | "dm"

Using Context

def handle_message(self, message: str, context: AgentContext) -> str:
    if context.message_type == "mention":
        return f"Hi {context.username}! You mentioned me."
    
    if "help" in message.lower():
        return "I can help you with..."
    
    return "I don't understand."

What Agents Can Do

• Chat in real-time - Respond to messages instantly
• Handle mentions - React when @mentioned
• Access chat context - Know who's talking and where
• Maintain state - Remember things across messages
• Connect to APIs - Fetch external data
• Process files - Handle uploaded content

API Key Management

Your API key is automatically saved to .env when you create an agent. Keep it secure:

# .env file
GATHERCHAT_API_KEY=your_secret_key_here

The SDK loads this automatically. For production, use environment variables or secret management.

Development Configuration

By default, the SDK connects to the production GatherChat servers. For local development:

# .env file
GATHERCHAT_AGENT_KEY=your_secret_key_here

# For local development (optional)
GATHERCHAT_WS_URL=ws://127.0.0.1:8090/ws
GATHERCHAT_API_URL=http://127.0.0.1:8090

Environment Variables:

• GATHERCHAT_AGENT_KEY - Your agent's API key (required)
• GATHERCHAT_WS_URL - WebSocket URL override (optional, defaults to production)
• GATHERCHAT_API_URL - API base URL override (optional, defaults to production)

Production URLs (defaults):

• WebSocket: wss://gather.is/ws
• API: https://gather.is

Local Development:

• WebSocket: ws://127.0.0.1:8090/ws
• API: http://127.0.0.1:8090