ajarbot/MIGRATION_GUIDE_AGENT_SDK.md

# Migration Guide: Agent SDK Implementation

## Quick Start (TL;DR)

### For New Users
```bash
# 1. Install dependencies
pip install -r requirements.txt

# 2. Run the bot (Agent SDK is the default)
python bot_runner.py
```

### For Existing Users
```bash
# 1. Update dependencies
pip install -r requirements.txt

# 2. That's it! The bot will automatically use Agent SDK
# Your existing .env settings are preserved
```

## Detailed Migration Steps

### Step 1: Understand Your Current Setup

Check your `.env` file:

```bash
cat .env
```

**Scenario A: Using Direct API (Pay-per-token)**
```env
ANTHROPIC_API_KEY=sk-ant-...
# No USE_CLAUDE_CODE_SERVER variable, or it's set to false
```

**Scenario B: Using Legacy Claude Code Server**
```env
USE_CLAUDE_CODE_SERVER=true
CLAUDE_CODE_SERVER_URL=http://localhost:8000
```

### Step 2: Choose Your Migration Path

#### Option 1: Migrate to Agent SDK (Recommended)

**Benefits:**
- Uses Claude Pro subscription (no per-token costs)
- Same speed as Direct API
- No separate server process required
- All features work identically

**Steps:**
1. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

2. Update `.env` (optional - SDK is default):
   ```env
   # Remove or comment out old settings
   # USE_CLAUDE_CODE_SERVER=false
   # CLAUDE_CODE_SERVER_URL=http://localhost:8000

   # Agent SDK is enabled by default, but you can be explicit:
   USE_AGENT_SDK=true

   # Keep your API key for fallback (optional)
   ANTHROPIC_API_KEY=sk-ant-...
   ```

3. Run the bot:
   ```bash
   python bot_runner.py
   ```

4. Verify Agent SDK is active:
   ```
   [LLM] Using Claude Agent SDK (Pro subscription)
   ```

#### Option 2: Keep Using Direct API

**When to use:**
- You don't have Claude Pro subscription
- You prefer pay-per-token billing
- You need to track exact API usage costs

**Steps:**
1. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

2. Update `.env`:
   ```env
   USE_DIRECT_API=true
   ANTHROPIC_API_KEY=sk-ant-...
   ```

3. Run the bot:
   ```bash
   python bot_runner.py
   ```

4. Verify Direct API is active:
   ```
   [LLM] Using Direct API (pay-per-token)
   ```

#### Option 3: Keep Using Legacy Server (Not Recommended)

**Only use if:**
- You have a custom modified `claude_code_server.py`
- You need the server for other tools/integrations

**Steps:**
1. Keep your current setup
2. The legacy server mode still works
3. No changes required

### Step 3: Test the Migration

Run the test suite:

```bash
python test_agent_sdk.py
```

Expected output:
```
=== Test 1: LLMInterface Initialization ===
✓ LLMInterface created successfully
  - Mode: agent_sdk
...
Total: 5/5 tests passed
🎉 All tests passed!
```

### Step 4: Verify Bot Functionality

Test all critical features:

1. **Simple Chat:**
   ```
   User: Hello!
   Bot: [Should respond normally]
   ```

2. **Tool Usage:**
   ```
   User: What files are in the current directory?
   Bot: [Should use list_directory tool]
   ```

3. **Gmail Integration:**
   ```
   User: Check my recent emails
   Bot: [Should use read_emails tool]
   ```

4. **Calendar Integration:**
   ```
   User: What's on my calendar today?
   Bot: [Should use read_calendar tool]
   ```

5. **Scheduled Tasks:**
   - Verify scheduled tasks still run
   - Check `config/scheduled_tasks.yaml`

## Environment Variables Reference

### New Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `USE_AGENT_SDK` | `true` | Enable Agent SDK mode (default) |
| `USE_DIRECT_API` | `false` | Force Direct API mode |

### Existing Variables (Still Supported)

| Variable | Default | Description |
|----------|---------|-------------|
| `ANTHROPIC_API_KEY` | - | API key for Direct API mode |
| `USE_CLAUDE_CODE_SERVER` | `false` | Enable legacy server mode |
| `CLAUDE_CODE_SERVER_URL` | `http://localhost:8000` | Legacy server URL |

### Priority Order

If multiple modes are enabled, the priority is:
1. `USE_DIRECT_API=true` → Direct API mode
2. `USE_CLAUDE_CODE_SERVER=true` → Legacy server mode
3. `USE_AGENT_SDK=true` (default) → Agent SDK mode
4. Agent SDK unavailable → Fallback to Direct API mode

## Troubleshooting

### Issue: "Agent SDK not available, falling back to Direct API"

**Cause:** `claude-agent-sdk` is not installed

**Solution:**
```bash
pip install claude-agent-sdk
```

### Issue: "ModuleNotFoundError: No module named 'claude_agent_sdk'"

**Cause:** Package not in requirements.txt or not installed

**Solution:**
```bash
# Verify requirements.txt has claude-agent-sdk
grep claude-agent-sdk requirements.txt

# If missing, update requirements.txt
pip install claude-agent-sdk anyio

# Or reinstall all dependencies
pip install -r requirements.txt
```

