agent0-js 0.0.5 → 0.0.7

package/README.md

@@ -86,6 +86,36 @@ Execute an agent and get the complete response.
 interface RunOptions {
   agentId: string;                    // The ID of the agent to run
   variables?: Record<string, string>; // Variables to pass to the agent
+  overrides?: ModelOverrides;         // Runtime model configuration overrides
+  extraMessages?: Message[];          // Extra messages to append to the prompt
+}
+
+interface ModelOverrides {
+  model?: {                    // Override the model
+    provider_id?: string;      // Override provider ID
+    name?: string;             // Override model name
+  };
+  maxOutputTokens?: number;    // Override max output tokens
+  temperature?: number;        // Override temperature
+  maxStepCount?: number;       // Override max step count
+  providerOptions?: ProviderOptions; // Provider-specific reasoning options
+}
+
+interface ProviderOptions {
+  openai?: {
+    reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high';
+    reasoningSummary?: 'auto' | 'detailed';
+  };
+  xai?: {
+    reasoningEffort?: 'low' | 'medium' | 'high';
+  };
+  google?: {
+    thinkingConfig?: {
+      thinkingBudget?: number;
+      thinkingLevel?: 'low' | 'medium' | 'high';
+      includeThoughts?: boolean;
+    };
+  };
 }
 ```
 
@@ -226,6 +256,151 @@ const response = await client.generate({
 // Prompt becomes: "Hello Sarah, let's talk about machine learning"
 ```
 
