@journeyrewards/hive-admin-sdk

Admin SDK for the Journey Hive Agent Orchestration API. Provides programmatic access to agent lifecycle management, skill provisioning, and platform settings.

Installation

npm install @journeyrewards/hive-admin-sdk

Quick Start

import { JourneyHiveAdminClient } from "@journeyrewards/hive-admin-sdk";

const client = new JourneyHiveAdminClient({
  apiKey: "jh_your_admin_api_key",
  // baseUrl: "https://your-instance.replit.app", // optional
});

API Key Permissions

Your API key must include the appropriate admin scopes:

| Scope | Description | |---|---| | admin:agents:create | Create new agents | | admin:agents:delete | Delete agents | | admin:agents:manage | Provision sandbox, wake/sleep agents | | admin:skills:read | List available skills and agent skills | | admin:skills:manage | Install, uninstall, configure, redeploy skills | | admin:settings:read | Read platform settings | | admin:settings:write | Update platform settings |

Use * (wildcard) to grant all permissions including admin scopes.

Usage

Agent Management

// Create a specialist agent
const agent = await client.agents.create({
  name: "Concierge Bot",
  slug: "concierge-bot",
  type: "specialist",
  soul_template: "hospitality-concierge",
  personality_notes: "Friendly and helpful hotel concierge",
  lifecycle_mode: "wake_on_demand",
  external_access: "api_enabled",
  metadata: { property: "grand-hotel" },
});

console.log(agent.id); // "abc123"
console.log(agent.status); // "idle"

// Create a member agent (personal loyalty concierge)
const memberAgent = await client.agents.create({
  name: "Member Agent — AJKDBC",
  slug: "member-ajkdbc",
  type: "member",
  member_id: "AJKDBC",                          // loyalty program ID
  clerk_user_id: "user_2nFZBKVLH3kMd9i...",     // Clerk auth ID
  personal_name: "Helga",                        // name the member chose
  personality_notes: "Warm, personal, proactive about rewards",
});

console.log(memberAgent.personal_name); // "Helga"
console.log(memberAgent.member_id);     // "AJKDBC"

// Provision a sandbox for the agent
const provisioned = await client.agents.provision(agent.id);
console.log(provisioned.sandbox_id); // "sandbox_xyz"

// Wake a sleeping agent
const awake = await client.agents.wake(agent.id);
console.log(awake.status); // "running"

// Put an agent to sleep
const sleeping = await client.agents.sleep(agent.id);
console.log(sleeping.status); // "sleeping"

// Delete an agent (also destroys its sandbox)
const deleted = await client.agents.delete(agent.id);
console.log(deleted.deleted); // true

Skill Management

// List all available skills
const skills = await client.skills.list();
console.log(skills.data); // [{ id: "...", name: "google-sheets", ... }]

// List skills installed on an agent
const agentSkills = await client.agents.listSkills(agentId);

// Install a skill on an agent
const installed = await client.agents.installSkill(agentId, {
  skill_id: "skill_abc",
  config: { SPREADSHEET_ID: "1234..." },
});

// Update skill configuration (env vars)
await client.agents.updateSkillConfig(agentId, skillId, {
  config: { SPREADSHEET_ID: "5678..." },
});

// Redeploy a skill to the agent's sandbox
await client.agents.redeploySkill(agentId, skillId);

// Uninstall a skill
await client.agents.uninstallSkill(agentId, skillId);

Platform Settings

// List all settings
const settings = await client.settings.list();

// Get a specific setting
const setting = await client.settings.get("default_model");
console.log(setting.value); // "anthropic/claude-opus-4-6"

// Update a setting
const updated = await client.settings.set("default_model", {
  value: "anthropic/claude-sonnet-4-20250514",
  description: "Default LLM model for new agents",
});

Error Handling

import {
  JourneyHiveAdminClient,
  JourneyHiveError,
  AuthenticationError,
  PermissionError,
  NotFoundError,
} from "@journeyrewards/hive-admin-sdk";

try {
  await client.agents.create({ name: "Test", slug: "test", type: "specialist" });
} catch (err) {
  if (err instanceof PermissionError) {
    console.error("Missing admin:agents:create permission");
  } else if (err instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (err instanceof NotFoundError) {
    console.error("Resource not found");
  } else if (err instanceof JourneyHiveError) {
    console.error(`API error ${err.status}: ${err.message} (${err.code})`);
  }
}

Debug Mode

Enable debug logging to see all HTTP requests and responses:

const client = new JourneyHiveAdminClient({
  apiKey: "jh_your_key",
  debug: true,
});

Configuration

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | required | API key with admin scopes | | baseUrl | string | https://journey-hive.replit.app | API base URL | | timeout | number | 30000 | Request timeout in ms | | debug | boolean | false | Enable debug logging |

Agent Types

The type field determines the agent's role and which additional fields are relevant:

| Type | Purpose | Key Fields | |---|---|---| | controller | Primary routing and orchestration | — | | organization | Organization-specific concierge | organization_id, hxp_org_id | | specialist | Specialized task handler | — | | security | Security monitoring | — | | auth | Authentication gateway | — | | member | Personal loyalty concierge for one traveler | member_id, clerk_user_id, personal_name |

Member Agent Fields

When creating a member agent, pass these fields so the platform can scope data and route sessions correctly:

• member_id — The traveler's loyalty program ID (e.g. "AJKDBC"). Used for BigQuery row-level security and data scoping.
• clerk_user_id — The Clerk authentication user ID (e.g. "user_abc123..."). Used to bind authenticated sessions to this agent.
• personal_name (optional) — A name the member chose for their agent (e.g. "Helga"). When set, the agent's SOUL.md and IDENTITY.md are generated with instructions to introduce itself by this name.

License

MIT