@base44-preview/sdk 0.8.32-pr.205.168e407 → 0.8.32-pr.205.c20240d

package/dist/client.js

@@ -6,8 +6,7 @@ import { createSsoModule } from "./modules/sso.js";
 import { createConnectorsModule, createUserConnectorsModule, } from "./modules/connectors.js";
 import { getAccessToken } from "./utils/auth-utils.js";
 import { createFunctionsModule } from "./modules/functions.js";
-import { createAgentsModule } from "./modules/agents.js";
-import { createDynamicAgentsModule } from "./modules/dynamic-agents.js";
+import { createAgentsModule } from "./modules/agents/index.js";
 import { createAppLogsModule } from "./modules/app-logs.js";
 import { createUsersModule } from "./modules/users.js";
 import { RoomsSocket } from "./utils/socket-utils.js";
@@ -150,9 +149,6 @@ export function createClient(config) {
             appId,
             serverUrl,
             token,
-        }),
-        dynamicAgents: createDynamicAgentsModule({
-            serverUrl,
             getToken: () => token || getAccessToken() || undefined,
         }),
         appLogs: createAppLogsModule(axiosClient, appId),
@@ -196,9 +192,6 @@ export function createClient(config) {
             appId,
             serverUrl,
             token,
-        }),
-        dynamicAgents: createDynamicAgentsModule({
-            serverUrl,
             getToken: () => serviceToken,
         }),
         appLogs: createAppLogsModule(serviceRoleAxiosClient, appId),

package/dist/client.types.d.ts

@@ -4,10 +4,9 @@ import type { AuthModule } from "./modules/auth.types.js";
 import type { SsoModule } from "./modules/sso.types.js";
 import type { ConnectorsModule, UserConnectorsModule } from "./modules/connectors.types.js";
 import type { FunctionsModule } from "./modules/functions.types.js";
-import type { AgentsModule } from "./modules/agents.types.js";
+import type { AgentsModule } from "./modules/agents/agents.types.js";
 import type { AppLogsModule } from "./modules/app-logs.types.js";
 import type { AnalyticsModule } from "./modules/analytics.types.js";
-import type { DynamicAgentsModule } from "./modules/dynamic-agents.types.js";
 /**
  * Options for creating a Base44 client.
  */
