@agient/chatbot 1.1.0 → 1.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 <h1>Agient</h1>
 
-**Create AI chatbot assistants with minimal setup. Implement tools that will allow your chatbots to perform actions and fetch data from your website.**
+**Embed an AI chatbot on your website with minimal setup. Register client-side tools to let the AI invoke actions in the user's browser.**
 
 </div>
 
@@ -18,27 +18,9 @@
 npm i @agient/chatbot
 ```
 
-**using [yarn](https://yarnpkg.com)**
-
-```shell
-yarn add @agient/chatbot
-```
-
-**using [pnpm](https://pnpm.io)**
-
-```shell
-pnpm add @agient/chatbot
-```
-
-**using [bun](https://bun.sh)**
-
-```shell
-bun i @agient/chatbot
-```
-
 ## 🚀 Quick Start
 
-Heading to [agient.dev](https://agient.dev) and create your own chatbot project. Once you've created your project, you'll receive an API key that you'll need to initialize the chatbot in your application.
+Head to [agient.dev](https://agient.dev) and create your own chatbot project. Once you've created your project, you'll receive an API key that you'll need to initialize the chatbot in your application.
 
 ```typescript
 import { createAgient } from '@agient/chatbot';
@@ -46,11 +28,15 @@ import { createAgient } from '@agient/chatbot';
 // Initialize the chatbot with your API key
 const agient = createAgient('your-api-key');
 