+### Model Overrides
+
+The `overrides` option allows you to dynamically configure the model at runtime. This is useful for:
+- **Load Balancing**: Distribute requests across different providers
+- **Fallbacks**: Switch to a backup model if the primary is unavailable  
+- **A/B Testing**: Test different models with the same agent configuration
+- **Cost Optimization**: Use cheaper models for non-critical requests
+
+```typescript
+// Override the model for a specific request
+const response = await client.generate({
+  agentId: 'agent_123',
+  variables: { prompt: 'Hello world' },
+  overrides: {
+    model: { name: 'gpt-4o-mini' }, // Use a different model
+    temperature: 0.5,               // Adjust temperature
+    maxOutputTokens: 500            // Limit output length
+  }
+});
+
+// Implement a simple fallback pattern
+async function runWithFallback(agentId: string, variables: Record<string, string>) {
+  try {
+    return await client.generate({ agentId, variables });
+  } catch (error) {
+    // Fallback to a different provider/model
+    return await client.generate({
+      agentId,
+      variables,
+      overrides: {
+        model: {
+          provider_id: 'backup-provider-id',
+          name: 'claude-3-haiku-20240307'
+        }
+      }
+    });
+  }
+}
+```
+
+### Provider Options
+
+The `providerOptions` option allows you to configure provider-specific reasoning and thinking behavior. Different providers have different options:
+
+**OpenAI / Azure** - Use `reasoningEffort` to control how much reasoning the model does, and `reasoningSummary` to control whether the model returns its reasoning process:
+
+```typescript
+const response = await client.generate({
+  agentId: 'agent_123',
+  overrides: {
+    providerOptions: {
+      openai: {
+        reasoningEffort: 'high', // 'minimal' | 'low' | 'medium' | 'high'
+        reasoningSummary: 'auto' // 'auto' | 'detailed' - controls reasoning output
+      }
+    }
+  }
+});
+```
+
+- `reasoningSummary: 'auto'` - Returns a condensed summary of the reasoning process
+- `reasoningSummary: 'detailed'` - Returns more comprehensive reasoning
+- When enabled, reasoning summaries appear in the stream as events with type `'reasoning'` and in non-streaming responses within the `reasoning` field
+
+**xAI (Grok)** - Use `reasoningEffort` to control reasoning:
+
+```typescript
+const response = await client.generate({
+  agentId: 'agent_123',
+  overrides: {
+    providerOptions: {
+      xai: {
+        reasoningEffort: 'high' // 'low' | 'medium' | 'high'
+      }
+    }
+  }
+});
+```
+
+**Google Generative AI / Google Vertex** - Use `thinkingConfig` to control thinking (use either `thinkingLevel` or `thinkingBudget`, not both):
+
+```typescript
+// Using thinkingLevel (recommended for most cases)
+const response = await client.generate({
+  agentId: 'agent_123',
+  overrides: {
+    providerOptions: {
+      google: {
+        thinkingConfig: {
+          thinkingLevel: 'high',     // 'low' | 'medium' | 'high'
+          includeThoughts: true      // Include thinking in response
+        }
+      }
+    }
+  }
+});
+
+// OR using thinkingBudget (for fine-grained control)
+const response = await client.generate({
+  agentId: 'agent_123',
+  overrides: {
+    providerOptions: {
+      google: {
+        thinkingConfig: {
+          thinkingBudget: 8192,      // Number of thinking tokens
+          includeThoughts: true
+        }
+      }
+    }
+  }
+});
+```
+
+### Extra Messages
+
+The `extraMessages` option allows you to programmatically append additional messages to the agent's prompt. These messages are used as-is without any variable substitution, making them ideal for:
+- **Dynamic Context**: Add conversation history or context at runtime
+- **Multi-turn Conversations**: Build chat applications by appending user/assistant turns
+- **Retrieved Content**: Inject RAG results or retrieved documents
+
+```typescript
+// Add conversation history to the agent
+const response = await client.generate({
+  agentId: 'agent_123',
+  variables: { topic: 'AI' },
+  extraMessages: [
+    { role: 'user', content: 'What is machine learning?' },
+    { role: 'assistant', content: 'Machine learning is a subset of AI...' },
+    { role: 'user', content: 'Tell me more about neural networks' }
+  ]
+});
+
+// Inject retrieved context (RAG pattern)
+const retrievedDocs = await searchDocuments(query);
+const response = await client.generate({
+  agentId: 'rag-agent',
+  extraMessages: [
+    { 
+      role: 'user', 
+      content: `Context:\n${retrievedDocs.join('\n')}\n\nQuestion: ${query}` 
+    }
+  ]
+});
+```
+
 ### Error Handling
 
 ```typescript

package/dist/index.js

@@ -27,6 +27,8 @@ class Agent0 {
         const response = await this.fetchApi('/api/v1/run', {
             agent_id: options.agentId,
             variables: options.variables,
+            overrides: options.overrides,
+            extra_messages: options.extraMessages,
             stream: false,
         });
         return await response.json();
@@ -35,6 +37,8 @@ class Agent0 {
         const response = await this.fetchApi('/api/v1/run', {
             agent_id: options.agentId,
             variables: options.variables,
+            overrides: options.overrides,
+            extra_messages: options.extraMessages,
             stream: true,
         });
         if (!response.body) {

package/dist/types.d.ts

@@ -1,11 +1,49 @@
+import type { GoogleGenerativeAIProviderOptions } from "@ai-sdk/google";
+import type { OpenAIResponsesProviderOptions } from "@ai-sdk/openai";
+import type { XaiProviderOptions } from "@ai-sdk/xai";
 import type { ModelMessage } from "ai";
 export interface Agent0Config {
     apiKey: string;
     baseUrl?: string;
 }
+/**
+ * Provider-specific options for reasoning/thinking configuration.
+ * Each provider has its own format for controlling reasoning behavior.
+ */
+export interface ProviderOptions {
+    /** OpenAI reasoning effort options */
+    openai?: OpenAIResponsesProviderOptions;
+    /** xAI reasoning effort options */
+    xai?: XaiProviderOptions;
+    /** Google/Vertex thinking configuration */
+    google?: GoogleGenerativeAIProviderOptions;
+}
+/**
+ * Model configuration overrides for runtime customization.
+ * Allows downstream applications to implement load balancing, fallbacks, and dynamic model switching.
+ */
+export interface ModelOverrides {
+    /** Override the model provider and name */
+    model?: {
+        provider_id?: string;
+        name?: string;
+    };
+    /** Override max output tokens */
+    maxOutputTokens?: number;
+    /** Override temperature */
+    temperature?: number;
+    /** Override max step count */
+    maxStepCount?: number;
+    /** Provider-specific options for reasoning/thinking configuration */
+    providerOptions?: ProviderOptions;
+}
 export interface RunOptions {
     agentId: string;
     variables?: Record<string, string>;
+    /** Runtime model overrides for load balancing, fallbacks, etc. */
+    overrides?: ModelOverrides;
+    /** Extra messages to append to the agent's prompt (used as-is, no variable substitution) */
+    extraMessages?: ModelMessage[];
 }
 export interface GenerateResponse {
     messages: ModelMessage[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent0-js",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "TypeScript SDK for Agent0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,6 +17,9 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
+    "@ai-sdk/google": "3.0.0-beta.69",
+    "@ai-sdk/openai": "3.0.0-beta.90",
+    "@ai-sdk/xai": "3.0.0-beta.54",
     "ai": "^5.0.98"
   },
   "scripts": {

package/src/index.ts

@@ -36,6 +36,8 @@ export class Agent0 {
         const response = await this.fetchApi('/api/v1/run', {
             agent_id: options.agentId,
             variables: options.variables,
+            overrides: options.overrides,
+            extra_messages: options.extraMessages,
             stream: false,
         });
 
@@ -46,6 +48,8 @@ export class Agent0 {
         const response = await this.fetchApi('/api/v1/run', {
             agent_id: options.agentId,
             variables: options.variables,
+            overrides: options.overrides,
+            extra_messages: options.extraMessages,
             stream: true,
         });
 

package/src/types.ts

@@ -1,16 +1,56 @@
+import type { GoogleGenerativeAIProviderOptions } from "@ai-sdk/google";
+import type { OpenAIResponsesProviderOptions } from "@ai-sdk/openai";
+import type { XaiProviderOptions } from "@ai-sdk/xai";
 import type { ModelMessage } from "ai";
 
 export interface Agent0Config {
-    apiKey: string;
-    baseUrl?: string;
+	apiKey: string;
+	baseUrl?: string;
+}
+
+/**
+ * Provider-specific options for reasoning/thinking configuration.
+ * Each provider has its own format for controlling reasoning behavior.
+ */
+export interface ProviderOptions {
+	/** OpenAI reasoning effort options */
+	openai?: OpenAIResponsesProviderOptions;
+	/** xAI reasoning effort options */
+	xai?: XaiProviderOptions;
+	/** Google/Vertex thinking configuration */
+	google?: GoogleGenerativeAIProviderOptions;
+}
+
+/**
+ * Model configuration overrides for runtime customization.
+ * Allows downstream applications to implement load balancing, fallbacks, and dynamic model switching.
+ */
+export interface ModelOverrides {
+	/** Override the model provider and name */
+	model?: {
+		provider_id?: string;
+		name?: string;
+	};
+	/** Override max output tokens */
+	maxOutputTokens?: number;
+	/** Override temperature */
+	temperature?: number;
+	/** Override max step count */
+	maxStepCount?: number;
+	/** Provider-specific options for reasoning/thinking configuration */
+	providerOptions?: ProviderOptions;
 }
 
 export interface RunOptions {
-    agentId: string;
-    variables?: Record<string, string>;
+	agentId: string;
+	variables?: Record<string, string>;
+	/** Runtime model overrides for load balancing, fallbacks, etc. */
+	overrides?: ModelOverrides;
+	/** Extra messages to append to the agent's prompt (used as-is, no variable substitution) */
+	extraMessages?: ModelMessage[];
 }
 
 export interface GenerateResponse {
-    messages: ModelMessage[];
-    text: string;
+	messages: ModelMessage[];
+	text: string;
 }