Jordan Ramos
a8665d8c72
This commit removes deprecated modules and reorganizes code into logical directories: Deleted files (superseded by newer systems): - claude_code_server.py (replaced by agent-sdk direct integration) - heartbeat.py (superseded by scheduled_tasks.py) - pulse_brain.py (unused in production) - config/pulse_brain_config.py (obsolete config) Created directory structure: - examples/ (7 example files: example_*.py, demo_*.py) - tests/ (5 test files: test_*.py) Updated imports: - agent.py: Removed heartbeat module and all enable_heartbeat logic - bot_runner.py: Removed heartbeat parameter from Agent initialization - llm_interface.py: Updated deprecated claude_code_server message Preserved essential files: - hooks.py (for future use) - adapters/skill_integration.py (for future use) - All Google integration tools (Gmail, Calendar, Contacts) - GLM provider code (backward compatibility) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
257 lines
5.6 KiB
Markdown
257 lines
5.6 KiB
Markdown
# Claude Agent SDK Setup
|
|
|
|
Use your **Claude Pro subscription** OR **API key** with ajarbot - no separate server needed.
|
|
|
|
## What is the Agent SDK?
|
|
|
|
The Claude Agent SDK lets you use Claude directly from Python using either:
|
|
- **Your Pro subscription** (unlimited usage within Pro limits)
|
|
- **Your API key** (pay-per-token)
|
|
|
|
The SDK automatically handles authentication and runs Claude in-process - no FastAPI server required.
|
|
|
|
## Quick Start
|
|
|
|
### 1. Install Dependencies
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
This installs `claude-agent-sdk` along with all other dependencies.
|
|
|
|
### 2. Choose Your Mode
|
|
|
|
Set `AJARBOT_LLM_MODE` in your `.env` file (or leave it unset for default):
|
|
|
|
```bash
|
|
# Use Claude Pro subscription (default - recommended for personal use)
|
|
AJARBOT_LLM_MODE=agent-sdk
|
|
|
|
# OR use pay-per-token API
|
|
AJARBOT_LLM_MODE=api
|
|
ANTHROPIC_API_KEY=sk-ant-...
|
|
```
|
|
|
|
### 3. Authenticate (Agent SDK mode only)
|
|
|
|
If using `agent-sdk` mode, authenticate with Claude CLI:
|
|
|
|
```bash
|
|
# Install Claude CLI (if not already installed)
|
|
# Download from: https://claude.ai/download
|
|
|
|
# Login with your Claude account
|
|
claude auth login
|
|
```
|
|
|
|
This opens a browser window to authenticate with your claude.ai account.
|
|
|
|
### 4. Run Your Bot
|
|
|
|
**Windows:**
|
|
```bash
|
|
run.bat
|
|
```
|
|
|
|
**Linux/Mac:**
|
|
```bash
|
|
python ajarbot.py
|
|
```
|
|
|
|
That's it! No separate server to manage.
|
|
|
|
## Architecture Comparison
|
|
|
|
### Old Setup (Deprecated)
|
|
```
|
|
Telegram/Slack → ajarbot → FastAPI Server (localhost:8000) → Claude Code SDK → Claude
|
|
```
|
|
|
|
### New Setup (Current)
|
|
```
|
|
Telegram/Slack → ajarbot → Claude Agent SDK → Claude (Pro OR API)
|
|
```
|
|
|
|
The new setup eliminates the FastAPI server, reducing complexity and removing an extra process.
|
|
|
|
## Mode Details
|
|
|
|
### Agent SDK Mode (Default)
|
|
|
|
**Pros:**
|
|
- Uses Pro subscription (unlimited within Pro limits)
|
|
- No API key needed
|
|
- Higher context window (200K tokens)
|
|
- Simple authentication via Claude CLI
|
|
|
|
**Cons:**
|
|
- Requires Node.js and Claude CLI installed
|
|
- Subject to Pro subscription rate limits
|
|
- Not suitable for multi-user production
|
|
|
|
**Setup:**
|
|
```bash
|
|
# .env file
|
|
AJARBOT_LLM_MODE=agent-sdk
|
|
|
|
# Authenticate once
|
|
claude auth login
|
|
```
|
|
|
|
### API Mode
|
|
|
|
**Pros:**
|
|
- No CLI authentication needed
|
|
- Predictable pay-per-token pricing
|
|
- Works in any environment (no Node.js required)
|
|
- Better for production/multi-user scenarios
|
|
|
|
**Cons:**
|
|
- Costs money per API call
|
|
- Requires managing API keys
|
|
|
|
**Setup:**
|
|
```bash
|
|
# .env file
|
|
AJARBOT_LLM_MODE=api
|
|
ANTHROPIC_API_KEY=sk-ant-...
|
|
```
|
|
|
|
## Cost Comparison
|
|
|
|
| Mode | Cost Model | Best For |
|
|
|------|-----------|----------|
|
|
| **Agent SDK (Pro)** | $20/month flat rate | Heavy personal usage |
|
|
| **API (pay-per-token)** | ~$0.25-$3 per 1M tokens | Light usage, production |
|
|
|
|
With default Haiku model, API mode costs approximately:
|
|
- ~$0.04/day for moderate personal use (1000 messages/month)
|
|
- ~$1.20/month for light usage
|
|
|
|
## Pre-Flight Checks
|
|
|
|
The `ajarbot.py` launcher runs automatic checks before starting:
|
|
|
|
**Agent SDK mode checks:**
|
|
- Python 3.10+
|
|
- Node.js available
|
|
- Claude CLI authenticated
|
|
- Config file exists
|
|
|
|
**API mode checks:**
|
|
- Python 3.10+
|
|
- `.env` file exists
|
|
- `ANTHROPIC_API_KEY` is set
|
|
- Config file exists
|
|
|
|
Run health check manually:
|
|
```bash
|
|
python ajarbot.py --health
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Node.js not found"
|
|
Agent SDK mode requires Node.js. Either:
|
|
1. Install Node.js from https://nodejs.org
|
|
2. Switch to API mode (set `AJARBOT_LLM_MODE=api`)
|
|
|
|
### "Claude CLI not authenticated"
|
|
```bash
|
|
# Check authentication status
|
|
claude auth status
|
|
|
|
# Re-authenticate
|
|
claude auth logout
|
|
claude auth login
|
|
```
|
|
|
|
### "Agent SDK not available"
|
|
```bash
|
|
pip install claude-agent-sdk
|
|
```
|
|
|
|
If installation fails, switch to API mode.
|
|
|
|
### Rate Limits (Agent SDK mode)
|
|
|
|
If you hit Pro subscription limits:
|
|
- Wait for limit refresh (usually 24 hours)
|
|
- Switch to API mode temporarily:
|
|
```bash
|
|
# In .env
|
|
AJARBOT_LLM_MODE=api
|
|
ANTHROPIC_API_KEY=sk-ant-...
|
|
```
|
|
|
|
### "ANTHROPIC_API_KEY not set" (API mode)
|
|
|
|
Create a `.env` file in the project root:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env and add your API key
|
|
```
|
|
|
|
Get your API key from: https://console.anthropic.com/settings/keys
|
|
|
|
## Migration from Old Setup
|
|
|
|
If you previously used the FastAPI server (`claude_code_server.py`):
|
|
|
|
1. **Remove old environment variables:**
|
|
```bash
|
|
# Delete these from .env
|
|
USE_CLAUDE_CODE_SERVER=true
|
|
CLAUDE_CODE_SERVER_URL=http://localhost:8000
|
|
```
|
|
|
|
2. **Set new mode:**
|
|
```bash
|
|
# Add to .env
|
|
AJARBOT_LLM_MODE=agent-sdk # or "api"
|
|
```
|
|
|
|
3. **Stop the old server** (no longer needed):
|
|
- The `claude_code_server.py` process can be stopped
|
|
- It's no longer used
|
|
|
|
4. **Run with new launcher:**
|
|
```bash
|
|
run.bat # Windows
|
|
python ajarbot.py # Linux/Mac
|
|
```
|
|
|
|
See [MIGRATION.md](MIGRATION.md) for detailed migration guide.
|
|
|
|
## Features
|
|
|
|
All ajarbot features work in both modes:
|
|
- 15 tools (file ops, system commands, Gmail, Calendar, Contacts)
|
|
- Multi-platform adapters (Slack, Telegram)
|
|
- Memory system with hybrid search
|
|
- Task scheduling
|
|
- Google integration (Gmail, Calendar, Contacts)
|
|
- Usage tracking (API mode only)
|
|
|
|
## Security
|
|
|
|
**Agent SDK mode:**
|
|
- Uses your Claude.ai authentication
|
|
- No API keys to manage
|
|
- Credentials stored by Claude CLI (secure)
|
|
- Runs entirely on localhost
|
|
|
|
**API mode:**
|
|
- API key in `.env` file (gitignored)
|
|
- Environment variable isolation
|
|
- No data leaves your machine except to Claude's API
|
|
|
|
Both modes are suitable for personal bots. API mode is recommended for production/multi-user scenarios.
|
|
|
|
## Sources
|
|
|
|
- [Claude Agent SDK GitHub](https://github.com/anthropics/anthropic-sdk-python)
|
|
- [Claude CLI Download](https://claude.ai/download)
|
|
- [Anthropic API Documentation](https://docs.anthropic.com/)
|