🧙 Agent Setup Wizard#

The interactive setup wizard makes it easy to configure new agents for the Jetstream-Letta bridge system. It guides you through all the required configuration steps and validates your settings.

Quick Start#

Option 1: Using the helper script (Recommended)#

./run_agent.sh setup

Option 2: Using the bridge directly#

python src/jetstream_letta_bridge.py --setup

Option 3: Using the standalone script#

python setup_agent.py

What the Wizard Does#

🤖 Agent Information#

Prompts for agent name and description
Lets you choose from pre-configured templates:
- Technical: Quick responses (batch_size: 1, max_steps: 100)
- Creative: Contextual responses (batch_size: 3, max_steps: 150)
- Analytical: Deep analysis (batch_size: 5, max_steps: 200)
- Custom: Configure your own settings

🦋 Bluesky Configuration#

Collects your Bluesky handle/email
Prompts for app password (with security reminder)
Configures PDS URI (defaults to https://bsky.social)
Tests authentication to verify credentials work

🧠 Letta Configuration#

Collects your Letta API key
Automatically fetches and displays your agents from Letta
Shows a table with agent details (ID, name, model, tools)
Lets you select which agent to use
Configures timeout settings

🌊 Jetstream Monitoring#

Configures jetstream instance (defaults to official endpoint)
Optionally lets you specify DIDs to monitor
Sets up reconnection settings

💾 File Generation#

Generates a complete YAML configuration file
Saves to agents/ directory with descriptive filename
Shows usage instructions for your new agent

Prerequisites#

Before running the setup wizard, make sure you have:

1. Bluesky Account Setup#

Create a Bluesky account at https://bsky.app
Go to Settings → App Passwords
Generate a new app password
Important: Use the app password, not your main account password!

2. Letta Agent Setup#

Create a Letta account and get your API key
Create at least one agent in your Letta dashboard
Note your agent ID (the wizard can fetch this automatically)

3. Python Dependencies#

Install required packages:

pip install click rich pyyaml requests

Usage Examples#

Complete Setup Flow#

$ ./run_agent.sh setup

🤖 Jetstream-Letta Bridge Setup Wizard

This wizard will help you configure a new agent...
Ready to set up your agent? [Y/n]: y

📝 Agent Information
Agent name: TechSupport
Select agent template:
  1. Technical - Quick responses for technical discussions
  2. Creative - Contextual responses for creative content  
  3. Analytical - Deep analysis with larger batches
  4. Custom - Configure your own settings
[1]: 1

🦋 Bluesky Configuration
Bluesky handle: support.mycompany.bsky.social
App password: [hidden]
Test Bluesky connection now? [Y/n]: y
✅ Bluesky authentication successful!

🧠 Letta Configuration
Letta API key: [hidden]
✅ Found 3 agents in your Letta account:
┌─────┬──────────────────────┬─────────────┬────────┬────────────┐
│  #  │      Agent ID        │    Name     │ Model  │   Tools    │
├─────┼──────────────────────┼─────────────┼────────┼────────────┤
│  1  │ agent-tech-uuid-123  │ TechBot     │ gpt-4  │ send_msg..│
│  2  │ agent-create-uuid-45 │ CreativeAI  │ gpt-4  │ send_msg..│
│  3  │ agent-analyze-uuid-78│ DataBot     │ gpt-4  │ send_msg..│
└─────┴──────────────────────┴─────────────┴────────┴────────────┘
Select agent (1-3): 1

🌊 Jetstream Configuration
Monitor specific DIDs only? [y/N]: n

💾 Saving Configuration
Configuration filename [techsupport.yaml]: 
✅ Configuration saved to: agents/techsupport.yaml

🎉 Setup Complete!
Your agent is ready to use!

Start your agent:
  ./run_agent.sh techsupport

Testing Your Configuration#

After setup, test your agent:

# Start with verbose output to see what's happening
./run_agent.sh techsupport --verbose

# Or test the configuration file directly
python src/jetstream_letta_bridge.py --agent agents/techsupport.yaml --verbose

Troubleshooting#

Authentication Issues#

Bluesky: Make sure you're using an app password, not your main password
Letta: Verify your API key is correct and has proper permissions
Test connections: The wizard will test connections and show specific error messages

Agent Issues#

Agent not found: Make sure the agent ID exists in your Letta account
Permission errors: Ensure your API key has access to the specified agent

Configuration Issues#

File not saved: Check that you have write permissions to the agents/ directory
Invalid YAML: The wizard generates valid YAML, but manual edits might break formatting

Runtime Issues#

# List available agents to verify your config was created
./run_agent.sh list

# Check the generated configuration file
cat agents/your-agent.yaml

# Test with minimal monitoring (no DIDs specified)
python src/jetstream_letta_bridge.py --agent agents/your-agent.yaml --wanted-dids ""

Advanced Configuration#

The wizard creates a complete configuration file, but you can manually edit it afterwards for advanced settings:

# Edit agents/your-agent.yaml
agent:
  batch_size: 3        # Adjust batch processing
  max_steps: 150       # Increase for complex tasks

jetstream:
  wanted_dids:         # Add specific communities to monitor
    - "did:plc:community1"  
    - "did:plc:community2"

letta:
  timeout: 900         # Increase timeout for slow responses

Next Steps#

After setting up your agent:

Test it: Run with --verbose to see activity
Monitor specific communities: Add DIDs to wanted_dids
Adjust batch size: Based on your agent's response patterns
Create more agents: Run the wizard again for different specializations
Schedule agents: Use cron or similar to run different agents at different times

Getting Help#

Run ./run_agent.sh help for usage options
Check the main README.md for system overview
Look at example configurations in agents/ directory
Use --verbose flag to see detailed activity logs