### Issue: Bot still using Direct API after migration

**Cause:** Explicit `USE_DIRECT_API=true` in `.env`

**Solution:**
```bash
# Edit .env and remove or change to false
USE_DIRECT_API=false

# Or comment out the line
# USE_DIRECT_API=true
```

### Issue: "anyio" import error

**Cause:** `anyio` package not installed (required for async/sync bridge)

**Solution:**
```bash
pip install anyio>=4.0.0
```

### Issue: Response format errors in agent.py

**Cause:** SDK response not properly converted to Message format

**Solution:**
1. Check `_convert_sdk_response_to_message()` implementation
2. Verify `TextBlock` and `ToolUseBlock` are imported
3. Run `python test_agent_sdk.py` to verify format compatibility

### Issue: Tool execution fails with Agent SDK

**Cause:** Agent SDK might not be returning expected tool format

**Solution:**
1. Check `_agent_sdk_chat_with_tools()` method
2. Verify tool definitions are passed correctly
3. Add debug logging:
   ```python
   print(f"SDK Response: {sdk_response}")
   ```

## Rollback Plan

If you need to rollback to the old system:

### Rollback to Direct API

```env
# In .env
USE_DIRECT_API=true
USE_AGENT_SDK=false
ANTHROPIC_API_KEY=sk-ant-...
```

### Rollback to Legacy Server

```env
# In .env
USE_CLAUDE_CODE_SERVER=true
CLAUDE_CODE_SERVER_URL=http://localhost:8000

# Start the server
python claude_code_server.py
```

### Rollback Code (if needed)

```bash
# Reinstall old dependencies (FastAPI/Uvicorn)
pip install fastapi>=0.109.0 uvicorn>=0.27.0

# Revert to old requirements.txt (backup needed)
git checkout HEAD~1 requirements.txt
pip install -r requirements.txt
```

## Frequently Asked Questions

### Q: Will this increase my costs?

**A:** If you have Claude Pro, **costs will decrease to $0** for LLM calls. If you don't have Pro, you can keep using Direct API mode.

### Q: Will this break my existing bot setup?

**A:** No. All functionality is preserved:
- All 17 tools work identically
- Scheduled tasks unchanged
- Adapters (Telegram, Slack) unchanged
- Memory system unchanged
- Self-healing system unchanged

### Q: Can I switch modes dynamically?

**A:** Not currently. You need to set the mode in `.env` and restart the bot.

### Q: Will usage tracking still work?

**A:** Usage tracking is disabled for Agent SDK mode (no costs to track). It still works for Direct API mode.

### Q: What about prompt caching?

**A:** Prompt caching currently works only in Direct API mode. Agent SDK support may be added in the future.

### Q: Can I use different modes for different bot instances?

**A:** Yes! Each bot instance reads `.env` independently. You can run multiple bots with different modes.

## Migration Checklist

Use this checklist to ensure a smooth migration:

### Pre-Migration
- [ ] Backup `.env` file
- [ ] Backup `requirements.txt`
- [ ] Note current mode (Direct API or Legacy Server)
- [ ] Verify bot is working correctly
- [ ] Document any custom configurations

### Migration
- [ ] Update `requirements.txt` (or `git pull` latest)
- [ ] Install new dependencies (`pip install -r requirements.txt`)
- [ ] Update `.env` with new variables (if needed)
- [ ] Remove old variables (if migrating from legacy server)

### Testing
- [ ] Run `python test_agent_sdk.py`
- [ ] Test simple chat
- [ ] Test tool usage (file operations)
- [ ] Test Gmail integration (if using)
- [ ] Test Calendar integration (if using)
- [ ] Test scheduled tasks
- [ ] Test with Telegram adapter (if using)
- [ ] Test with Slack adapter (if using)

### Post-Migration
- [ ] Verify mode in startup logs (`[LLM] Using Claude Agent SDK...`)
- [ ] Monitor for errors in first 24 hours
- [ ] Verify scheduled tasks still run
- [ ] Check memory system working correctly
- [ ] Document any issues or edge cases

### Cleanup (Optional)
- [ ] Remove unused legacy server code (if not needed)
- [ ] Remove `USE_CLAUDE_CODE_SERVER` from `.env`
- [ ] Uninstall FastAPI/Uvicorn (if not used elsewhere)
- [ ] Update documentation with new setup

## Support

If you encounter issues:

1. **Check logs:** Look for `[LLM]` and `[Agent]` prefixed messages
2. **Run tests:** `python test_agent_sdk.py`
3. **Check mode:** Verify startup message shows correct mode
4. **Verify dependencies:** `pip list | grep claude-agent-sdk`
5. **Check .env:** Ensure no conflicting variables

## Next Steps

After successful migration:

1. **Monitor performance:** Compare speed and response quality
2. **Track savings:** Calculate cost savings vs Direct API
3. **Report issues:** Document any bugs or edge cases
4. **Optimize:** Look for opportunities to leverage SDK features
5. **Share feedback:** Help improve the implementation

## Version History

### v1.0.0 (2026-02-15)
- Initial Agent SDK implementation
- Three-mode architecture
- Backward compatibility maintained
- Zero changes to agent.py, tools.py, adapters