Swisper + SwisperStudio Configuration Overview¶
Visual Reference for Configuration
Architecture Diagram¶
┌─────────────────────────────────────────────────────────────────┐
│ Same Data Center / Host │
│ │
│ ┌──────────────────────────┐ ┌───────────────────────┐ │
│ │ Swisper Backend │ │ SwisperStudio Backend│ │
│ │ │ │ │ │
│ │ Config: │ │ Config: │ │
│ │ ┌────────────────────┐ │ │ ┌─────────────────┐ │ │
│ │ │ SWISPER_STUDIO_ │ │ │ │ OBSERVABILITY_ │ │ │
│ │ │ REDIS_URL: │ │ │ │ REDIS_URL: │ │ │
│ │ │ redis://172.17. │ │ │ │ redis://redis: │ │ │
│ │ │ 0.1:6380 │ │ │ │ 6379 │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ PROJECT_ID: │ │ │ │ │ │ │
│ │ │ 0d7aa606-... │ │ │ │ │ │ │
│ │ └────────────────────┘ │ │ └─────────────────┘ │ │
│ │ │ │ │ │ │ │
│ │ │ SDK │ │ │ Consumer │ │
│ │ │ publishes │ │ │ reads │ │
│ │ ▼ │ │ ▼ │ │
│ └───────────┼──────────────┘ └─────────┼────────────┘ │
│ │ │ │
│ │ │ │
│ ┌───────────▼───────────────────────────────▼───────────┐ │
│ │ │ │
│ │ Redis (SwisperStudio's Observability Redis) │ │
│ │ Container: swisper_studio_redis │ │
│ │ Host Port: 6380 │ │
│ │ Container Port: 6379 │ │
│ │ │ │
│ │ Stream: observability:events │ │
│ │ MAXLEN: 100,000 events │ │
│ │ Memory: 512MB max │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Redis (Swisper's Operational Redis) │ │
│ │ Container: swisper_redis / helvetiq-redis │ │
│ │ Port: 6379 │ │
│ │ │ │
│ │ Data: Sessions, cache, queues │ │
│ │ Memory: 2GB+ (operational needs) │ │
│ │ Persistence: YES │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────┘
Configuration Matrix¶
| Component | Configuration Key | Value | Purpose |
|---|---|---|---|
| Swisper Backend | SWISPER_STUDIO_REDIS_URL |
redis://172.17.0.1:6380 |
Where to publish observability events |
| Swisper Backend | SWISPER_STUDIO_PROJECT_ID |
0d7aa606-... |
Which Studio project to send events to |
| Swisper Backend | SWISPER_STUDIO_ENABLED |
true |
Enable/disable observability |
| Studio Backend | OBSERVABILITY_REDIS_URL |
redis://redis:6379 |
Where to consume events from (own Redis) |
| Studio Backend | DATABASE_URL |
postgresql+asyncpg://... |
Where to store traces |
Connection Flow¶
┌─────────────────────────────────────────────────────────────┐
│ Step 1: Swisper Agent Execution │
│ │
│ User Request │
│ ↓ │
│ Agent Graph Execution (GlobalSupervisor, ResearchAgent...) │
│ ↓ │
│ SwisperStudio SDK Decorator Captures: │
│ • State transitions │
│ • Tool executions │
│ • LLM calls │
│ ↓ │
│ SDK publishes to Redis (fire-and-forget, <2ms) │
│ ↓ │
│ ✅ User Response (Swisper continues) │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Step 2: Event in Redis │
│ │
│ Redis Stream: observability:events │
│ Event: { │
│ event_type: "observation_start", │
│ trace_id: "abc123...", │
│ project_id: "0d7aa606...", │
│ data: { ... } │
│ } │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Step 3: SwisperStudio Consumer Processing │
│ │
│ Consumer polls Redis (XREADGROUP) │
│ ↓ │
│ Reads batch of events (100 at a time) │
│ ↓ │
│ Validates events │
│ ↓ │
│ Writes to PostgreSQL (traces, observations tables) │
│ ↓ │
│ Acknowledges events (XACK) │
│ ↓ │
│ Events removed from Redis │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Step 4: Viewing in SwisperStudio UI │
│ │
│ User opens: http://localhost:3000/projects/.../traces │
│ ↓ │
│ Studio Backend queries PostgreSQL │
│ ↓ │
│ Returns traces + observations │
│ ↓ │
│ UI renders: │
│ • Trace list │
│ • Timeline view │
│ • State graph │
│ • Tool executions │
│ • LLM prompts/responses │
└─────────────────────────────────────────────────────────────┘
Critical Configuration Values¶
Docker Host IP (Most Common)¶
# This is the Docker bridge gateway IP
# Allows containers to reach host-exposed ports
172.17.0.1
# Usage in Swisper config:
SWISPER_STUDIO_REDIS_URL=redis://172.17.0.1:6380
Why 6380? - SwisperStudio Redis runs in container on port 6379 - But exposed to host on port 6380 (to avoid conflict with Swisper's Redis) - From Swisper container: connect to host port 6380
Project ID (Unique per Environment)¶
# Development
SWISPER_STUDIO_PROJECT_ID=0d7aa606-cb29-4a31-8a59-50fa61151a32
# Staging (different project!)
SWISPER_STUDIO_PROJECT_ID=abc12345-6789-1234-5678-901234567890
# Production (different project!)
SWISPER_STUDIO_PROJECT_ID=def12345-6789-1234-5678-901234567890
Why different projects per environment? - Separate dev/staging/prod traces - Different retention policies - Different team access - Clearer debugging
Quick Setup Commands¶
1. Start SwisperStudio¶
cd /root/projects/swisper_studio
docker compose up -d
# Verify Redis is running
docker ps | grep swisper_studio_redis
# Should show:
# swisper_studio_redis redis:7.2-alpine Up 5 seconds 0.0.0.0:6380->6379/tcp
2. Configure Swisper¶
# Add to Swisper's .env file
cat >> /path/to/swisper/backend/.env << 'EOF'
# SwisperStudio Observability
SWISPER_STUDIO_ENABLED=true
SWISPER_STUDIO_REDIS_URL=redis://172.17.0.1:6380
SWISPER_STUDIO_PROJECT_ID=0d7aa606-cb29-4a31-8a59-50fa61151a32
EOF
3. Restart Swisper¶
cd /path/to/swisper
docker compose restart backend
# Check logs for confirmation
docker logs swisper-backend | grep SwisperStudio
# Should see:
# ✅ SwisperStudio observability initialized (Redis Streams)
# ✅ LLM prompt capture enabled
4. Test Connection¶
# From Swisper container, test Redis connection
docker exec swisper-backend redis-cli -h 172.17.0.1 -p 6380 ping
# Should return: PONG
5. Trigger Test Event¶
# Send a message through Swisper
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{"message": "Test observability"}'
# Check events appeared in Redis
docker exec swisper_studio_redis redis-cli XLEN observability:events
# Should show: 5 (or some number > 0)
6. View in Studio UI¶
# Open Studio UI
open http://localhost:3000
# Navigate to: Projects > Your Project > Traces
# Should see your test trace!
Troubleshooting Checklist¶
If events are not appearing:
# 1. Check SwisperStudio Redis is running
docker ps | grep swisper_studio_redis
# ✅ Should show running container
# 2. Check port is exposed
docker port swisper_studio_redis
# ✅ Should show: 6379/tcp -> 0.0.0.0:6380
# 3. Check Swisper can reach it
docker exec swisper-backend ping -c 1 172.17.0.1
# ✅ Should succeed
# 4. Check Redis responds
docker exec swisper-backend redis-cli -h 172.17.0.1 -p 6380 ping
# ✅ Should return: PONG
# 5. Check Swisper config loaded
docker exec swisper-backend python -c "from app.core.config import settings; print(settings.SWISPER_STUDIO_REDIS_URL)"
# ✅ Should show: redis://172.17.0.1:6380
# 6. Check events in Redis
docker exec swisper_studio_redis redis-cli XLEN observability:events
# ✅ Should show > 0 after triggering Swisper actions
# 7. Check Studio consumer is running
docker logs swisper_studio_backend | grep consumer
# ✅ Should show: "Observability consumer started"
# 8. Check consumer is processing
docker logs swisper_studio_backend | grep "Processing batch"
# ✅ Should show periodic "Processing batch of N events"
Summary¶
What Swisper needs:
1. ✅ Redis URL: redis://172.17.0.1:6380
2. ✅ Project ID: From Studio UI
3. ✅ SDK installed: pip install swisper-studio-sdk==0.5.0
That's it! Observability works automatically after configuration.
Last Updated: 2025-11-20