agent0-js 0.0.11 → 0.0.13

package/README.md

@@ -73,6 +73,7 @@ const client = new Agent0({
 |--------|------|----------|---------|-------------|
 | `apiKey` | `string` | Yes | - | Your Agent0 API key |
 | `baseUrl` | `string` | No | `https://app.agent0.com` | The base URL for the Agent0 API |
+| `environment` | `'staging' \| 'production'` | No | `'production'` | Default environment for all runs (can be overridden per-run) |
 
 ## Methods
 
@@ -85,9 +86,17 @@ Execute an agent and get the complete response.
 ```typescript
 interface RunOptions {
   agentId: string;                    // The ID of the agent to run
+  environment?: 'staging' | 'production'; // Environment to run (default: 'production')
   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
+  extraTools?: CustomTool[];          // Additional custom tools to add at runtime
+}
+
+interface CustomTool {
+  title: string;                       // Unique title for the tool (lowercase with underscores)
+  description: string;                // Description of what the tool does
+  inputSchema?: Record<string, unknown>; // JSON Schema for the tool's parameters
 }
 
 interface ModelOverrides {
@@ -447,6 +456,54 @@ const response = await client.generate({
 // Prompt becomes: "Hello Sarah, let's talk about machine learning"
 ```
 
+### Staging and Production Environments
+
+Agent0 supports deploying different versions of your agent to staging and production environments. This allows you to test changes before rolling them out to production.
+
+The environment can be set at two levels with the following priority:
+1. **Run-level** (highest priority): Set `environment` in `generate()` or `stream()` options
+2. **Constructor-level**: Set `environment` when creating the `Agent0` client
+3. **Default**: Falls back to `'production'`
+
+```typescript
+// Set default environment at constructor level
+const stagingClient = new Agent0({
+  apiKey: process.env.AGENT0_API_KEY!,
+  environment: 'staging' // All runs will use staging by default
+});
+
+// This uses 'staging' from constructor
+const response1 = await stagingClient.generate({
+  agentId: 'agent_123',
+  variables: { name: 'Test User' }
+});
+
+// Override constructor setting at run level
+const response2 = await stagingClient.generate({
+  agentId: 'agent_123',
+  environment: 'production', // Overrides the constructor's 'staging'
+  variables: { name: 'Real User' }
+});
+
+// Default client (no constructor environment) uses 'production'
+const defaultClient = new Agent0({
+  apiKey: process.env.AGENT0_API_KEY!
+});
+
+// This uses 'production' (the default)
+const response3 = await defaultClient.generate({
+  agentId: 'agent_123',
+  variables: { name: 'User' }
+});
+
+// Run-level environment takes precedence
+const response4 = await defaultClient.generate({
+  agentId: 'agent_123',
+  environment: 'staging',
+  variables: { name: 'Test User' }
+});
+```
+
 ### Model Overrides
 
 The `overrides` option allows you to dynamically configure the model at runtime. This is useful for:
@@ -592,6 +649,95 @@ const response = await client.generate({
 });
 ```
 
+### Custom Tools (extraTools)
+
+The `extraTools` option allows you to add custom tool definitions at runtime. These tools are merged with any tools defined in the agent configuration. Custom tools enable function calling without requiring an MCP server - the LLM will generate tool calls, but **execution must be handled externally** by your application.
+
+This is useful for:
+- **Dynamic Tool Injection**: Add context-specific tools at runtime
+- **Function Calling Patterns**: Define tools that your application will execute
+- **Hybrid Agents**: Combine MCP server tools with custom tools
+
+```typescript
+// Define custom tools for function calling
+const response = await client.generate({
+  agentId: 'agent_123',
+  extraTools: [
+    {
+      title: 'get_weather',
+      description: 'Get the current weather for a location',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          location: {
+            type: 'string',
+            description: 'City name or zip code'
+          },
+          units: {
+            type: 'string',
+            enum: ['celsius', 'fahrenheit'],
+            description: 'Temperature units'
+          }
+        },
+        required: ['location']
+      }
+    },
+    {
+      title: 'search_database',
+      description: 'Search the company database for information',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'Search query' },
+          limit: { type: 'number', description: 'Max results to return' }
+        },
+        required: ['query']
+      }
+    }
+  ]
+});
+
+// The response may contain tool calls that your app needs to handle
+for (const message of response.messages) {
+  if (message.role === 'assistant') {
+    for (const part of message.content) {
+      if (part.type === 'tool-call') {
+        console.log('Tool called:', part.toolName);
+        console.log('Arguments:', part.args);
+        // Execute the tool and provide results back to the agent
+      }
+    }
+  }
+}
+```
+
+**Streaming with Custom Tools:**
+
+```typescript
+const stream = client.stream({
+  agentId: 'agent_123',
+  extraTools: [
+    {
+      title: 'lookup_user',
+      description: 'Look up user information by ID',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          userId: { type: 'string' }
+        },
+        required: ['userId']
+      }
+    }
+  ]
+});
+
+for await (const chunk of stream) {
+  if (chunk.type === 'tool-call') {
+    console.log(`Tool ${chunk.toolName} called with:`, chunk.args);
+  }
+}
+```
+
 ### Error Handling
 
 ```typescript

