RapidStack

RapidStack is the agent orchestration platform for ShellApps. It manages the lifecycle of Norman agents — from spawning and task assignment to execution and teardown.

What RapidStack Does

Agent orchestration — Spawn, manage, and terminate agent instances
Task queuing — Queue tasks and route them to the right agent
Workflow management — Chain agents together for complex multi-step workflows
Resource management — Allocate compute, manage concurrency, handle timeouts

Architecture

                    ┌────────────────┐
User Request ─────▶│   RapidStack   │
                    │                │
                    │  Task Queue    │
                    │  ┌──────────┐  │     ┌───────────┐
                    │  │ Task A   │──┼────▶│  Agent 1  │──▶ Toolshed
                    │  │ Task B   │──┼────▶│  Agent 2  │──▶ Toolshed
                    │  │ Task C   │  │     └───────────┘
                    │  └──────────┘  │
                    └────────────────┘

A request comes in (from Experience, API, or another agent)
RapidStack creates a task and queues it
An agent is spawned or reused to handle the task
The agent uses Toolshed to execute tools
Results flow back through RapidStack

Key Concepts

Agents

Agents are stateless workers that execute tasks. Each agent has a defined capability set and can access tools via Toolshed.

interface Agent {
  id: string;
  type: string;           // Agent template/type
  status: 'idle' | 'running' | 'completed' | 'failed';
  taskId?: string;
  tools: string[];        // Toolshed tool IDs this agent can use
  createdAt: string;
  ttl: number;            // Time-to-live in seconds
}

Tasks

Tasks are units of work assigned to agents.

interface Task {
  id: string;
  type: string;
  status: 'queued' | 'running' | 'completed' | 'failed';
  agentId?: string;
  input: Record<string, unknown>;
  output?: Record<string, unknown>;
  priority: number;
  createdAt: string;
}

Workflows

Workflows chain multiple tasks together with conditional logic:

const workflow = {
  name: 'deploy-and-notify',
  steps: [
    { task: 'run-tests', tools: ['e2e.run-suite'] },
    { task: 'deploy', tools: ['github.create-release'], dependsOn: ['run-tests'] },
    { task: 'notify', tools: ['slack.send-message'], dependsOn: ['deploy'] },
  ],
};

Quick Example

import { RapidStack } from '@shellapps/rapidstack-client';
 
const rapid = new RapidStack({ token: authToken });
 
// Create and queue a task
const task = await rapid.createTask({
  type: 'code-review',
  input: { prUrl: 'https://github.com/shellapps/experience/pull/42' },
  tools: ['github.read-pr', 'github.create-review'],
});
 
// Wait for completion
const result = await rapid.waitForTask(task.id);
console.log(result.output);

API Reference — Full endpoint documentation
Toolshed — Tool registry used by agents
Auth — Agent authentication and permissions
E2E Testing — Test workflows orchestrated by RapidStack

API Reference API Reference