@kigathi/ai-agents 0.1.2 → 0.1.3

package/README.md

@@ -17,7 +17,7 @@ npm install openai
 ## Quick API shape
 
 ```js
-import { createClient } from '@kigathi/ai-agents';
+import { createClient } from "@kigathi/ai-agents";
 
 const sdk = createClient(config);
 sdk.registerTool(tool);
@@ -25,6 +25,66 @@ sdk.createAgent(agent);
 const result = await sdk.run(params);
 ```
 
+## Modes
+
+The SDK supports three setup patterns, and in normal usage you do not need to pass `mode` manually. The client infers it from the config you provide.
+
+### 1. Direct mode
+
+Use this when your app should call OpenAI directly and you do not need backend persistence.
+
+```js
+import { createClient } from "@kigathi/ai-agents";
+
+const sdk = createClient({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+```
+
+Required:
+
+- `apiKey`
+
+### 2. Proxy mode
+
+Use this when your app should call your backend, and your backend should perform the agent run.
+
+```js
+import { createClient } from "@kigathi/ai-agents";
+
+const sdk = createClient({
+  backendUrl: "https://api.example.com",
+});
+```
+
+Required:
+
+- `backendUrl`
+
+### 3. Direct mode with backend persistence
+
+Use this when your app should call OpenAI directly, but you still want your backend to persist messages, receive tool events, or trigger downstream workflows.
+
+```js
+import { createClient } from "@kigathi/ai-agents";
+
+const sdk = createClient({
+  apiKey: process.env.OPENAI_API_KEY,
+  backendUrl: "https://api.example.com",
+});
+```
+
+Required:
+
+- `apiKey`
+- `backendUrl`
+
+Behavior summary:
+
+- `apiKey` only: direct OpenAI execution
+- `backendUrl` only: proxy mode, where your backend performs the run
+- `apiKey` and `backendUrl` together: direct OpenAI execution plus backend persistence and event sync
+
 ## Minimal vs full examples
 
 The sections below show the smallest valid call for each API, followed by a more realistic production-style example.
@@ -34,7 +94,7 @@ The sections below show the smallest valid call for each API, followed by a more
 Minimal direct mode:
 
 ```js
-import { createClient } from '@kigathi/ai-agents';
+import { createClient } from "@kigathi/ai-agents";
 
 const sdk = createClient({
   apiKey: process.env.OPENAI_API_KEY,
@@ -44,26 +104,25 @@ const sdk = createClient({
 Minimal proxy mode:
 
 ```js
-import { createClient } from '@kigathi/ai-agents';
+import { createClient } from "@kigathi/ai-agents";
 
 const sdk = createClient({
-  backendUrl: 'https://api.example.com',
+  backendUrl: "https://api.example.com",
 });
 ```
 
 Full example:
 
 ```js
