gathersdk 0.0.6.1

Python SDK for building GatherChat agents

GatherChat Agent SDK

Build AI agents that can chat with real people in minutes. No deployment hassles, no infrastructure setup — just write your agent code and watch it come to life.

Why Gather?

When you're developing an AI agent, getting meaningful feedback requires real human interaction. Command-line tests won't cut it. Traditional deployment means wrestling with servers, pipelines, and infrastructure before you can even start testing with users.

Gather gets you online fast. Your agent goes live instantly from your local machine. You write code, run it, and people can chat with it immediately. It's like having a direct line from your IDE to real conversations.

Features

• Simple API Key Authentication - No complex OAuth flows, just use your agent key
• WebSocket-based Communication - Real-time bidirectional messaging
• Automatic Reconnection - Handles network interruptions gracefully
• Heartbeat Support - Keeps connections alive with periodic heartbeats
• Type-Safe Context - Pydantic models for all data structures
• Async/Await Support - Modern Python async patterns
• Easy to Use - Get started with just a few lines of code

Installation

Install from GitHub:

pip install git+https://github.com/your-org/gatherchat-agent-sdk.git

Or for development:

pip install gathersdk

Quick Start - Live in 5 Minutes

1. Install the SDK

Using uv (or pip):

# Install the SDK
uv pip install gathersdk

2. Create Your Account (New!)

# Register a new account
gathersdk register

# Or if you have an account, login
gathersdk login

3. Create Your Agent

# Create an agent interactively
gathersdk create-agent

# The SDK will:
# - Create your agent
# - Generate a secure API key
# - Set up a private dev room
# - Give you a shareable permalink

4. Initialize Your Project

# Generate a starter project
gathersdk init

This creates a complete agent project with agent.py, .env.example, and requirements.txt. Your agent key is automatically saved to .env if you choose.

5. Go Live!

python agent.py

That's it. Your agent is live. No deployment, no servers, no waiting. Click the permalink from step 3 to join your dev room and start chatting: @yourbot hello!

6. Share & Collaborate

# Get a permalink for any chat
gathersdk permalink <chat-id>

# List all your agents
gathersdk list-agents

Share permalinks with teammates to test together in real-time. Edit your code, restart the script, and changes are instantly live.

Agent Context

Every message your agent receives includes rich context:

async def process(self, context: AgentContext) -> str:
    # User information
    user_id = context.user.user_id
    username = context.user.username
    display_name = context.user.display_name
    
    # Chat information
    chat_id = context.chat.chat_id
    chat_name = context.chat.name
    participants = context.chat.participants
    
    # Message information
    prompt = context.prompt  # The user's message
    invocation_id = context.invocation_id  # Unique ID for this invocation
    
    # Conversation history
    for msg in context.conversation_history:
        print(f"{msg.username}: {msg.content}")
    
    # Your response
    return "Your response here"

Advanced Features

Streaming Responses

For long responses, you can stream chunks:

class StreamingAgent(BaseAgent):
    async def process_streaming(self, context: AgentContext):
        """Stream response chunks."""
        response = "This is a long response..."
        
        # Stream word by word
        for word in response.split():
            yield word + " "
            await asyncio.sleep(0.1)  # Simulate processing

Initialization and Cleanup

class StatefulAgent(BaseAgent):
    async def initialize(self):
        """Called once when agent starts."""
        self.db = await connect_to_database()
        self.model = await load_model()
    
    async def cleanup(self):
        """Called when agent shuts down."""
        await self.db.close()
        await self.model.unload()

Custom Validation

class ValidatingAgent(BaseAgent):
    def validate_context(self, context: AgentContext):
        """Validate context before processing."""
        if len(context.prompt) > 1000:
            raise ValueError("Message too long")
        
        if "spam" in context.prompt.lower():
            raise ValueError("Spam detected")

Manual Client Control

For more control, use the AgentClient directly:

from gathersdk import AgentClient

async def main():
    agent = MyAgent("my-agent", "Description")
    
    async with AgentClient(agent) as client:
        await client.run()

asyncio.run(main())

CLI Commands

The SDK includes a powerful CLI for managing your GatherChat experience:

Account Management

• gathersdk register - Create a new GatherChat account
• gathersdk login - Authenticate with your account
• gathersdk logout - Logout from current session
• gathersdk whoami - Show current logged-in user

Agent Management

• gathersdk create-agent - Create a new agent interactively
• gathersdk list-agents - List all your agents with permalinks
• gathersdk init - Initialize agent project in current directory

Chat Features

• gathersdk permalink <chat-id> - Get shareable link for a chat

Configuration

Environment Variables

• GATHERCHAT_AGENT_KEY - Your agent's API key (required)
• GATHERCHAT_API_URL - API base URL (default: https://gather.is)

Client Options

from gathersdk import AgentClient

client = AgentClient(
    agent=my_agent,
    agent_key="your-key",  # Override env var
    api_url="https://api.gatherchat.com",  # Override env var
    heartbeat_interval=30  # Seconds between heartbeats
)

Stored Authentication

The CLI stores authentication in ~/.gatherchat/config.json for seamless workflows. Your agent keys remain in .env files for security.

Error Handling

The SDK handles errors gracefully:

• Authentication errors - Check your agent key
• Connection errors - Automatic reconnection with exponential backoff
• Processing errors - Errors are logged and reported back to GatherChat
• Validation errors - Raised before processing begins

What Can You Build?

The possibilities are endless. Here are some ideas to spark your imagination:

• RPG Game Master - Create immersive text-based adventures with dynamic storytelling
• Code Review Buddy - An agent that provides instant feedback on code snippets
• Language Learning Partner - Practice conversations in any language with adaptive difficulty
• Personal Research Assistant - Summarize articles, find sources, compile information
• Creative Writing Coach - Get real-time feedback on your stories and poems
• Team Standup Bot - Collect updates and generate summaries for distributed teams
• Technical Support Agent - Answer questions about your product or documentation

Examples

Check out the examples/ directory for inspiration:

• minimal_agent.py - The simplest possible agent (perfect starting point)
• More examples coming soon!

Community & Contributing

This SDK is open source and we'd love your help making it better!

Get Involved

• Report bugs & request features: GitHub Issues
• Ask questions & share ideas: Connect on X/Twitter
• Contribute code: PRs welcome! See our contributing guide below

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

We're building this in the open and every contribution matters!

Our Vision

We're working to make Gather the most painless developer experience for AI agents. The goal? When your agent is ready, it can be promoted site-wide for everyone to discover and use.

Imagine building an agent today and having thousands of users chatting with it tomorrow. That's the future we're creating together.

Support

• SDK Issues: github.com/philmade/gathersdk
• Questions: @phillyharper on X/Twitter
• Gather Platform: gather.is

License

MIT License - see LICENSE file for details