ajarbot/MIGRATION_GUIDE_AGENT_SDK.md

Migration Guide: Agent SDK Implementation

Quick Start (TL;DR)

For New Users

# 1. Install dependencies
pip install -r requirements.txt

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

For Existing Users

# 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:

cat .env

Scenario A: Using Direct API (Pay-per-token)

ANTHROPIC_API_KEY=sk-ant-...
# No USE_CLAUDE_CODE_SERVER variable, or it's set to false

Scenario B: Using Legacy Claude Code Server

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:

   pip install -r requirements.txt
   

2. Update .env (optional - SDK is default):

   # 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:

   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:

   pip install -r requirements.txt
   

2. Update .env:

   USE_DIRECT_API=true
   ANTHROPIC_API_KEY=sk-ant-...
   

3. Run the bot:

   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:

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:

pip install claude-agent-sdk

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

Cause: Package not in requirements.txt or not installed

Solution:

# 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:

# 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:

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:

   print(f"SDK Response: {sdk_response}")
   

Rollback Plan

If you need to rollback to the old system:

Rollback to Direct API

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

Rollback to Legacy Server

# 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)

# 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