-import { createClient } from '@kigathi/ai-agents';
+import { createClient } from "@kigathi/ai-agents";
 
 const sdk = createClient({
   apiKey: process.env.OPENAI_API_KEY,
   orgId: process.env.OPENAI_ORG_ID,
   projectId: process.env.OPENAI_PROJECT_ID,
-  backendUrl: 'https://api.example.com',
-  mode: 'direct',
+  backendUrl: "https://api.example.com",
   pricing: {
-    'gpt-4.1-mini': {
+    "gpt-4.1-mini": {
       prompt_per_million: 0.4,
       completion_per_million: 1.6,
     },
@@ -90,12 +149,11 @@ You can also run the model directly with OpenAI while still sending conversation
 Use `apiKey` and `backendUrl` together:
 
 ```js
-import { createClient } from '@kigathi/ai-agents';
+import { createClient } from "@kigathi/ai-agents";
 
 const sdk = createClient({
   apiKey: process.env.OPENAI_API_KEY,
-  backendUrl: 'https://api.example.com',
-  mode: 'direct',
+  backendUrl: "https://api.example.com",
 });
 ```
 
@@ -120,7 +178,7 @@ Minimal example:
 
 ```js
 sdk.registerTool({
-  name: 'lookup_order',
+  name: "lookup_order",
 });
 ```
 
@@ -128,20 +186,20 @@ Full example:
 
 ```js
 sdk.registerTool({
-  name: 'lookup_order',
-  type: 'function',
-  description: 'Find order details by order number.',
+  name: "lookup_order",
+  type: "function",
+  description: "Find order details by order number.",
   parameters_schema: {
-    type: 'object',
+    type: "object",
     properties: {
-      order_number: { type: 'string' },
+      order_number: { type: "string" },
     },
-    required: ['order_number'],
+    required: ["order_number"],
   },
   handler: async ({ order_number }, context) => {
     return {
       order_number,
-      status: 'processing',
+      status: "processing",
       requested_by: context.userId ?? null,
     };
   },
@@ -169,8 +227,8 @@ Minimal example:
 
 ```js
 sdk.createAgent({
-  name: 'support-bot',
-  model: 'gpt-4.1-mini',
+  name: "support-bot",
+  model: "gpt-4.1-mini",
 });
 ```
 
@@ -178,16 +236,16 @@ Full example:
 
 ```js
 sdk.createAgent({
-  id: 'support-bot-v1',
-  name: 'support-bot',
-  model: 'gpt-4.1-mini',
-  instructions: 'You are a concise support assistant. Use tools when needed.',
+  id: "support-bot-v1",
+  name: "support-bot",
+  model: "gpt-4.1-mini",
+  instructions: "You are a concise support assistant. Use tools when needed.",
   temperature: 0.3,
   max_output_tokens: 400,
-  tools: ['lookup_order'],
+  tools: ["lookup_order"],
   metadata: {
-    team: 'support',
-    channel: 'web',
+    team: "support",
+    channel: "web",
   },
 });
 ```
@@ -212,8 +270,8 @@ Minimal example:
 
 ```js
 const result = await sdk.run({
-  agent: 'support-bot',
-  message: 'Where is order AX-4420?',
+  agent: "support-bot",
+  message: "Where is order AX-4420?",
 });
 
 console.log(result.output_text);
@@ -223,18 +281,18 @@ Full example:
 
 ```js
 const result = await sdk.run({
-  agent: 'support-bot',
-  message: 'Check order AX-4420 and summarize the current status.',
+  agent: "support-bot",
+  message: "Check order AX-4420 and summarize the current status.",
   conversation_id: 1234,
-  conversation_key: 'support:customer-42',
+  conversation_key: "support:customer-42",
   user_id: 42,
   context: {
     userId: 42,
-    accountId: 'acc_123',
+    accountId: "acc_123",
   },
   messages: [
-    { role: 'user', content: 'Hi' },
-    { role: 'assistant', content: 'How can I help?' },
+    { role: "user", content: "Hi" },
+    { role: "assistant", content: "How can I help?" },
   ],
   max_history_messages: 20,
   maxToolIterations: 8,
@@ -268,8 +326,8 @@ Minimal example:
 
 ```js
 for await (const delta of sdk.runStream({
-  agent: 'support-bot',
-  message: 'Give me a short update on order AX-4420.',
+  agent: "support-bot",
+  message: "Give me a short update on order AX-4420.",
 })) {
   process.stdout.write(delta);
 }
@@ -279,9 +337,9 @@ Full example:
 
 ```js
 for await (const delta of sdk.runStream({
-  agent: 'support-bot',
-  message: 'Summarize the latest ticket updates.',
-  conversation_key: 'support:customer-42',
+  agent: "support-bot",
+  message: "Summarize the latest ticket updates.",
+  conversation_key: "support:customer-42",
   user_id: 42,
 })) {
   process.stdout.write(delta);
@@ -291,38 +349,38 @@ for await (const delta of sdk.runStream({
 ## Complete minimal working example
 
 ```js
-import { createClient } from '@kigathi/ai-agents';
+import { createClient } from "@kigathi/ai-agents";
 
 const sdk = createClient({
   apiKey: process.env.OPENAI_API_KEY,
 });
 
 sdk.registerTool({
-  name: 'lookup_order',
-  description: 'Return a fake order status.',
+  name: "lookup_order",
+  description: "Return a fake order status.",
   parameters_schema: {
-    type: 'object',
+    type: "object",
     properties: {
-      order_number: { type: 'string' },
+      order_number: { type: "string" },
     },
-    required: ['order_number'],
+    required: ["order_number"],
   },
   handler: async ({ order_number }) => ({
     order_number,
-    status: 'processing',
+    status: "processing",
   }),
 });
 
 sdk.createAgent({
-  name: 'support-bot',
-  model: 'gpt-4.1-mini',
-  instructions: 'You are a concise support assistant.',
-  tools: ['lookup_order'],
+  name: "support-bot",
+  model: "gpt-4.1-mini",
+  instructions: "You are a concise support assistant.",
+  tools: ["lookup_order"],
 });
 
 const result = await sdk.run({
-  agent: 'support-bot',
-  message: 'Check order AX-4420',
+  agent: "support-bot",
+  message: "Check order AX-4420",
 });
 
 console.log(result.output_text);
@@ -331,16 +389,15 @@ console.log(result.output_text);
 ## Complete proxy example
 
 ```js
-import { createClient } from '@kigathi/ai-agents';
+import { createClient } from "@kigathi/ai-agents";
 
 const sdk = createClient({
-  backendUrl: 'https://api.example.com',
-  mode: 'proxy',
+  backendUrl: "https://api.example.com",
 });
 
 const result = await sdk.run({
-  agent: 'support-bot',
-  message: 'Start claim #99',
+  agent: "support-bot",
+  message: "Start claim #99",
   conversation_id: 1234,
 });
 
@@ -350,46 +407,45 @@ console.log(result.output_text);
 ## Complete direct + backend persistence example
 
 ```js
-import { createClient } from '@kigathi/ai-agents';
+import { createClient } from "@kigathi/ai-agents";
 
 const sdk = createClient({
   apiKey: process.env.OPENAI_API_KEY,
-  backendUrl: 'https://api.example.com',
-  mode: 'direct',
+  backendUrl: "https://api.example.com",
 });
 
 sdk.registerTool({
-  name: 'lookup_order',
-  description: 'Find order by order number.',
+  name: "lookup_order",
+  description: "Find order by order number.",
   parameters_schema: {
-    type: 'object',
+    type: "object",
     properties: {
-      order_number: { type: 'string' },
+      order_number: { type: "string" },
     },
-    required: ['order_number'],
+    required: ["order_number"],
   },
   handler: async ({ order_number }) => ({
     order_number,
-    status: 'processing',
+    status: "processing",
   }),
 });
 
 sdk.createAgent({
-  name: 'support-bot',
-  model: 'gpt-4.1-mini',
-  instructions: 'You are a concise support assistant.',
-  tools: ['lookup_order'],
+  name: "support-bot",
+  model: "gpt-4.1-mini",
+  instructions: "You are a concise support assistant.",
+  tools: ["lookup_order"],
 });
 
 const result = await sdk.run({
-  agent: 'support-bot',
-  message: 'Check order AX-4420',
+  agent: "support-bot",
+  message: "Check order AX-4420",
   conversation_id: 1234,
   user_id: 42,
-  client_message_id: 'msg_123',
+  client_message_id: "msg_123",
   metadata: {
-    source: 'dashboard',
-    account_id: 'acc_123',
+    source: "dashboard",
+    account_id: "acc_123",
   },
 });
 
@@ -398,15 +454,15 @@ console.log(result.output_text);
 
 ## Full sample apps
 
-- `../examples/lyre-ai-agents-node/express-chat` - Express server + Tailwind widget UI
-- `../examples/lyre-ai-agents-node/nuxt-chat` - Nuxt 3 app + server API route + Tailwind
-- `../examples/lyre-ai-agents-node/sveltekit-chat` - SvelteKit app + server endpoint + Tailwind
+- [express-chat](https://github.com/kigathi-chege/lyre-ai-agents-examples/tree/main/express-chat) - Express server + Tailwind widget UI
+- [nuxt-chat](https://github.com/kigathi-chege/lyre-ai-agents-examples/tree/main/nuxt-chat) - Nuxt 3 app + server API route + Tailwind
+- [sveltekit-chat](https://github.com/kigathi-chege/lyre-ai-agents-examples/tree/main/sveltekit-chat) - SvelteKit app + server endpoint + Tailwind
 
-All three use `@kigathi/ai-agents` in `proxy` mode against Axis backend so conversation, message, and cost metadata stay in Axis.
+All three use `@kigathi/ai-agents` in direct mode with backend persistence so OpenAI handles model execution while Axis stores conversation, message, and related event metadata.
 
 ## Notes
 
-- `createClient()` auto-selects `proxy` mode when `backendUrl` is provided without `apiKey`. Otherwise it defaults to `direct`.
+- `createClient()` auto-selects proxy mode when `backendUrl` is provided without `apiKey`. Otherwise it uses direct mode.
 - In direct mode, the consuming app must have the `openai` package installed.
 - In direct mode with `backendUrl`, the SDK still calls OpenAI directly, then asynchronously persists messages and tool events to your backend.
 - You can pass either an agent name/id or a full agent object to `run()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kigathi/ai-agents",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Forward-only Agents/Bots SDK on top of OpenAI Responses API.",
   "type": "module",
   "sideEffects": false,