@@ -86,8 +85,6 @@ export interface Base44Client {
     analytics: AnalyticsModule;
     /** {@link AppLogsModule | App logs module} for tracking app usage. */
     appLogs: AppLogsModule;
-    /** {@link DynamicAgentsModule | Dynamic agents module} for code-defined AI agents and tool loops. */
-    dynamicAgents: DynamicAgentsModule;
     /** {@link AuthModule | Auth module} for user authentication and management. */
     auth: AuthModule;
     /** {@link UserConnectorsModule | Connectors module} for app-user OAuth flows. */
@@ -129,8 +126,6 @@ export interface Base44Client {
         agents: AgentsModule;
         /** {@link AppLogsModule | App logs module} with elevated permissions. */
         appLogs: AppLogsModule;
-        /** {@link DynamicAgentsModule | Dynamic agents module} with elevated permissions. */
-        dynamicAgents: DynamicAgentsModule;
         /** {@link ConnectorsModule | Connectors module} for OAuth token retrieval. */
         connectors: ConnectorsModule;
         /** {@link EntitiesModule | Entities module} with elevated permissions. */

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { createClient, createClientFromRequest, type Base44Client, type CreateClientConfig, type CreateClientOptions } from "./client.js";
 import { Base44Error, type Base44ErrorJSON } from "./utils/axios-client.js";
 import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from "./utils/auth-utils.js";
-import { tool } from "./modules/dynamic-agents.js";
+import { tool } from "./modules/agents/tool.js";
 export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, tool, };
 export type { Base44Client, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, };
 export * from "./types.js";
@@ -9,10 +9,10 @@ export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityFilterOperat
 export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";
 export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
 export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./modules/functions.types.js";
-export type { AgentsModule, AgentName, AgentNameRegistry, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents.types.js";
+export type { AgentsModule, AgentName, AgentNameRegistry, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents/agents.types.js";
 export type { AppLogsModule } from "./modules/app-logs.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
 export type { ConnectorsModule, UserConnectorsModule, } from "./modules/connectors.types.js";
 export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";
-export type { Tool, JSONSchema, ChatMessage, Step, RunUsage, RunResult, RunInput, RunOptions, ToolChoice, AgentConfig, Agent, DynamicAgentsModule, } from "./modules/dynamic-agents.types.js";
+export type { Tool, JSONSchema, ChatMessage, Step, RunUsage, RunResult, RunInput, RunOptions, ToolChoice, AgentConfig, Agent, FinishReason, } from "./modules/agents/agents.types.js";
 export type { GetAccessTokenOptions, SaveAccessTokenOptions, RemoveAccessTokenOptions, GetLoginUrlOptions, } from "./utils/auth-utils.types.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 import { createClient, createClientFromRequest, } from "./client.js";
 import { Base44Error } from "./utils/axios-client.js";
 import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, } from "./utils/auth-utils.js";
-import { tool } from "./modules/dynamic-agents.js";
+import { tool } from "./modules/agents/tool.js";
 export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, tool, };
 export * from "./types.js";

package/dist/modules/{agents.types.d.ts → agents/agents.types.d.ts}

@@ -1,6 +1,317 @@
 import { AxiosInstance } from "axios";
-import { RoomsSocket } from "../utils/socket-utils.js";
-import { ModelFilterParams } from "../types.js";
+import { RoomsSocket } from "../../utils/socket-utils.js";
+import { ModelFilterParams } from "../../types.js";
+/**
+ * A JSON Schema object describing a tool's input parameters.
+ * Use the standard JSON Schema `object` shape: `{ type: "object", properties: {...}, required: [...] }`.
+ */
+export type JSONSchema = Record<string, unknown>;
+/**
+ * A tool an agent can call. Create one with {@linkcode tool | tool()}, or derive it from a
+ * resource with `.asTool()`.
+ */
+export interface Tool {
+    /** Natural-language description the model uses to decide when to call the tool. */
+    description: string;
+    /** JSON Schema for the tool's arguments. */
+    parameters: JSONSchema;
+    /** Runs the tool. Receives parsed arguments; returns any JSON-serializable value (or a string). */
+    execute: (args: any) => Promise<unknown> | unknown;
+}
+/**
+ * Why the agent run ended.
+ * `"max_steps"` is set by the SDK when the step cap is hit; all other values come from the model/normalization layer.
+ */
+export type FinishReason = "stop" | "length" | "tool-calls" | "content-filter" | "error" | "other";
+/** An OpenAI-shaped chat message accepted by {@linkcode Agent.run}. */
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | null;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    tool_call_id?: string;
+}
+/** One iteration of the agent loop: the tool calls the model made and their results. */
+export interface Step {
+    toolResults: Array<{
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+        result: string;
+    }>;
+    /** Token/credit usage of the model call that produced this step's tool calls. */
+    usage?: RunUsage;
+}
+/** Token/credit usage for a single model call or a sum across calls. `credits` is the Base44 gateway's `base44_credits`. */
+export interface RunUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    credits?: number;
+}
+/** Result of {@linkcode Agent.run}. */
+export interface RunResult {
+    /** The model's final text output. */
+    text: string;
+    /** The loop history (one entry per step that made tool calls). */
+    steps: Step[];
+    /**
+     * Why the run ended.
+     * Values come from the model/normalization layer (`"stop"`, `"length"`, `"tool-calls"`, `"content-filter"`, `"error"`, `"other"`)
+     * or from the SDK itself (`"max_steps"`, set when the step cap is reached).
+     */
+    finishReason: FinishReason | "max_steps";
+    /** Token and credit usage from the final completion. */
+    usage: RunUsage;
+    /** Summed across all model calls in the loop; `usage` is the final call only. */
+    totalUsage: RunUsage;
+    /** The raw final completion body, for advanced use. */
+    raw: unknown;
+}
+/** Input to {@linkcode Agent.run}: either a single prompt or a full message list. */
+export type RunInput = {
+    prompt: string;
+} | {
+    messages: ChatMessage[];
+};
+/**
+ * Per-run options passed as the second argument to {@linkcode Agent.run}.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 10_000);
+ *
+ * const result = await agent.run(
+ *   { prompt: "Summarize last month's sales." },
+ *   { abortSignal: controller.signal },
+ * );
+ * ```
+ */
+export interface RunOptions {
+    /** Abort the run (and the in-flight gateway request). */
+    abortSignal?: AbortSignal;
+}
+/** OpenAI-compatible tool choice. */
+export type ToolChoice = "auto" | "none" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
+/**
+ * Configuration for a code-defined agent passed to {@linkcode AgentsModule.create}.
+ *
+ * @example
+ * ```typescript
+ * const agent = base44.agents.create({
+ *   model: "claude_sonnet_4_6",
+ *   system: "You are a concise travel planner.",
+ *   tools: { getWeather, searchFlights },
+ *   maxSteps: 5,
+ * });
+ * ```
+ */
+export interface AgentConfig {
+    /**
+     * Model alias or vendor model ID to use for this agent.
+     *
+     * Use a Base44 model alias (e.g. `"claude_sonnet_4_6"`, `"gpt_4o"`, `"gpt_5_mini"`) or a
+     * fully-qualified vendor ID. Available aliases are listed in the Base44 console.
+     */
+    model: string;
+    /**
+     * System prompt prepended to every run.
+     *
+     * Provide instructions, persona, or constraints for the model.
+     * Omit to let the model run without a system message.
+     */
+    system?: string;
+    /**
+     * Tools the agent may call, keyed by their function name.
+     *
+     * Each value must be a {@linkcode Tool} object — use the {@linkcode tool | tool()} factory
+     * to create one, or use `.asTool()` on a resource such as an entity or function.
+     *
+     * @example
+     * ```typescript
+     * import { tool } from "@base44/sdk";
+     *
+     * const getWeather = tool({
+     *   description: "Get the current weather for a city.",
+     *   parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
+     *   execute: async ({ city }) => fetch(`/weather?city=${city}`).then(r => r.json()),
+     * });
+     *
+     * const agent = base44.agents.create({ model: "claude_sonnet_4_6", tools: { getWeather } });
+     * ```
+     */
+    tools?: Record<string, Tool>;
+    /**
+     * Maximum number of tool-calling loop iterations before the run stops.
+     *
+     * Each iteration is one round-trip to the model. If the model keeps calling tools
+     * and this limit is reached, the run ends with `finishReason: "max_steps"`.
+     * Defaults to `8`.
+     */
+    maxSteps?: number;
+    /**
+     * Sampling temperature passed to the model.
+     *
+     * Controls output randomness: lower values (e.g. `0`) produce more deterministic
+     * responses; higher values (e.g. `1`) increase variety. Omit to use the model default.
+     *
+     * Note: GPT-5 series models only accept `temperature: 1`.
+     */
+    temperature?: number;
+    /**
+     * JSON Schema to constrain the model's output to structured JSON.
+     *
+     * When set, the request is sent with `response_format: { type: "json_schema", … }`.
+     * The model's response will be valid JSON matching the schema; access it by parsing
+     * `RunResult.text`.
+     * The schema is sent with strict JSON-schema mode, so it should have `additionalProperties: false` and list every property in `required` (otherwise the provider may reject it).
+     *
+     * @example
+     * ```typescript
+     * const agent = base44.agents.create({
+     *   model: "claude_sonnet_4_6",
+     *   responseFormat: {
+     *     type: "object",
+     *     properties: { summary: { type: "string" }, score: { type: "number" } },
+     *     required: ["summary", "score"],
+     *   },
+     * });
+     * const { text } = await agent.run({ prompt: "Rate this product description." });
+     * const { summary, score } = JSON.parse(text);
+     * ```
+     */
+    responseFormat?: JSONSchema;
+    /**
+     * Controls whether and which tool the model must call.
+     *
+     * - `"auto"` (default when tools are provided): the model decides.
+     * - `"none"`: the model must not call any tool.
+     * - `"required"`: the model must call at least one tool.
+     * - `{ type: "function", function: { name } }`: force a specific tool.
+     */
+    toolChoice?: ToolChoice;
+}
+/**
+ * A reusable code-defined agent returned by {@linkcode AgentsModule.create}.
+ *
+ * An agent runs a multi-step tool-calling loop: it sends messages to the model,
+ * executes any tool calls the model requests, feeds the results back, and repeats
+ * until the model produces a final answer or `maxSteps` is reached.
+ *
+ * @example
+ * ```typescript
+ * const agent = base44.agents.create({
+ *   model: "claude_sonnet_4_6",
+ *   system: "You are a concise travel planner.",
+ *   tools: { getWeather },
+ * });
+ *
+ * const { text } = await agent.run({ prompt: "What's the weather like in Tel Aviv?" });
+ * console.log(text);
+ * ```
+ */
+export interface Agent {
+    /**
+     * Runs the agent's tool-calling loop to completion and returns the final result.
+     *
+     * Builds an initial message list from `input`, then repeatedly calls the model,
+     * executes any tool calls, and feeds results back until the model stops or
+     * `maxSteps` (from {@linkcode AgentConfig}) is reached.
+     *
+     * Tool errors are fed back to the model as tool results rather than thrown, so
+     * the model can recover or explain the failure.
+     *
+     * @param input - The run input: either `{ prompt: string }` for a simple user
+     *   message, or `{ messages: ChatMessage[] }` to supply a full conversation history.
+     * @param options - Optional {@linkcode RunOptions} (e.g. an `AbortSignal`).
+     * @returns Promise resolving to a {@linkcode RunResult} containing the model's
+     *   final text, per-step tool call history, finish reason, and token/credit usage.
+     *
+     * @example
+     * ```typescript
+     * // Simple prompt
+     * const { text, usage } = await agent.run({ prompt: "Plan a one-day trip to Haifa." });
+     * console.log(text);
+     * console.log(`Credits used: ${usage.credits}`);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Supply a full message history
+     * const { text } = await agent.run({
+     *   messages: [
+     *     { role: "user", content: "What is the capital of France?" },
+     *     { role: "assistant", content: "Paris." },
+     *     { role: "user", content: "And what is the population?" },
+     *   ],
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cancel a long-running run
+     * const controller = new AbortController();
+     * setTimeout(() => controller.abort(), 15_000);
+     * const { text } = await agent.run(
+     *   { prompt: "Summarize all open support tickets." },
+     *   { abortSignal: controller.signal },
+     * );
+     * ```
+     */
+    run(input: RunInput, options?: RunOptions): Promise<RunResult>;
+    /**
+     * Wraps this agent as a {@linkcode Tool} so another agent can call it as a sub-agent.
+     *
+     * The returned tool exposes a single `prompt` parameter. When called, it invokes
+     * {@linkcode Agent.run | run()} with that prompt and returns the text result.
+     * Use this to build agent hierarchies where a coordinator agent delegates tasks
+     * to specialized sub-agents.
+     *
+     * @param opts - Options for the tool wrapper.
+     * @param opts.description - Required. Natural-language description the calling
+     *   model uses to decide when to invoke this sub-agent.
+     * @param opts.name - Optional display name for the tool. Defaults to the
+     *   agent config's model alias when omitted.
+     * @returns A {@linkcode Tool} that can be passed in another agent's `tools` map.
+     * @note The sub-agent runs independently — the parent's `abortSignal` is not propagated and
+     *   the sub-agent's token/credit usage is not included in the parent's `totalUsage`.
+     *
+     * @example
+     * ```typescript
+     * const researchAgent = base44.agents.create({
+     *   model: "claude_sonnet_4_6",
+     *   tools: { webSearch },
+     * });
+     *
+     * const writerAgent = base44.agents.create({
+     *   model: "claude_sonnet_4_6",
+     *   tools: {
+     *     research: researchAgent.asTool({
+     *       description: "Search the web and return a research summary.",
+     *     }),
+     *   },
+     * });
+     *
+     * const { text } = await writerAgent.run({ prompt: "Write a blog post about coral reefs." });
+     * ```
+     */
+    asTool(opts: {
+        name?: string;
+        description: string;
+    }): Tool;
+}
 /**
  * Registry of agent names. The [`types generate`](/developers/references/cli/commands/types-generate) command fills this registry, then [`AgentName`](#agentname) resolves to a union of the keys.
  */
