@antipopp/agno-client 0.8.0 → 0.10.0

package/README.md

@@ -68,6 +68,8 @@ new AgnoClient(config: AgnoClientConfig)
 - `dbId` (string, optional) - Database ID
 - `sessionId` (string, optional) - Current session ID
 - `userId` (string, optional) - User ID to link sessions to a specific user
+- `headers` (Record<string, string>, optional) - Global custom headers for all API requests
+- `params` (Record<string, string>, optional) - Global query parameters for all API requests
 
 ### Methods
 
@@ -88,6 +90,17 @@ await client.sendMessage(formData);
 await client.sendMessage('Hello!', {
   headers: { 'X-Custom-Header': 'value' }
 });
+
+// With query parameters
+await client.sendMessage('Hello!', {
+  params: { temperature: '0.7', max_tokens: '500' }
+});
+
+// With both headers and params
+await client.sendMessage('Hello!', {
+  headers: { 'X-Request-ID': '12345' },
+  params: { debug: 'true' }
+});
 ```
 
 #### `getMessages()`
@@ -241,6 +254,94 @@ try {
 }
 ```
 
+### Custom Headers and Query Parameters
+
+The client supports both global and per-request headers and query parameters.
+
+#### Global Configuration
+
+Set headers and params in the client config to apply them to all API requests:
+
+```typescript
+const client = new AgnoClient({
+  endpoint: 'http://localhost:7777',
+  agentId: 'agent-123',
+  headers: {
+    'X-API-Version': 'v2',
+    'X-Client-ID': 'my-app'
+  },
+  params: {
+    locale: 'en-US',
+    environment: 'production'
+  }
+});
+```
+
+#### Per-Request Options
+
+Override or add headers/params for specific requests:
+
+```typescript
+// Per-request overrides global settings
+await client.sendMessage('Hello!', {
+  headers: { 'X-Request-ID': '12345' },
+  params: { temperature: '0.7' }
+});
+
+// All methods support headers and params
+await client.loadSession('session-123', {
+  params: { include_metadata: 'true' }
+});
+
+await client.fetchSessions({
+  params: { limit: '50', status: 'active' }
+});
+
+await client.continueRun(tools, {
+  headers: { 'X-Trace-ID': 'abc123' },
+  params: { debug: 'true' }
+});
+```
+
+#### Merge Behavior
+
+**Headers:**
+1. Global headers from `config.headers` (lowest precedence)
+2. Per-request headers (overrides global)
+3. Authorization header from `authToken` (highest precedence - always overrides)
+
+**Query Parameters:**
+1. Global params from `config.params` (lowest precedence)
+2. Per-request params (highest precedence - overrides global)
+
+```typescript
+const client = new AgnoClient({
+  endpoint: 'http://localhost:7777',
+  agentId: 'agent-123',
+  params: { version: 'v1', locale: 'en-US' }
+});
+
+// This request will have: version=v2 (overridden), locale=en-US (from global), debug=true (added)
+await client.sendMessage('Hello!', {
+  params: { version: 'v2', debug: 'true' }
+});
+```
+
+#### Common Use Cases
+
+**Headers:**
+- Request tracking: `{ 'X-Request-ID': uuid() }`
+- API versioning: `{ 'X-API-Version': 'v2' }`
+- Client identification: `{ 'X-Client-ID': 'mobile-app' }`
+- Custom auth: `{ 'X-Custom-Auth': 'token' }`
+
+**Query Parameters:**
+- Model configuration: `{ temperature: '0.7', max_tokens: '500' }`
+- Feature flags: `{ enable_streaming: 'true' }`
+- Locale/language: `{ locale: 'en-US', timezone: 'America/New_York' }`
+- Debugging: `{ debug: 'true', trace_id: 'xyz' }`
+- Pagination: `{ page: '1', limit: '50' }`
+
 ### Request Cancellation
 
 Use `AbortController` to cancel ongoing requests. This is essential for preventing memory leaks when components unmount or users navigate away during streaming:

package/dist/index.d.mts

