@elqnt/agents 3.0.3 → 3.0.4

package/README.md

@@ -0,0 +1,196 @@
+# @elqnt/agents
+
+AI agent management for Eloquent platform - models, API, hooks, and utilities.
+
+## Installation
+
+```bash
+pnpm add @elqnt/agents
+```
+
+## Quick Start
+
+### Provisioning Agents (Admin)
+
+Use `provisionAgentsApi` to set up default agents for an organization:
+
+```typescript
+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-4.1-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
+
+```typescript
+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
+
+```typescript
+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,
+
+  // Provisioning
+  provisionAgentsApi,
+} from "@elqnt/agents/api";
+```
+
+### `/hooks` - React Hooks
+
+```typescript
+import { useAgents, useSkills } from "@elqnt/agents/hooks";
+
+const { agents, loading, error, createAgent } = useAgents(options);
+const { skills, loading, error } = useSkills(options);
+```
+
+### `/models` - TypeScript Types
+
+Types generated from Go via tygo.
+
+```typescript
+import type {
+  Agent,
+  AgentSummary,
+  Skill,
+  SubAgent,
+  ToolDefinition,
+  AgentWidget,
+  DefaultDefinitions,
+  AgentProvisionDefinition,
+} from "@elqnt/agents/models";
+```
+
+### `/utils` - Utilities
+
+```typescript
+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:
+
+```typescript
+interface DefaultDefinitions {
+  agents: Agent[];
+  toolDefinitions: ToolDefinition[];
+  subAgents: SubAgent[];
+  skills: Skill[];
+}
+```
+
+### AgentProvisionDefinition
+
+Convenience type for single-agent provisioning:
+
+```typescript
+interface AgentProvisionDefinition {
+  agent: Agent;
+  tools?: ToolDefinition[];
+  subAgents?: SubAgent[];
+  skills?: Skill[];
+}
+```
+
+Use `toDefaultDefinitions()` to convert to API format.
+
+## API Options
+
+```typescript
+interface ApiClientOptions {
+  baseUrl: string;      // API Gateway URL
+  orgId: string;        // Organization ID
+  userId?: string;      // Optional user ID
+  userEmail?: string;   // Optional user email
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elqnt/agents",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "Agent management and orchestration for Eloquent platform - models, browser & server APIs, React hooks, and utilities",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -46,8 +46,8 @@
     "directory": "packages/agents"
   },
   "dependencies": {
-    "@elqnt/types": "2.0.9",
-    "@elqnt/api-client": "1.0.3",
+    "@elqnt/types": "2.0.10",
+    "@elqnt/api-client": "1.0.4",
     "@elqnt/kg": "3.0.0"
   },
   "peerDependencies": {
@@ -58,7 +58,7 @@
     "react": "^19.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
-    "@elqnt/api-client": "1.0.3"
+    "@elqnt/api-client": "1.0.4"
   },
   "scripts": {
     "build": "tsup",