@@ -162,6 +473,8 @@ export interface AgentsModuleConfig {
     serverUrl?: string;
     /** Authentication token */
     token?: string;
+    /** Returns the current bearer token at call time (thunk — never a captured string). Used by `create()`. */
+    getToken?: () => string | undefined;
 }
 /**
  * Agents module for managing AI agent conversations.
@@ -356,6 +669,27 @@ export interface AgentsModule {
      * ```
      */
     subscribeToConversation(conversationId: string, onUpdate?: (conversation: AgentConversation) => void): () => void;
+    /**
+     * Creates a code-defined agent: you specify the model, system prompt, and tools in code,
+     * and the SDK runs the tool-calling loop against the Base44 AI Gateway.
+     *
+     * Returns a reusable {@linkcode Agent} you can {@linkcode Agent.run | run} or expose to
+     * another agent as a tool with {@linkcode Agent.asTool | asTool}.
+     *
+     * @param config - Model alias, optional system prompt, tools, and step limit.
+     * @returns A reusable {@linkcode Agent} with {@linkcode Agent.run | run()} and {@linkcode Agent.asTool | asTool()}.
+     *
+     * @example
+     * ```typescript
+     * const agent = base44.agents.create({
+     *   model: "claude_sonnet_4_6",
+     *   system: "You plan trips.",
+     *   tools: { getWeather },
+     * });
+     * const { text } = await agent.run({ prompt: "Plan a day in Haifa." });
+     * ```
+     */
+    create(config: AgentConfig): Agent;
     /**
      * Gets WhatsApp connection URL for an agent.
      *

package/dist/modules/agents/gateway.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Minimal transport shape used by provider adapters to send completions requests.
+ * @internal
+ */
+export type GatewayTransport = {
+    complete(body: Record<string, unknown>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+};
+/** @internal */
+export interface GatewayConfig {
+    serverUrl: string;
+    /** Returns the current bearer token at call time (thunk — never a captured string). */
+    getToken: () => string | undefined;
+}
+/**
+ * Resolves the AI Gateway connection from a client config.
+ * @internal
+ */
+export declare function resolveConnection(config: GatewayConfig): {
+    baseURL: string;
+    apiKey: string;
+};
+/**
+ * Creates the gateway transport — owns the single HTTP call to the OpenAI-compatible
+ * `/chat/completions` endpoint.
+ * @internal
+ */
+export declare function createGatewayTransport(config: GatewayConfig): {
+    complete(body: Record<string, unknown>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+};

package/dist/modules/{ai-gateway.js → agents/gateway.js}

@@ -1,4 +1,4 @@
-import { Base44Error } from "../utils/axios-client.js";
+import { Base44Error } from "../../utils/axios-client.js";
 /**
  * Resolves the AI Gateway connection from a client config.
  * @internal
@@ -13,9 +13,8 @@ export function resolveConnection(config) {
     };
 }
 /**
- * Creates the gateway transport. Owns the single HTTP call to the OpenAI-compatible
- * `/chat/completions` endpoint. Shaped so a streaming `.stream()` method can be added
- * later without changing callers of `.complete()`.
+ * Creates the gateway transport — owns the single HTTP call to the OpenAI-compatible
+ * `/chat/completions` endpoint.
  * @internal
  */
 export function createGatewayTransport(config) {

package/dist/modules/{agents.d.ts → agents/index.d.ts}

@@ -1,2 +1,2 @@
 import { AgentsModule, AgentsModuleConfig } from "./agents.types.js";
-export declare function createAgentsModule({ axios, getSocket, appId, serverUrl, token, }: AgentsModuleConfig): AgentsModule;
+export declare function createAgentsModule({ axios, getSocket, appId, serverUrl, token, getToken, }: AgentsModuleConfig): AgentsModule;

package/dist/modules/{agents.js → agents/index.js}

@@ -1,5 +1,12 @@
-import { getAccessToken } from "../utils/auth-utils.js";
-export function createAgentsModule({ axios, getSocket, appId, serverUrl, token, }) {
+import { getAccessToken } from "../../utils/auth-utils.js";
+import { createGatewayTransport } from "./gateway.js";
+import { openAICompatibleProvider } from "./providers/openai-compatible.js";
+import { createAgent } from "./loop.js";
+export function createAgentsModule({ axios, getSocket, appId, serverUrl, token, getToken, }) {
+    const model = openAICompatibleProvider(createGatewayTransport({
+        serverUrl: serverUrl !== null && serverUrl !== void 0 ? serverUrl : "",
+        getToken: getToken !== null && getToken !== void 0 ? getToken : (() => token),
+    }));
     const baseURL = `/apps/${appId}/agents`;
     // Track active conversations
     const currentConversations = {};
@@ -85,5 +92,6 @@ export function createAgentsModule({ axios, getSocket, appId, serverUrl, token,
         subscribeToConversation,
         getWhatsAppConnectURL,
         getTelegramConnectURL,
+        create(config) { return createAgent(config, model); },
     };
 }

package/dist/modules/agents/loop.d.ts

@@ -0,0 +1,4 @@
+import type { Agent, AgentConfig } from "./agents.types.js";
+import type { LanguageModel } from "./provider.js";
+/** Creates an Agent from a config and a language model. @internal */
+export declare function createAgent(agentConfig: AgentConfig, model: LanguageModel): Agent;