Pitfalls of Session Management in Multi-AI-Agent Systems

Introduction Running multiple AI agents through a single gateway is a powerful approach. However, session management comes with surprising pitfalls. Problem 1: Session Path Validation Error Sending messages to any agent produced: handler failed: Error: Session file path must be within sessions directory Debug logging revealed the root cause: session files were created under the correct agent directory, but path validation fell back to the default agent during reads. Fix if ( path . isAbsolute ( trimmed )) { const m = trimmed . match ( /^ ( .* \/ agents \/[^\/] + \/ sessions )\/ / ); if ( m ) effectiveBase = m [ 1 ]; } Problem 2: Auth Profile Format After fixing the path issue, auth errors appeared. The per-agent auth profiles needed version, type, and lastGood fields. Lessons Problems stack - fix one layer to reveal the next Print variable values instead of guessing Transfer patch scripts via SCP instead of inline SSH