package/dist/index.d.ts

@@ -24,4 +24,4 @@ export declare class Agent0 {
      */
     embedMany(options: EmbedManyOptions): Promise<EmbedManyResponse>;
 }
-export type { Agent0Config, EmbedManyOptions, EmbedManyResponse, EmbedModel, EmbedOptions, EmbedResponse, GenerateResponse, ModelOverrides, ProviderOptions, RunOptions, } from "./types";
+export type { Agent0Config, CustomTool, EmbedManyOptions, EmbedManyResponse, EmbedModel, EmbedOptions, EmbedResponse, Environment, GenerateResponse, ModelOverrides, ProviderOptions, RunOptions, } from "./types";

package/dist/index.js

@@ -27,9 +27,11 @@ class Agent0 {
     async generate(options) {
         const response = await this.fetchApi("/api/v1/run", {
             agent_id: options.agentId,
+            environment: options.environment,
             variables: options.variables,
             overrides: options.overrides,
             extra_messages: options.extraMessages,
+            extra_tools: options.extraTools,
             stream: false,
         });
         return await response.json();
@@ -37,9 +39,11 @@ class Agent0 {
     async *stream(options) {
         const response = await this.fetchApi("/api/v1/run", {
             agent_id: options.agentId,
+            environment: options.environment,
             variables: options.variables,
             overrides: options.overrides,
             extra_messages: options.extraMessages,
+            extra_tools: options.extraTools,
             stream: true,
         });
         if (!response.body) {

package/dist/types.d.ts

@@ -37,13 +37,36 @@ export interface ModelOverrides {
     /** Provider-specific options for reasoning/thinking configuration */
     providerOptions?: ProviderOptions;
 }
+/**
+ * A custom tool defined at runtime.
+ * Custom tools have title, description, and inputSchema but no execute function.
+ * The LLM will generate tool calls for these, but execution must be handled externally.
+ */
+export interface CustomTool {
+    /** Unique title for the tool (lowercase with underscores recommended) */
+    title: string;
+    /** Description of what the tool does - helps the AI understand when to use it */
+    description: string;
+    /** JSON Schema defining the parameters this tool accepts */
+    inputSchema?: Record<string, unknown>;
+}
+/**
+ * Environment to run the agent in.
+ * - 'staging': Run the staging-deployed version of the agent
+ * - 'production': Run the production-deployed version of the agent (default)
+ */
+export type Environment = "staging" | "production";
 export interface RunOptions {
     agentId: string;
+    /** Environment to run ('staging' or 'production'). Defaults to 'production'. */
+    environment?: Environment;
     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[];
+    /** Additional custom tools to add at runtime. These are merged with any tools defined in the agent. */
+    extraTools?: CustomTool[];
 }
 export interface GenerateResponse {
     messages: ModelMessage[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent0-js",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "TypeScript SDK for Agent0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -5,6 +5,7 @@ import type {
 	EmbedManyResponse,
 	EmbedOptions,
 	EmbedResponse,
+	Environment,
 	GenerateResponse,
 	RunOptions,
 } from "./types";
@@ -12,10 +13,19 @@ import type {
 export class Agent0 {
 	private apiKey: string;
 	private baseUrl: string;
+	private environment?: Environment;
 
 	constructor(config: Agent0Config) {
 		this.apiKey = config.apiKey;
 		this.baseUrl = config.baseUrl || "https://app.agent0.com"; // Default URL, can be overridden
+		this.environment = config.environment;
+	}
+
+	/**
+	 * Resolve the environment to use: run-level > constructor-level > default 'production'
+	 */
+	private resolveEnvironment(runEnvironment?: Environment): Environment {
+		return runEnvironment ?? this.environment ?? "production";
 	}
 
 	private async fetchApi(endpoint: string, body: unknown): Promise<Response> {
@@ -46,9 +56,11 @@ export class Agent0 {
 	async generate(options: RunOptions): Promise<GenerateResponse> {
 		const response = await this.fetchApi("/api/v1/run", {
 			agent_id: options.agentId,
+			environment: this.resolveEnvironment(options.environment),
 			variables: options.variables,
 			overrides: options.overrides,
 			extra_messages: options.extraMessages,
+			extra_tools: options.extraTools,
 			stream: false,
 		});
 
@@ -60,9 +72,11 @@ export class Agent0 {
 	): AsyncGenerator<TextStreamPart<ToolSet>, void, unknown> {
 		const response = await this.fetchApi("/api/v1/run", {
 			agent_id: options.agentId,
+			environment: this.resolveEnvironment(options.environment),
 			variables: options.variables,
 			overrides: options.overrides,
 			extra_messages: options.extraMessages,
+			extra_tools: options.extraTools,
 			stream: true,
 		});
 
@@ -134,11 +148,13 @@ export class Agent0 {
 // Re-export types for convenience
 export type {
 	Agent0Config,
+	CustomTool,
 	EmbedManyOptions,
 	EmbedManyResponse,
 	EmbedModel,
 	EmbedOptions,
 	EmbedResponse,
+	Environment,
 	GenerateResponse,
 	ModelOverrides,
 	ProviderOptions,

package/src/types.ts

@@ -6,6 +6,8 @@ import type { embed, embedMany, ModelMessage } from "ai";
 export interface Agent0Config {
 	apiKey: string;
 	baseUrl?: string;
+	/** Default environment to use for all runs. Can be overridden per-run. Defaults to 'production'. */
+	environment?: Environment;
 }
 
 /**
@@ -41,13 +43,38 @@ export interface ModelOverrides {
 	providerOptions?: ProviderOptions;
 }
 
+/**
+ * A custom tool defined at runtime.
+ * Custom tools have title, description, and inputSchema but no execute function.
+ * The LLM will generate tool calls for these, but execution must be handled externally.
+ */
+export interface CustomTool {
+	/** Unique title for the tool (lowercase with underscores recommended) */
+	title: string;
+	/** Description of what the tool does - helps the AI understand when to use it */
+	description: string;
+	/** JSON Schema defining the parameters this tool accepts */
+	inputSchema?: Record<string, unknown>;
+}
+
+/**
+ * Environment to run the agent in.
+ * - 'staging': Run the staging-deployed version of the agent
+ * - 'production': Run the production-deployed version of the agent (default)
+ */
+export type Environment = "staging" | "production";
+
 export interface RunOptions {
 	agentId: string;
+	/** Environment to run ('staging' or 'production'). Defaults to 'production'. */
+	environment?: Environment;
 	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[];
+	/** Additional custom tools to add at runtime. These are merged with any tools defined in the agent. */
+	extraTools?: CustomTool[];
 }
 
 export interface GenerateResponse {