SDK Reference

Installation

The SDK is a local package in the monorepo:

{
  "dependencies": {
    "@assistme/agent-app-sdk": "file:../packages/agent-app-sdk"
  }
}

Exports

import {
  // Registration
  registerMicroApp,
  getRegisteredApp,
  isAppRegistered,
  getAllRegisteredApps,
  unregisterMicroApp,

  // React Context & Hooks
  MicroAppContext,
  useMicroApp,
  useBridge,
  useHostContext,
  useIsRunningInHost,

  // Bridge utilities
  createNoopBridge,
  validateBridge,
} from "@assistme/agent-app-sdk";

Types

MicroApp

The main app record from the apps database table.

interface MicroApp {
  id: string;
  slug: string;
  name: string;
  description: string | null;
  long_description: string | null;
  icon_url: string | null;
  color: string;
  developer_id: string | null;
  category: AppCategory;
  status: MicroAppStatus;
  is_builtin: boolean;
  sort_order: number;
  required_permissions: MicroAppPermission[];
  tags: string[];
  install_count: number;
  average_rating: number;
  rating_count: number;
  // Agent configuration
  system_prompt: string | null;
  model: string;
  temperature: number;
  max_tokens: number;
  tools: AgentTool[];
  welcome_message: string | null;
  suggested_prompts: string[];
  memory_enabled: boolean;
  max_context_messages: number;
  created_at: string;
  updated_at: string;
}

MicroAppVersion

A specific version of an Agent App.

interface MicroAppVersion {
  id: string;
  app_id: string;
  version: string;
  bundle_url: string | null;
  bundle_hash: string | null;
  bundle_size: number | null;
  min_host_version: string;
  status: VersionStatus;
  changelog: string | null;
  reviewed_by: string | null;
  reviewed_at: string | null;
  review_notes: string | null;
  entry_component: string;
  created_at: string;
  updated_at: string;
}

UserInstalledApp

A record of a user's installed app.

interface UserInstalledApp {
  id: string;
  user_id: string;
  app_id: string;
  installed_version_id: string | null;
  position: number;
  is_pinned: boolean;
  last_opened_at: string | null;
  preferences: Record<string, unknown>;
  installed_at: string;
  updated_at: string;
  app_info?: MicroApp; // Joined data
}

MicroAppRegistration

The object passed to registerMicroApp() to register a static app.

interface MicroAppRegistration {
  slug: string;
  name: string;
  component: ComponentType<MicroAppProps>;
  permissions?: MicroAppPermission[];
  onMount?: () => void | Promise<void>;
  onUnmount?: () => void;
}

MicroAppProps

Props injected into every Agent App's root component.

interface MicroAppProps {
  bridge: MicroAppBridge;
  hostContext: MicroAppHostContext;
}

MicroAppManifest

Bundle metadata for dynamic loading.

interface MicroAppManifest {
  slug: string;
  name: string;
  version: string;
  bundleUrl?: string;
  bundleHash?: string;
  entryComponent: string;
  loadingStrategy: LoadingStrategy;
  permissions: MicroAppPermission[];
}

Enums

type MicroAppStatus = "draft" | "in_review" | "published" | "suspended" | "archived";

type VersionStatus = "draft" | "in_review" | "approved" | "rejected" | "published" | "deprecated";

type AppCategory = "productivity" | "health" | "education" | "social"
                 | "finance" | "lifestyle" | "utility" | "entertainment";

type MicroAppPermission = "camera" | "location" | "notifications" | "contacts"
                        | "storage" | "microphone" | "haptics" | "biometrics";

type AgentTool = "web_search" | "code_exec" | "image_gen" | "file_read"
               | "calculator" | "calendar" | "reminders" | "knowledge_base";

type LoadingStrategy = "static" | "dynamic";

Registration API

`registerMicroApp(registration)`

Registers a static Agent App component in the global registry. Call this once at app startup (before navigation).

registerMicroApp({
  slug: "my-app",
  name: "My App",
  component: MyAppComponent,
  permissions: ["notifications"],
});

`isAppRegistered(slug): boolean`

Check if an app is registered in the static registry.

`getRegisteredApp(slug): MicroAppRegistration | undefined`

Get the registration object for a static app.

`getAllRegisteredApps(): MicroAppRegistration[]`

Get all registered static apps.

`unregisterMicroApp(slug): void`

Remove a static app from the registry.

React Hooks

`useMicroApp()`

Access the bridge and host context from any component inside an Agent App:

import { useMicroApp } from "@assistme/agent-app-sdk";

function MyComponent() {
  const { bridge, hostContext, isRunningInHost } = useMicroApp();

  // isRunningInHost: true when rendered inside the host app
  // false when running standalone
}

`useBridge()`

Shortcut to get just the bridge:

import { useBridge } from "@assistme/agent-app-sdk";

function MyComponent() {
  const bridge = useBridge();
  bridge.showToast("Hello!");
}

`useHostContext()`

Shortcut to get just the host context:

import { useHostContext } from "@assistme/agent-app-sdk";

function MyComponent() {
  const hostContext = useHostContext(); // may be null
  if (!hostContext) return null;
  const { userId, colorScheme } = hostContext;
}

`useIsRunningInHost()`

Check if the app is running inside the host:

import { useIsRunningInHost } from "@assistme/agent-app-sdk";

function MyComponent() {
  const isInHost = useIsRunningInHost();
  if (!isInHost) return <Text>Open this app in AssistMe</Text>;
}

Bridge Utilities

`createNoopBridge(): MicroAppBridge`

Returns a safe no-op bridge for standalone development. All methods are implemented but do nothing:

import { createNoopBridge } from "@assistme/agent-app-sdk";

// Useful for running your app outside the host during development
const bridge = createNoopBridge();

`validateBridge(bridge): boolean`

Runtime check that all required bridge methods are present:

import { validateBridge } from "@assistme/agent-app-sdk";

if (validateBridge(bridge)) {
  // All bridge methods are available
}

On this page