# GatherChat Agent SDK
Build AI agents that chat with real people. Deploy instantly from your local machine.
## Installation
```bash
pip install gathersdk
```
## Quick Start
### 1. Create an Agent
```bash
# Create account & agent
gathersdk create-agent
# Gets you:
# - Agent API key
# - Private dev room
# - Shareable chat link
```
### 2. Initialize Project
```bash
gathersdk init
```
Creates:
- `agent.py` - Your agent code
- `.env` - Your API key
- `requirements.txt` - Dependencies
### 3. Write Your Agent
```python
from gatherchat_agent_sdk 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
```bash
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:
```python
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:
```python
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
```python
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:
```bash
# .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:
```bash
# .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`
Raw data
{
"_id": null,
"home_page": "https://github.com/gatherchat/gatherchat-agent-sdk",
"name": "gathersdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "gatherchat gathersdk agent chatbot websocket async",
"author": "GatherChat Team",
"author_email": "sdk@gather.is",
"download_url": "https://files.pythonhosted.org/packages/0e/ac/e524d74a2675e061887d6a9dc6be3db5cd78de0bd8c8586d65cd6494664a/gathersdk-0.0.6.6.tar.gz",
"platform": null,
"description": "# GatherChat Agent SDK\n\nBuild AI agents that chat with real people. Deploy instantly from your local machine.\n\n## Installation\n\n```bash\npip install gathersdk\n```\n\n## Quick Start\n\n### 1. Create an Agent\n\n```bash\n# Create account & agent\ngathersdk create-agent\n\n# Gets you:\n# - Agent API key \n# - Private dev room\n# - Shareable chat link\n```\n\n### 2. Initialize Project\n\n```bash\ngathersdk init\n```\n\nCreates:\n- `agent.py` - Your agent code\n- `.env` - Your API key\n- `requirements.txt` - Dependencies\n\n### 3. Write Your Agent\n\n```python\nfrom gatherchat_agent_sdk import Agent, AgentContext\n\nclass MyAgent(Agent):\n def handle_message(self, message: str, context: AgentContext) -> str:\n return f\"You said: {message}\"\n\nif __name__ == \"__main__\":\n agent = MyAgent()\n agent.run()\n```\n\n### 4. Go Live\n\n```bash\npython agent.py\n```\n\nYour agent is now live. Chat with it at your dev room link using `@youragent hello!`\n\n## SDK Commands\n\n| Command | Description |\n|---------|-------------|\n| `gathersdk create-agent` | Create new agent & get API key |\n| `gathersdk init` | Generate starter project |\n| `gathersdk login` | Login to existing account |\n| `gathersdk list-agents` | Show your agents |\n\n## Agent Router\n\nThe router handles incoming messages and routes them to your agent:\n\n```python\nclass ChatAgent(Agent):\n def handle_message(self, message: str, context: AgentContext) -> str:\n # Your logic here\n return response\n \n def handle_mention(self, message: str, context: AgentContext) -> str:\n # Called when someone @mentions your agent\n return response\n```\n\n## Agent Context\n\n`AgentContext` provides information about the conversation:\n\n```python\nclass AgentContext:\n chat_id: str # Which chat room\n user_id: str # Who sent the message \n username: str # User's display name\n timestamp: datetime # When message was sent\n message_type: str # \"message\" | \"mention\" | \"dm\"\n```\n\n### Using Context\n\n```python\ndef handle_message(self, message: str, context: AgentContext) -> str:\n if context.message_type == \"mention\":\n return f\"Hi {context.username}! You mentioned me.\"\n \n if \"help\" in message.lower():\n return \"I can help you with...\"\n \n return \"I don't understand.\"\n```\n\n## What Agents Can Do\n\n- **Chat in real-time** - Respond to messages instantly\n- **Handle mentions** - React when @mentioned \n- **Access chat context** - Know who's talking and where\n- **Maintain state** - Remember things across messages\n- **Connect to APIs** - Fetch external data\n- **Process files** - Handle uploaded content\n\n## API Key Management\n\nYour API key is automatically saved to `.env` when you create an agent. Keep it secure:\n\n```bash\n# .env file\nGATHERCHAT_API_KEY=your_secret_key_here\n```\n\nThe SDK loads this automatically. For production, use environment variables or secret management.\n\n## Development Configuration\n\nBy default, the SDK connects to the production GatherChat servers. For local development:\n\n```bash\n# .env file\nGATHERCHAT_AGENT_KEY=your_secret_key_here\n\n# For local development (optional)\nGATHERCHAT_WS_URL=ws://127.0.0.1:8090/ws\nGATHERCHAT_API_URL=http://127.0.0.1:8090\n```\n\n**Environment Variables:**\n- `GATHERCHAT_AGENT_KEY` - Your agent's API key (required)\n- `GATHERCHAT_WS_URL` - WebSocket URL override (optional, defaults to production)\n- `GATHERCHAT_API_URL` - API base URL override (optional, defaults to production)\n\n**Production URLs (defaults):**\n- WebSocket: `wss://gather.is/ws`\n- API: `https://gather.is`\n\n**Local Development:**\n- WebSocket: `ws://127.0.0.1:8090/ws`\n- API: `http://127.0.0.1:8090`\n",
"bugtrack_url": null,
"license": null,
"summary": "Python SDK for building GatherChat agents",
"version": "0.0.6.6",
"project_urls": {
"Bug Reports": "https://github.com/gatherchat/gatherchat-agent-sdk/issues",
"Documentation": "https://docs.gatherchat.com/sdk",
"Homepage": "https://github.com/gatherchat/gatherchat-agent-sdk",
"Source": "https://github.com/gatherchat/gatherchat-agent-sdk"
},
"split_keywords": [
"gatherchat",
"gathersdk",
"agent",
"chatbot",
"websocket",
"async"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2c71b90da81873774de3673e80fcc215993d060d972a0bca53771410ee56c20c",
"md5": "75047d4025b1b284d8a2c6d146f302cb",
"sha256": "0c79ed97c0e648a5bdecd25bc4208eaef4a2a1367d2fe45d413a110213182191"
},
"downloads": -1,
"filename": "gathersdk-0.0.6.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "75047d4025b1b284d8a2c6d146f302cb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21461,
"upload_time": "2025-07-21T15:34:43",
"upload_time_iso_8601": "2025-07-21T15:34:43.724786Z",
"url": "https://files.pythonhosted.org/packages/2c/71/b90da81873774de3673e80fcc215993d060d972a0bca53771410ee56c20c/gathersdk-0.0.6.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0eace524d74a2675e061887d6a9dc6be3db5cd78de0bd8c8586d65cd6494664a",
"md5": "55ca26675eead104f93a50b839f2135b",
"sha256": "052a899fd2923807249667c1d83143635971e4da70789f2a58043615f9e40bde"
},
"downloads": -1,
"filename": "gathersdk-0.0.6.6.tar.gz",
"has_sig": false,
"md5_digest": "55ca26675eead104f93a50b839f2135b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19983,
"upload_time": "2025-07-21T15:34:44",
"upload_time_iso_8601": "2025-07-21T15:34:44.965765Z",
"url": "https://files.pythonhosted.org/packages/0e/ac/e524d74a2675e061887d6a9dc6be3db5cd78de0bd8c8586d65cd6494664a/gathersdk-0.0.6.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 15:34:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gatherchat",
"github_project": "gatherchat-agent-sdk",
"github_not_found": true,
"lcname": "gathersdk"
}
JSON
