@elqnt/agents

AI agent management for Eloquent platform - models, API, hooks, and utilities.

Installation

pnpm add @elqnt/agents

Quick Start

Provisioning Agents (Admin)

Use provisionAgentsApi to set up default agents for an organization:

import { provisionAgentsApi } from "@elqnt/agents/api";
import type { DefaultDefinitions } from "@elqnt/agents/models";

const definitions: DefaultDefinitions = {
  agents: [{
    orgId: "org-uuid",
    name: "support-agent",
    title: "Support Agent",
    description: "Customer support AI assistant",
    provider: "azure-openai",
    model: "gpt-5.4-mini",
    type: "chat",
    status: "active",
    systemPrompt: "You are a helpful support agent...",
    isDefault: true,
  }],
  toolDefinitions: [],
  subAgents: [],
  skills: [],
};

const result = await provisionAgentsApi([definitions], {
  baseUrl: "https://api.elqnt.ai",
  orgId: "org-uuid",
});

if (result.data?.success) {
  console.log(`Created ${result.data.agentsCreated} agents`);
}

Using Agents Hook

import { useAgents } from "@elqnt/agents/hooks";

function AgentList() {
  const { agents, loading, error, createAgent, updateAgent } = useAgents({
    baseUrl: config.apiGatewayUrl,
    orgId: config.orgId,
  });

  if (loading) return <Spinner />;
  if (error) return <Error message={error} />;

  return (
    <ul>
      {agents.map(agent => (
        <li key={agent.id}>{agent.title}</li>
      ))}
    </ul>
  );
}

Exports

/api - API Functions

import {
  // Agents
  listAgentsApi,
  getAgentApi,
  createAgentApi,
  updateAgentApi,
  deleteAgentApi,
  getDefaultAgentApi,

  // Skills
  listSkillsApi,
  getSkillApi,
  createSkillApi,
  updateSkillApi,
  deleteSkillApi,

  // Sub-agents
  listSubAgentsApi,
  getSubAgentApi,
  createSubAgentApi,

  // Tool Definitions
  listToolDefinitionsApi,
  getToolDefinitionApi,
  createToolDefinitionApi,

  // Widgets
  listWidgetsApi,
  createWidgetApi,
  updateWidgetApi,

  // Integrations (OAuth connections)
  listIntegrationsApi,
  getIntegrationApi,
  connectIntegrationApi,
  disconnectIntegrationApi,
  refreshIntegrationApi,
  updateIntegrationTriageApi,
  runEmailTriageApi,

  // Sandbox (AI-generated HTML)
  createSandboxApi,
  getSandboxApi,
  updateSandboxApi,
  listSandboxesApi,
  deleteSandboxApi,

  // Scheduler - Tasks
  listSchedulerTasksApi,
  createSchedulerTaskApi,
  getSchedulerTaskApi,
  updateSchedulerTaskApi,
  deleteSchedulerTaskApi,
  snoozeSchedulerTaskApi,
  completeSchedulerTaskApi,
  startSchedulerTaskApi,

  // Scheduler - Schedules
  listSchedulesApi,
  createScheduleApi,
  getScheduleApi,
  updateScheduleApi,
  deleteScheduleApi,
  pauseScheduleApi,
  resumeScheduleApi,
  runScheduleApi,

  // Provisioning
  provisionAgentsApi,
} from "@elqnt/agents/api";

/hooks - React Hooks

import { useAgents, useSkills, useIntegrations } from "@elqnt/agents/hooks";

// Agent management
const { listAgents, getAgent, createAgent, updateAgent, deleteAgent, getDefaultAgent, loading, error } = useAgents(options);

// Skill management
const { listSkills, getSkill, createSkill, updateSkill, deleteSkill, getCategories, loading, error } = useSkills(options);

// OAuth integrations (Google, Microsoft)
const { listIntegrations, getIntegration, connectIntegration, disconnectIntegration, refreshIntegration, updateTriage, runEmailTriage, loading, error } = useIntegrations(options);

Available hooks: | Hook | Description | |------|-------------| | useAgents | Agent CRUD operations | | useSkills | Skill CRUD operations | | useSubAgents | Sub-agent CRUD operations | | useToolDefinitions | Tool definition CRUD operations | | useAgentJobs | Agent job management (pause/resume) | | useWidgets | Chat widget CRUD operations | | useSkillUserConfig | Per-user skill configuration | | useAnalytics | Agent analytics (chats, CSAT, task outcomes) | | useIntegrations | OAuth integration management (Google, Microsoft) | | useSandbox | AI-generated HTML sandbox management | | useSchedulerTasks | Scheduler task operations (create, snooze, complete) | | useSchedulerSchedules | Recurring schedule operations (pause, resume, run) |

/models - TypeScript Types

Types generated from Go via tygo.

import type {
  Agent,
  AgentSummary,
  Skill,
  SubAgent,
  ToolDefinition,
  AgentWidget,
  DefaultDefinitions,
  AgentProvisionDefinition,
  // Integration types
  UserIntegration,
  IntegrationProviderTS,  // 'google' | 'microsoft'
  IntegrationTypeTS,      // 'email' | 'calendar' | 'drive'
  IntegrationStatusTS,    // 'active' | 'expired' | 'revoked' | 'error'
  // Sandbox types
  Sandbox,
  CreateSandboxRequest,
  CreateSandboxResponse,
} from "@elqnt/agents/models";

// Scheduler types (from API)
import type {
  SchedulerTask,
  SchedulerSchedule,
} from "@elqnt/agents/api";

/utils - Utilities

import { toDefaultDefinitions } from "@elqnt/agents/utils";

// Convert single agent provision to DefaultDefinitions format
const provision: AgentProvisionDefinition = {
  agent: { ... },
  tools: [...],
  subAgents: [...],
  skills: [...],
};

const definitions = toDefaultDefinitions(provision);
// { agents: [...], toolDefinitions: [...], subAgents: [...], skills: [...] }

Type Reference

DefaultDefinitions

The format expected by the provisioning API:

interface DefaultDefinitions {
  agents: Agent[];
  toolDefinitions: ToolDefinition[];
  subAgents: SubAgent[];
  skills: Skill[];
}

AgentProvisionDefinition

Convenience type for single-agent provisioning:

interface AgentProvisionDefinition {
  agent: Agent;
  tools?: ToolDefinition[];
  subAgents?: SubAgent[];
  skills?: Skill[];
}

Use toDefaultDefinitions() to convert to API format.

API Options

interface ApiClientOptions {
  baseUrl: string;      // API Gateway URL
  orgId: string;        // Organization ID
  userId?: string;      // Optional user ID
  userEmail?: string;   // Optional user email
}