hhopkins95/ai-systems

Overview

This skill explains the purpose, value proposition, and high-level architecture of the Agent Runtime monorepo. It describes how the runtime launches and manages AI agent sessions in isolated sandboxes and how the React client library integrates with the backend for real-time streaming and session lifecycle management. The focus is on practical outcomes: isolation, streaming, session management, and multi-architecture support.

How this skill works

The runtime exposes a REST API and WebSocket endpoint. Clients create sessions via REST, join a WebSocket room, and send the first message which lazily provisions a Modal sandbox to run an agent (Claude SDK or OpenCode). The backend SessionManager tracks sandbox lifecycle, parses agent output into typed blocks, syncs state to a PersistenceAdapter, and streams block events to clients in real time.

When to use it

• Building apps that must run arbitrary agent workloads in isolated environments
• Needing real-time, incremental streaming of agent output to clients
• Multi-tenant systems where resource and security isolation per session is required
• Implementing React frontends that manage session lifecycle and display streaming transcripts
• Coordinating agents that use tools, subagents, or custom skills

Best practices

• Implement a PersistenceAdapter to persist sessions, transcripts, and workspace files outside the runtime
• Use lazy sandbox creation to minimize resource usage until a session receives its first message
• Rely on block-typed output for deterministic rendering (UserMessageBlock, AssistantTextBlock, ToolResultBlock, etc.)
• Configure AGENT_ARCHITECTURE_TYPE per session to choose Claude SDK or OpenCode as needed
• Enforce workspace file and tool permissions inside the sandbox to maintain security boundaries

Example use cases

• Chat UI that streams agent reasoning and tool outputs block-by-block to users
• Automation platform that spawns short-lived agents to run code, grep files, or orchestrate tasks safely
• Multi-tenant IDE assistant that isolates each developer’s agent in its own sandbox
• Workflow system that delegates tasks to subagents and collects structured transcripts for auditing