-agient.on('getWeather', async args => {
-  return 'The weather is currently sunny and 75°F';
+// Called when the AI decides to invoke the tool
+agient.on('getOrderStatus', async ({ orderId }) => {
+  const order = await myApi.getOrder(orderId);
+  return `Order ${orderId} is ${order.status}`;
 });
 ```
 
+Tools execute client-side (in the user's browser) and return results to the AI. No server changes needed on your end.
+
 ## ⚙️ Configuration Options
 
 The `createAgient` function accepts the following options:
@@ -63,22 +49,12 @@ interface AgientOptions {
    * @default true
    */
   autoStart?: boolean;
+  /**
+   * Connection timeout in milliseconds.
+   * @default 10000
+   */
+  timeout?: number;
 }
 ```
 
-### 🔨 Tool Handling
-
-The chatbot supports custom tools that can be implemented to perform specific actions.
-Tools must first be registered inside your chatbot at https://agient.dev. Then you can implement them by their names.
-Here's how to implement a tool:
-
-```typescript
-import { createAgient } from '@agient/chatbot';
-
-const agient = createAgient('your-api-key');
-
-agient.on('incrementCounter', async ({ by }) => {
-  const newCount = await incrementCounter(by);
-  return `The counter is now ${newCount}`;
-});
-```
+> This package is a thin wrapper — `src/index.ts` re-exports everything from `@agient/widget`. All business logic lives in `libs/widget`.

package/dist/index.d.ts

@@ -1,108 +1,60 @@
-/**
- * The main instance interface returned by {@link createAgient}.
- * Provides methods to interact with the chatbot.
- *
- * @template Tools - The type of tools available to the chatbot
- *
- * @example
- * ```typescript
- * const agient = createAgient('api-key');
- *
- * // Register a handler for the 'incrementCounter' tool
- * agient.on('incrementCounter', async ({ by }) => {
- *   const newCount = await incrementCounter(by);
- *   return `The counter is now ${newCount}`;
- * });
- * ```
- */
-export declare class AgientInstance<T extends ToolsMap = DefaultToolsMap> {
-    private readonly apiKey;
-    private readonly options;
-    /**
-     * The status of the chatbot.
-     */
-    private status;
-    /**
-     * The session ID for the chatbot.
-     */
-    private _sessionId;
-    /**
-     * The socket for the chatbot.
-     */
-    private _socket;
-    /**
-     * Whether the chatbot is in playground mode. Used only internally at https://agient.dev
-     */
-    private readonly isPlayground;
-    /**
-     * When the chatbot is active, a provider object is initialized
-     */
-    private provider;
-    /**
-     * Passthrough to AgientElement.onMount
-     */
-    private onMount?;
-    /**
-     * The tools registered by the consumer of the widget.
-     */
-    private readonly registeredTools;
-    constructor(apiKey: string, options: AgientOptions);
-    /**
-     * Register a tool handler for a tool defined in the agient app.
-     *
-     * @param event - The name of the tool to register a handler for.
-     * @param fn - The handler for the tool.
-     */
-    on<Tool extends ToolKeys<T>>(event: Tool, fn: (args: T[Tool]) => string | Promise<string>): void;
+import { FlexibleSchema } from '@ai-sdk/provider-utils';
+
+export declare class AgientInstance {
+    private readonly coreReady;
+    constructor(apiKey: string, options: CreateAgientOptions);
     /**
-     * Start the chatbot.
+     * Starts the chatbot client.
+     * @returns A promise that resolves when the chatbot is connected.
      */
     start(): Promise<void>;
     /**
-     * Stop the chatbot.
+     * Stops the chatbot client.
      */
-    stop(): Promise<void>;
+    stop(): void;
     /**
-     * Stop the chatbot and disconnect the socket.
-     */
-    private onDisconnect;
-    private get socket();
-    private get sessionId();
-    /**
-     * Create a socket for the chatbot.
+     * Registers a client-side tool that the AI agent can invoke during a conversation.
+     * The tool becomes available to the agent for the lifetime of the session, until
+     * {@link unregisterTool} is called with the returned token.
      *
-     * @param apiKey - The API key for the chatbot.
-     * @param sessionId - The session ID for the chatbot.
-     */
-    private createSocket;
-    /**
-     * Get the session ID for the chatbot.
-     */
-    private getSessionId;
-}
-
-/**
- * Configuration options for the Agient chat widget.
- */
-export declare interface AgientOptions {
-    /**
-     * Whether to automatically start the chat widget when initialized.
-     * If false, the widget will need to be manually started.
-     * @default true
+     * @param name - A human-readable name for the tool (e.g. `"getWeather"`). Internally
+     *   suffixed with a UUID to avoid collisions.
+     * @param options - Tool configuration including description, input schema, and execute function.
+     * @returns An opaque token used to unregister the tool later.
+     *
+     * @example
+     * ```ts
+     * import { z } from 'zod';
+     *
+     * const token = await agient.registerTool('getWeather', {
+     *   description: 'Get the current weather for a given city.',
+     *   inputSchema: z.object({
+     *     city: z.string().describe('The city to look up'),
+     *   }),
+     *   execute: async ({ city }) => {
+     *     const res = await fetch(`/api/weather?city=${city}`);
+     *     return res.json();
+     *   },
+     * });
+     *
+     * // Later, when the tool is no longer needed:
+     * agient.unregisterTool(token);
+     * ```
      */
-    autoStart?: boolean;
+    registerTool<TInput, TOutput>(name: string, options: RegisterToolOptions<TInput, TOutput>): Promise<UnregisterToolToken>;
     /**
-     * The timeout for the socket connection.
-     * @default 10000
+     * Unregisters a previously registered tool, removing it from the agent's available tools.
+     *
+     * @param token - The opaque token returned by {@link registerTool}.
      */
-    timeout?: number;
+    unregisterTool(token: UnregisterToolToken): void;
 }
 
 /**
  * Creates a new Agient instance for embedding the chat widget into your application.
  *
  * @param apiKey - Your Agient API key for authentication
- * @param options - Configuration options for the widget instance. See {@link AgientOptions} for available options.
+ * @param options - Configuration options for the widget instance. See {@link CreateAgientOptions} for available options.
  * @returns An {@link AgientInstance} that provides methods to interact with the widget.
  *
  * @example
@@ -111,42 +63,68 @@ export declare interface AgientOptions {
  *   autoStart: true
  * });
  *
- * agient.on('message', async (args) => {
- *   // Handle incoming messages
- *   return 'Response message';
+ * const unregisterToken = await agient.registerTool('getWeather', ({
+ *   description: 'Get the weather for a given city',
+ *   inputSchema: z.object({
+ *     city: z.string(),
+ *   }),
+ *   execute: async ({ city }) => `The weather in ${city} is sunny`,
+ *   metadata: {
+ *     requiresConfirmation: true,
+ *     showContextMessage: true,
+ *   },
  * });
  * ```
  */
-export declare const createAgient: <Tools extends ToolsMap = DefaultToolsMap>(apiKey: string, options?: AgientOptions) => AgientInstance<Tools>;
+export declare const createAgient: (apiKey: string, options: CreateAgientOptions) => AgientInstance;
 
-/**
- * Default tools map that allows any argument types.
- * Used when no specific tool types are provided.
- */
-export declare type DefaultToolsMap = {
-    [key: string]: Record<string, any>;
-};
+export declare interface CreateAgientOptions {
+    /**
+     * Maximum time to wait for socket operations to complete.
+     * @default 10_000
+     */
+    timeout?: number;
+    /**
+     * Whether to automatically start the chatbot client.
+     * @default true
+     */
+    autoStart?: boolean;
+}
 
-/**
- * Represents a valid argument type that can be passed to or returned from a tool.
- * This includes primitive types, arrays, and objects.
- */
-export declare type ToolAgrument = string | number | boolean | null | Array<ToolAgrument> | {
-    [key: string]: ToolAgrument;
-};
+export declare interface RegisterToolOptions<TInput, TOutput> {
+    /**
+     * The description of the tool.
+     */
+    description: string;
+    /**
+     * The schema for the tool's input.
+     */
+    inputSchema?: FlexibleSchema<TInput>;
+    /**
+     * The function to execute when the tool is called.
+     */
+    execute: (input: TInput) => Promise<TOutput> | TOutput;
+    /**
+     * Additional metadata about the tool.
+     */
+    metadata?: {
+        /**
+         * Whether the tool requires user confirmation before execution.
+         * @default false
+         */
+        requiresConfirmation?: boolean;
+        /**
+         * Whether the tool should show a context message to the user while executing.
+         * @default false
+         */
+        showContextMessage?: boolean;
+    };
+}
 
-/**
- * Extracts the available tool names from a {@link ToolsMap}.
- * @template Tools - The tools map type to extract keys from
- */
-export declare type ToolKeys<Tools extends ToolsMap> = keyof Tools & (string | symbol);
+declare const UnregisterToolBrand: unique symbol;
 
-/**
- * Maps tool names to their argument types.
- * Each tool is defined as a record of string keys to {@link ToolAgrument} values.
- */
-export declare type ToolsMap = {
-    [key: string]: Record<string, ToolAgrument>;
+export declare type UnregisterToolToken = string & {
+    readonly [UnregisterToolBrand]: never;
 };
 
 export { }