agent0-js 0.0.5 → 0.0.6

package/README.md

@@ -86,6 +86,18 @@ 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
 }
 ```
 
@@ -226,6 +238,78 @@ 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'
+        }
+      }
+    });
+  }
+}
+```
+
+### 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

@@ -3,9 +3,30 @@ export interface Agent0Config {
     apiKey: string;
     baseUrl?: string;
 }
+/**
+ * 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;
+}
 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.6",
   "description": "TypeScript SDK for Agent0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -5,9 +5,31 @@ export interface Agent0Config {
     baseUrl?: string;
 }
 
+/**
+ * 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;
+}
+
 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 {