@@ -1,19 +1,20 @@
-import EventEmitter from 'eventemitter3';
 import { AgnoClientConfig, ChatMessage, ClientState, SessionEntry, ToolCall, AgentDetails, TeamDetails } from '@antipopp/agno-types';
 export { AgentDetails, AgnoClientConfig, AudioData, ChatMessage, ClientState, ImageData, MessageExtraData, ResponseAudioData, RunEvent, RunResponse, RunResponseContent, SessionEntry, TeamDetails, ToolCall, VideoData } from '@antipopp/agno-types';
+import EventEmitter from 'eventemitter3';
 
 /**
  * Main Agno client class
  * Provides stateful management of agent/team interactions with streaming support
  */
 declare class AgnoClient extends EventEmitter {
-    private messageStore;
-    private configManager;
-    private sessionManager;
-    private eventProcessor;
-    private state;
-    private pendingUISpecs;
+    private readonly messageStore;
+    private readonly configManager;
+    private readonly sessionManager;
+    private readonly eventProcessor;
+    private readonly state;
+    private readonly pendingUISpecs;
     private runCompletedSuccessfully;
+    private currentRunId;
     constructor(config: AgnoClientConfig);
     /**
      * Get current messages
@@ -35,11 +36,16 @@ declare class AgnoClient extends EventEmitter {
      * Clear all messages
      */
     clearMessages(): void;
+    /**
+     * Cancel an active or paused run
+     */
+    cancelRun(): Promise<void>;
     /**
      * Send a message to the agent/team (streaming)
      */
     sendMessage(message: string | FormData, options?: {
         headers?: Record<string, string>;
+        params?: Record<string, string>;
     }): Promise<void>;
     /**
      * Handle streaming chunk
@@ -59,15 +65,21 @@ declare class AgnoClient extends EventEmitter {
     /**
      * Load a session
      */
-    loadSession(sessionId: string): Promise<ChatMessage[]>;
+    loadSession(sessionId: string, options?: {
+        params?: Record<string, string>;
+    }): Promise<ChatMessage[]>;
     /**
      * Fetch all sessions
      */
-    fetchSessions(): Promise<SessionEntry[]>;
+    fetchSessions(options?: {
+        params?: Record<string, string>;
+    }): Promise<SessionEntry[]>;
     /**
      * Delete a session
      */
-    deleteSession(sessionId: string): Promise<void>;
+    deleteSession(sessionId: string, options?: {
+        params?: Record<string, string>;
+    }): Promise<void>;
     /**
      * Add tool calls to the last message
      * Used by frontend execution to add tool calls that were executed locally
@@ -91,33 +103,48 @@ declare class AgnoClient extends EventEmitter {
      * Teams do not support the continue endpoint.
      *
      * @param tools - Array of tool calls with execution results
-     * @param options - Optional request headers
+     * @param options - Optional request headers and query parameters
      * @throws Error if no paused run exists
      * @throws Error if called with team mode (teams don't support HITL)
      */
     continueRun(tools: ToolCall[], options?: {
         headers?: Record<string, string>;
+        params?: Record<string, string>;
     }): Promise<void>;
     /**
      * Check endpoint status
      */
-    checkStatus(): Promise<boolean>;
+    checkStatus(options?: {
+        params?: Record<string, string>;
+    }): Promise<boolean>;
     /**
      * Fetch agents from endpoint
      */
-    fetchAgents(): Promise<AgentDetails[]>;
+    fetchAgents(options?: {
+        params?: Record<string, string>;
+    }): Promise<AgentDetails[]>;
     /**
      * Fetch teams from endpoint
      */
-    fetchTeams(): Promise<TeamDetails[]>;
+    fetchTeams(options?: {
+        params?: Record<string, string>;
+    }): Promise<TeamDetails[]>;
     /**
      * Initialize client (check status and fetch agents/teams)
      * Automatically selects the first available agent or team if none is configured
      */
-    initialize(): Promise<{
+    initialize(options?: {
+        params?: Record<string, string>;
+    }): Promise<{
         agents: AgentDetails[];
         teams: TeamDetails[];
     }>;
+    /**
+     * Dispose of the client and clean up all resources.
+     * Call this method when the client is no longer needed to prevent memory leaks.
+     * After calling dispose(), the client instance should not be reused.
+     */
+    dispose(): void;
 }
 
 /**

package/dist/index.d.ts

@@ -1,19 +1,20 @@
-import EventEmitter from 'eventemitter3';
 import { AgnoClientConfig, ChatMessage, ClientState, SessionEntry, ToolCall, AgentDetails, TeamDetails } from '@antipopp/agno-types';
 export { AgentDetails, AgnoClientConfig, AudioData, ChatMessage, ClientState, ImageData, MessageExtraData, ResponseAudioData, RunEvent, RunResponse, RunResponseContent, SessionEntry, TeamDetails, ToolCall, VideoData } from '@antipopp/agno-types';
+import EventEmitter from 'eventemitter3';
 
 /**
  * Main Agno client class
  * Provides stateful management of agent/team interactions with streaming support
  */
 declare class AgnoClient extends EventEmitter {
-    private messageStore;
-    private configManager;
-    private sessionManager;
-    private eventProcessor;
-    private state;
-    private pendingUISpecs;
+    private readonly messageStore;
+    private readonly configManager;
+    private readonly sessionManager;
+    private readonly eventProcessor;
+    private readonly state;
+    private readonly pendingUISpecs;
     private runCompletedSuccessfully;
+    private currentRunId;
     constructor(config: AgnoClientConfig);
     /**
      * Get current messages
@@ -35,11 +36,16 @@ declare class AgnoClient extends EventEmitter {
      * Clear all messages
      */
     clearMessages(): void;
+    /**
+     * Cancel an active or paused run
+     */
+    cancelRun(): Promise<void>;
     /**
      * Send a message to the agent/team (streaming)
      */
     sendMessage(message: string | FormData, options?: {
         headers?: Record<string, string>;
+        params?: Record<string, string>;
     }): Promise<void>;
     /**
      * Handle streaming chunk
@@ -59,15 +65,21 @@ declare class AgnoClient extends EventEmitter {
     /**
      * Load a session
      */
-    loadSession(sessionId: string): Promise<ChatMessage[]>;
+    loadSession(sessionId: string, options?: {
+        params?: Record<string, string>;
+    }): Promise<ChatMessage[]>;
     /**
      * Fetch all sessions
      */
-    fetchSessions(): Promise<SessionEntry[]>;
+    fetchSessions(options?: {
+        params?: Record<string, string>;
+    }): Promise<SessionEntry[]>;
     /**
      * Delete a session
      */
-    deleteSession(sessionId: string): Promise<void>;
+    deleteSession(sessionId: string, options?: {
+        params?: Record<string, string>;
+    }): Promise<void>;
     /**
      * Add tool calls to the last message
      * Used by frontend execution to add tool calls that were executed locally
@@ -91,33 +103,48 @@ declare class AgnoClient extends EventEmitter {
      * Teams do not support the continue endpoint.
      *
      * @param tools - Array of tool calls with execution results
-     * @param options - Optional request headers
+     * @param options - Optional request headers and query parameters
      * @throws Error if no paused run exists
      * @throws Error if called with team mode (teams don't support HITL)
      */
     continueRun(tools: ToolCall[], options?: {
         headers?: Record<string, string>;
+        params?: Record<string, string>;
     }): Promise<void>;
     /**
      * Check endpoint status
      */
-    checkStatus(): Promise<boolean>;
+    checkStatus(options?: {
+        params?: Record<string, string>;
+    }): Promise<boolean>;
     /**
      * Fetch agents from endpoint
      */
-    fetchAgents(): Promise<AgentDetails[]>;
+    fetchAgents(options?: {
+        params?: Record<string, string>;
+    }): Promise<AgentDetails[]>;
     /**
      * Fetch teams from endpoint
      */
-    fetchTeams(): Promise<TeamDetails[]>;
+    fetchTeams(options?: {
+        params?: Record<string, string>;
+    }): Promise<TeamDetails[]>;
     /**
      * Initialize client (check status and fetch agents/teams)
      * Automatically selects the first available agent or team if none is configured
      */
-    initialize(): Promise<{
+    initialize(options?: {
+        params?: Record<string, string>;
+    }): Promise<{
         agents: AgentDetails[];
         teams: TeamDetails[];
     }>;
+    /**
+     * Dispose of the client and clean up all resources.
+     * Call this method when the client is no longer needed to prevent memory leaks.
+     * After calling dispose(), the client instance should not be reused.
+     */
+    dispose(): void;
 }
 
 /**