@base44-preview/sdk 0.8.32-pr.203.8313142 → 0.8.32-pr.205.36088fe

package/dist/client.js

@@ -6,7 +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 { 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";
@@ -149,6 +149,7 @@ export function createClient(config) {
             appId,
             serverUrl,
             token,
+            getToken: () => token || getAccessToken() || undefined,
         }),
         appLogs: createAppLogsModule(axiosClient, appId),
         users: createUsersModule(axiosClient, appId),
@@ -191,6 +192,7 @@ export function createClient(config) {
             appId,
             serverUrl,
             token,
+            getToken: () => serviceToken,
         }),
         appLogs: createAppLogsModule(serviceRoleAxiosClient, appId),
         cleanup: () => {

package/dist/client.types.d.ts

@@ -4,7 +4,7 @@ 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";
 /**

package/dist/index.d.ts

@@ -1,16 +1,18 @@
 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";
-export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
+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";
 export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityFilterOperators, EntityFilterQuery, EntityFilterValue, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
 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, } from "./modules/agents/agents.types.js";
 export type { GetAccessTokenOptions, SaveAccessTokenOptions, RemoveAccessTokenOptions, GetLoginUrlOptions, } from "./utils/auth-utils.types.js";

package/dist/index.js

@@ -1,5 +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";
-export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
+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,305 @@
 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;
+}
+/** An OpenAI-shaped chat message used internally and 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: `"stop"` (model finished), `"tool_calls"`, or `"max_steps"`. */
+    finishReason: string;
+    /** 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`.
+     *
+     * @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.
+     *
+     * @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 +461,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 +657,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,24 @@
+/** @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/agents/gateway.js

@@ -0,0 +1,41 @@
+import { Base44Error } from "../../utils/axios-client.js";
+/**
+ * Resolves the AI Gateway connection from a client config.
+ * @internal
+ */
+export function resolveConnection(config) {
+    var _a;
+    const { serverUrl, getToken } = config;
+    // No appId in the path: the gateway resolves the app by request Host.
+    return {
+        baseURL: `${serverUrl}/api/ai/unified/v1`,
+        apiKey: (_a = getToken()) !== null && _a !== void 0 ? _a : "",
+    };
+}
+/**
+ * Creates the gateway transport — owns the single HTTP call to the OpenAI-compatible
+ * `/chat/completions` endpoint.
+ * @internal
+ */
+export function createGatewayTransport(config) {
+    return {
+        async complete(body, opts = {}) {
+            const { baseURL, apiKey } = resolveConnection(config);
+            const res = await fetch(`${baseURL}/chat/completions`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal: opts.signal,
+            });
+            const json = await res.json().catch(() => null);
+            if (!res.ok) {
+                const err = (json && json.error) || {};
+                throw new Base44Error(err.message || `AI Gateway request failed with status ${res.status}`, res.status, err.code || err.type || "ai_gateway_error", json, null);
+            }
+            return json;
+        },
+    };
+}

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;

package/dist/modules/agents/loop.js

@@ -0,0 +1,146 @@
+const DEFAULT_MAX_STEPS = 8;
+function safeParseJson(json) {
+    try {
+        return JSON.parse(json || "{}");
+    }
+    catch (_a) {
+        return {};
+    }
+}
+function inputToMessages(input) {
+    if (!("messages" in input)) {
+        return [{ role: "user", content: input.prompt }];
+    }
+    // Map the public ChatMessage[] 1:1 to neutral ModelMessage[] by role.
+    return input.messages.map((message) => {
+        var _a, _b, _c;
+        if (message.role === "system") {
+            return { role: "system", content: typeof message.content === "string" ? message.content : "" };
+        }
+        if (message.role === "user") {
+            return { role: "user", content: typeof message.content === "string" ? message.content : "" };
+        }
+        if (message.role === "assistant") {
+            const toolCalls = (_a = message.tool_calls) === null || _a === void 0 ? void 0 : _a.map((call) => ({
+                id: call.id,
+                name: call.function.name,
+                args: safeParseJson(call.function.arguments),
+            }));
+            return {
+                role: "assistant",
+                content: (_b = message.content) !== null && _b !== void 0 ? _b : undefined,
+                toolCalls: (toolCalls === null || toolCalls === void 0 ? void 0 : toolCalls.length) ? toolCalls : undefined,
+            };
+        }
+        // tool
+        return {
+            role: "tool",
+            toolCallId: (_c = message.tool_call_id) !== null && _c !== void 0 ? _c : "",
+            result: typeof message.content === "string" ? message.content : "",
+        };
+    });
+}
+function stringifyToolResult(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function sumUsage(accumulated, next) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    return {
+        inputTokens: ((_a = accumulated.inputTokens) !== null && _a !== void 0 ? _a : 0) + ((_b = next.inputTokens) !== null && _b !== void 0 ? _b : 0),
+        outputTokens: ((_c = accumulated.outputTokens) !== null && _c !== void 0 ? _c : 0) + ((_d = next.outputTokens) !== null && _d !== void 0 ? _d : 0),
+        totalTokens: ((_e = accumulated.totalTokens) !== null && _e !== void 0 ? _e : 0) + ((_f = next.totalTokens) !== null && _f !== void 0 ? _f : 0),
+        credits: ((_g = accumulated.credits) !== null && _g !== void 0 ? _g : 0) + ((_h = next.credits) !== null && _h !== void 0 ? _h : 0),
+    };
+}
+/** Creates an Agent from a config and a language model. @internal */
+export function createAgent(agentConfig, model) {
+    var _a;
+    const maxSteps = (_a = agentConfig.maxSteps) !== null && _a !== void 0 ? _a : DEFAULT_MAX_STEPS;
+    const tools = agentConfig.tools;
+    const agent = {
+        async run(input, options = {}) {
+            var _a, _b, _c, _d;
+            const messages = [
+                ...(agentConfig.system ? [{ role: "system", content: agentConfig.system }] : []),
+                ...inputToMessages(input),
+            ];
+            const steps = [];
+            let totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, credits: 0 };
+            // The most recent model call; referenced after the loop for the max-steps return.
+            let modelResult = null;
+            for (let step = 0; step < maxSteps; step++) {
+                modelResult = await model.generate({
+                    model: agentConfig.model,
+                    messages,
+                    tools,
+                    temperature: agentConfig.temperature,
+                    toolChoice: agentConfig.toolChoice,
+                    responseFormat: agentConfig.responseFormat,
+                    signal: options.abortSignal,
+                });
+                totalUsage = sumUsage(totalUsage, (_a = modelResult.usage) !== null && _a !== void 0 ? _a : {});
+                messages.push({
+                    role: "assistant",
+                    content: modelResult.text || undefined,
+                    toolCalls: modelResult.toolCalls.length ? modelResult.toolCalls : undefined,
+                });
+                // No tool calls: the model is done — return its final answer.
+                if (modelResult.toolCalls.length === 0) {
+                    return {
+                        text: modelResult.text,
+                        steps,
+                        finishReason: modelResult.finishReason,
+                        usage: modelResult.usage,
+                        totalUsage,
+                        raw: modelResult.raw,
+                    };
+                }
+                // Execute each requested tool and feed the result back for the next turn.
+                const toolResults = [];
+                for (const call of modelResult.toolCalls) {
+                    const matchedTool = tools === null || tools === void 0 ? void 0 : tools[call.name];
+                    let resultContent;
+                    if (!matchedTool) {
+                        resultContent = `Error: tool "${call.name}" is not available.`;
+                    }
+                    else {
+                        try {
+                            resultContent = stringifyToolResult(await matchedTool.execute(call.args));
+                        }
+                        catch (error) {
+                            const message = error === null || error === void 0 ? void 0 : error.message;
+                            resultContent = `Error: ${message !== null && message !== void 0 ? message : String(error)}`;
+                        }
+                    }
+                    messages.push({ role: "tool", toolCallId: call.id, toolName: call.name, result: resultContent });
+                    toolResults.push({ toolCallId: call.id, toolName: call.name, args: call.args, result: resultContent });
+                }
+                steps.push({ toolResults, usage: modelResult.usage });
+            }
+            // Loop exhausted without a final (tool-free) answer.
+            return {
+                text: (_b = modelResult === null || modelResult === void 0 ? void 0 : modelResult.text) !== null && _b !== void 0 ? _b : "",
+                steps,
+                finishReason: "max_steps",
+                usage: (_c = modelResult === null || modelResult === void 0 ? void 0 : modelResult.usage) !== null && _c !== void 0 ? _c : {},
+                totalUsage,
+                raw: (_d = modelResult === null || modelResult === void 0 ? void 0 : modelResult.raw) !== null && _d !== void 0 ? _d : null,
+            };
+        },
+        asTool(toolOpts) {
+            return {
+                description: toolOpts.description,
+                parameters: {
+                    type: "object",
+                    properties: { prompt: { type: "string", description: "What to ask the sub-agent." } },
+                    required: ["prompt"],
+                },
+                execute: async (args) => {
+                    const result = await agent.run({ prompt: args.prompt });
+                    return result.text;
+                },
+            };
+        },
+    };
+    return agent;
+}

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

@@ -0,0 +1,55 @@
+import type { Tool, ToolChoice, JSONSchema, RunUsage } from "./agents.types.js";
+/** A parsed tool call the model wants to make. Args are already parsed (object), never a JSON string. @internal */
+export interface ModelToolCall {
+    id: string;
+    name: string;
+    args: unknown;
+}
+/**
+ * Neutral, provider-agnostic conversation message. `system` is a message role here;
+ * each provider adapter places it where its wire format expects. `content` is a string.
+ * @internal
+ */
+export type ModelMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string;
+} | {
+    role: "assistant";
+    content?: string;
+    toolCalls?: ModelToolCall[];
+} | {
+    role: "tool";
+    toolCallId: string;
+    toolName?: string;
+    result: string;
+};
+/** Finish reasons normalized across providers. @internal */
+export type FinishReason = "stop" | "length" | "tool-calls" | "content-filter" | "error" | "other";
+/** A request to a language model. @internal */
+export interface GenerateRequest {
+    model: string;
+    messages: ModelMessage[];
+    tools?: Record<string, Tool>;
+    temperature?: number;
+    toolChoice?: ToolChoice;
+    responseFormat?: JSONSchema;
+    signal?: AbortSignal;
+}
+/** Normalized model output. @internal */
+export interface GenerateResult {
+    text: string;
+    toolCalls: ModelToolCall[];
+    finishReason: FinishReason;
+    usage: RunUsage;
+    /** Opaque vendor-specific extras (cache control, reasoning, safety, …). @internal */
+    providerMetadata?: Record<string, unknown>;
+    /** The raw vendor response, for advanced use. */
+    raw: unknown;
+}
+/** The provider seam. Adapters translate neutral <-> vendor wire. @internal */
+export interface LanguageModel {
+    generate(req: GenerateRequest): Promise<GenerateResult>;
+}

package/dist/modules/agents/provider.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/agents/providers/openai-compatible.d.ts

@@ -0,0 +1,13 @@
+import type { LanguageModel } from "../provider.js";
+interface GatewayTransport {
+    complete(body: Record<string, unknown>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<any>;
+}
+/**
+ * OpenAI-compatible provider: speaks the Chat Completions wire format over the Base44
+ * gateway transport.
+ * @internal
+ */
+export declare function openAICompatibleProvider(transport: GatewayTransport): LanguageModel;
+export {};

package/dist/modules/agents/providers/openai-compatible.js

@@ -0,0 +1,110 @@
+function serializeTools(tools) {
+    if (!tools)
+        return undefined;
+    const entries = Object.entries(tools);
+    if (entries.length === 0)
+        return undefined;
+    return entries.map(([name, toolDef]) => ({
+        type: "function",
+        function: { name, description: toolDef.description, parameters: toolDef.parameters },
+    }));
+}
+/** Neutral messages -> Chat Completions messages. System role in the array is passed through. */
+function toChatMessages(messages) {
+    var _a, _b;
+    const chatMessages = [];
+    for (const message of messages) {
+        if (message.role === "system") {
+            chatMessages.push({ role: "system", content: message.content });
+        }
+        else if (message.role === "user") {
+            chatMessages.push({ role: "user", content: message.content });
+        }
+        else if (message.role === "assistant") {
+            const assistantMessage = { role: "assistant", content: (_a = message.content) !== null && _a !== void 0 ? _a : null };
+            if ((_b = message.toolCalls) === null || _b === void 0 ? void 0 : _b.length) {
+                assistantMessage.tool_calls = message.toolCalls.map((call) => {
+                    var _a;
+                    return ({
+                        id: call.id,
+                        type: "function",
+                        function: { name: call.name, arguments: JSON.stringify((_a = call.args) !== null && _a !== void 0 ? _a : {}) },
+                    });
+                });
+            }
+            chatMessages.push(assistantMessage);
+        }
+        else {
+            chatMessages.push({ role: "tool", tool_call_id: message.toolCallId, content: message.result });
+        }
+    }
+    return chatMessages;
+}
+/** Build the Chat Completions body using the param whitelist (rejected params can never appear). */
+function buildChatCompletionsBody(req) {
+    const body = { model: req.model, messages: toChatMessages(req.messages) };
+    if (req.temperature !== undefined)
+        body.temperature = req.temperature;
+    if (req.toolChoice !== undefined)
+        body.tool_choice = req.toolChoice;
+    if (req.responseFormat !== undefined) {
+        body.response_format = { type: "json_schema", json_schema: { name: "response", schema: req.responseFormat, strict: true } };
+    }
+    const tools = serializeTools(req.tools);
+    if (tools)
+        body.tools = tools;
+    return body;
+}
+const FINISH = {
+    stop: "stop", length: "length", tool_calls: "tool-calls", content_filter: "content-filter",
+};
+function normalizeFinish(raw, hasToolCalls) {
+    if (hasToolCalls)
+        return "tool-calls";
+    if (raw !== undefined && FINISH[raw])
+        return FINISH[raw];
+    return "other";
+}
+function parseChatCompletion(raw) {
+    var _a, _b, _c, _d, _e;
+    const choice = (_a = raw === null || raw === void 0 ? void 0 : raw.choices) === null || _a === void 0 ? void 0 : _a[0];
+    const message = (_b = choice === null || choice === void 0 ? void 0 : choice.message) !== null && _b !== void 0 ? _b : {};
+    const toolCalls = ((_c = message.tool_calls) !== null && _c !== void 0 ? _c : []).map((call) => {
+        var _a, _b;
+        let args = {};
+        try {
+            args = JSON.parse(((_a = call.function) === null || _a === void 0 ? void 0 : _a.arguments) || "{}");
+        }
+        catch (_c) {
+            args = {};
+        }
+        return { id: call.id, name: (_b = call.function) === null || _b === void 0 ? void 0 : _b.name, args };
+    });
+    const rawUsage = (_d = raw === null || raw === void 0 ? void 0 : raw.usage) !== null && _d !== void 0 ? _d : {};
+    const usage = {
+        inputTokens: rawUsage.prompt_tokens,
+        outputTokens: rawUsage.completion_tokens,
+        totalTokens: rawUsage.total_tokens,
+        credits: rawUsage.base44_credits,
+    };
+    return {
+        text: (_e = message.content) !== null && _e !== void 0 ? _e : "",
+        toolCalls,
+        finishReason: normalizeFinish(choice === null || choice === void 0 ? void 0 : choice.finish_reason, toolCalls.length > 0),
+        usage,
+        raw,
+    };
+}
+/**
+ * OpenAI-compatible provider: speaks the Chat Completions wire format over the Base44
+ * gateway transport.
+ * @internal
+ */
+export function openAICompatibleProvider(transport) {
+    return {
+        async generate(req) {
+            const raw = await transport.complete(buildChatCompletionsBody(req), { signal: req.signal });
+            return parseChatCompletion(raw);
+        },
+    };
+}

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

@@ -0,0 +1,37 @@
+import type { Tool } from "./agents.types.js";
+/**
+ * Defines a tool an agent can call.
+ *
+ * A tool combines a natural-language `description` (used by the model to decide
+ * when to call the tool), a JSON Schema for its `parameters`, and an `execute`
+ * function that runs when the model calls it.
+ *
+ * Pass the returned tool in the `tools` map of {@linkcode AgentsModule.create | base44.agents.create()}.
+ *
+ * @param t - The tool definition: `description`, `parameters` (JSON Schema), and `execute`.
+ * @returns The same tool object, typed as {@linkcode Tool}.
+ *
+ * @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", description: "City name, e.g. 'Tel Aviv'" } },
+ *     required: ["city"],
+ *   },
+ *   execute: async ({ city }) => {
+ *     const data = await fetchWeatherAPI(city);
+ *     return { city, tempC: data.temperature };
+ *   },
+ * });
+ *
+ * const agent = base44.agents.create({
+ *   model: "claude_sonnet_4_6",
+ *   tools: { getWeather },
+ * });
+ * ```
+ */
+export declare function tool(t: Tool): Tool;

package/dist/modules/agents/tool.js

@@ -0,0 +1,38 @@
+/**
+ * Defines a tool an agent can call.
+ *
+ * A tool combines a natural-language `description` (used by the model to decide
+ * when to call the tool), a JSON Schema for its `parameters`, and an `execute`
+ * function that runs when the model calls it.
+ *
+ * Pass the returned tool in the `tools` map of {@linkcode AgentsModule.create | base44.agents.create()}.
+ *
+ * @param t - The tool definition: `description`, `parameters` (JSON Schema), and `execute`.
+ * @returns The same tool object, typed as {@linkcode Tool}.
+ *
+ * @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", description: "City name, e.g. 'Tel Aviv'" } },
+ *     required: ["city"],
+ *   },
+ *   execute: async ({ city }) => {
+ *     const data = await fetchWeatherAPI(city);
+ *     return { city, tempC: data.temperature };
+ *   },
+ * });
+ *
+ * const agent = base44.agents.create({
+ *   model: "claude_sonnet_4_6",
+ *   tools: { getWeather },
+ * });
+ * ```
+ */
+export function tool(t) {
+    return t;
+}

package/dist/modules/entities.js

@@ -53,7 +53,7 @@ function parseRealtimeMessage(dataStr) {
  */
 function createEntityHandler(axios, appId, entityName, getSocket) {
     const baseURL = `/apps/${appId}/entities/${entityName}`;
-    return {
+    const handler = {
         // List entities with optional pagination and sorting
         async list(sort, limit, skip, fields) {
             const params = {};
@@ -159,5 +159,62 @@ function createEntityHandler(axios, appId, entityName, getSocket) {
             });
             return unsubscribe;
         },
+        asTool(opts = {}) {
+            var _a;
+            const operations = (_a = opts.operations) !== null && _a !== void 0 ? _a : ["read"];
+            const tools = {};
+            if (operations.includes("read")) {
+                tools[`read_${entityName}`] = {
+                    description: `Read ${entityName} entities. For the query param, use MongoDB query syntax, e.g. { "status": "open", "price": { "$gt": 30 } }.`,
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            query: { type: "object", description: `MongoDB-style filter over ${entityName} fields.`, additionalProperties: true },
+                            sort: { type: "string", description: "Field to sort by; prefix with '-' for descending (e.g. '-created_date')." },
+                            limit: { type: "number", description: "Maximum number of records to return." },
+                            skip: { type: "number", description: "Number of records to skip (pagination)." },
+                            fields: { type: "array", items: { type: "string" }, description: "Subset of fields to return." },
+                        },
+                    },
+                    execute: (args = {}) => { var _a; return handler.filter(((_a = args.query) !== null && _a !== void 0 ? _a : {}), args.sort, args.limit, args.skip, args.fields); },
+                };
+            }
+            if (operations.includes("create")) {
+                tools[`create_${entityName}`] = {
+                    description: `Create a new ${entityName} entity`,
+                    // open object: the SDK has no runtime schema, so the model supplies fields directly
+                    parameters: { type: "object", additionalProperties: true },
+                    execute: (args = {}) => handler.create(args),
+                };
+            }
+            if (operations.includes("update")) {
+                tools[`update_${entityName}`] = {
+                    description: `Update an existing ${entityName} entity`,
+                    parameters: {
+                        type: "object",
+                        properties: { id: { type: "string", description: `The id of the ${entityName} to update.` } },
+                        required: ["id"],
+                        additionalProperties: true,
+                    },
+                    execute: (args) => {
+                        const { id, ...data } = args !== null && args !== void 0 ? args : {};
+                        return handler.update(id, data);
+                    },
+                };
+            }
+            if (operations.includes("delete")) {
+                tools[`delete_${entityName}`] = {
+                    description: `Delete an existing ${entityName} entity`,
+                    parameters: {
+                        type: "object",
+                        properties: { id: { type: "string", description: `The id of the ${entityName} to delete.` } },
+                        required: ["id"],
+                    },
+                    execute: (args) => handler.delete(args.id),
+                };
+            }
+            return tools;
+        },
     };
+    return handler;
 }

package/dist/modules/entities.types.d.ts

@@ -640,6 +640,25 @@ export interface EntityHandler<T = any> {
      * ```
      */
     subscribe(callback: RealtimeCallback<T>): () => void;
+    /**
+     * Turns this entity into a map of agent tools — one per allowed operation
+     * (`read_<Entity>`, `create_<Entity>`, `update_<Entity>`, `delete_<Entity>`).
+     * Read-only by default, pass `operations` to opt into writes. Spread the result into an agent's `tools`.
+     *
+     * @param opts - Optional `operations` (`"read" | "create" | "update" | "delete"`, default `["read"]`).
+     * @returns A map of tool-name -> {@linkcode Tool}.
+     *
+     * @example
+     * ```typescript
+     * const agent = base44.agents.create({
+     *   model: "claude_sonnet_4_6",
+     *   tools: { ...base44.entities.Order.asTool({ operations: ["read", "update"] }) },
+     * });
+     * ```
+     */
+    asTool(opts?: {
+        operations?: ("read" | "create" | "update" | "delete")[];
+    }): Record<string, import("./agents/agents.types.js").Tool>;
 }
 /**
  * Typed entities module - maps registry keys to typed handlers (full record type).

package/dist/modules/functions.js

@@ -31,38 +31,40 @@ export function createFunctionsModule(axios, appId, config) {
         }
         return headers;
     };
+    // Hoisted so both the returned `invoke` property and `asTool.execute` can reference it
+    // without relying on `this` (which breaks when the object is spread into the client).
+    const invoke = async (functionName, data) => {
+        // Validate input
+        if (typeof data === "string") {
+            throw new Error(`Function ${functionName} must receive an object with named parameters, received: ${data}`);
+        }
+        let formData;
+        let contentType;
+        // Handle file uploads with FormData
+        if (data instanceof FormData ||
+            (data && Object.values(data).some((value) => value instanceof File))) {
+            formData = new FormData();
+            Object.keys(data).forEach((key) => {
+                if (data[key] instanceof File) {
+                    formData.append(key, data[key], data[key].name);
+                }
+                else if (typeof data[key] === "object" && data[key] !== null) {
+                    formData.append(key, JSON.stringify(data[key]));
+                }
+                else {
+                    formData.append(key, data[key]);
+                }
+            });
+            contentType = "multipart/form-data";
+        }
+        else {
+            formData = data;
+            contentType = "application/json";
+        }
+        return axios.post(`/apps/${appId}/functions/${functionName}`, formData || data, { headers: { "Content-Type": contentType } });
+    };
     return {
-        // Invoke a custom backend function by name
-        async invoke(functionName, data) {
-            // Validate input
-            if (typeof data === "string") {
-                throw new Error(`Function ${functionName} must receive an object with named parameters, received: ${data}`);
-            }
-            let formData;
-            let contentType;
-            // Handle file uploads with FormData
-            if (data instanceof FormData ||
-                (data && Object.values(data).some((value) => value instanceof File))) {
-                formData = new FormData();
-                Object.keys(data).forEach((key) => {
-                    if (data[key] instanceof File) {
-                        formData.append(key, data[key], data[key].name);
-                    }
-                    else if (typeof data[key] === "object" && data[key] !== null) {
-                        formData.append(key, JSON.stringify(data[key]));
-                    }
-                    else {
-                        formData.append(key, data[key]);
-                    }
-                });
-                contentType = "multipart/form-data";
-            }
-            else {
-                formData = data;
-                contentType = "application/json";
-            }
-            return axios.post(`/apps/${appId}/functions/${functionName}`, formData || data, { headers: { "Content-Type": contentType } });
-        },
+        invoke,
         // Fetch a backend function endpoint directly.
         async fetch(path, init = {}) {
             const normalizedPath = path.startsWith("/") ? path : `/${path}`;
@@ -75,5 +77,17 @@ export function createFunctionsModule(axios, appId, config) {
             const response = await fetch(joinBaseUrl(config === null || config === void 0 ? void 0 : config.baseURL, primaryPath), requestInit);
             return response;
         },
+        // Turn a backend function into an agent tool.
+        asTool(name, opts) {
+            var _a;
+            return {
+                description: opts.description,
+                parameters: (_a = opts.parameters) !== null && _a !== void 0 ? _a : { type: "object", properties: {}, additionalProperties: true },
+                execute: async (args) => {
+                    const res = await invoke(name, args !== null && args !== void 0 ? args : {});
+                    return res === null || res === void 0 ? void 0 : res.data;
+                },
+            };
+        },
     };
 }

package/dist/modules/functions.types.d.ts

@@ -86,6 +86,19 @@ export interface FunctionsModule {
      * ```
      */
     invoke(functionName: FunctionName, data?: Record<string, any>): Promise<any>;
+    /**
+     * Turns a backend function into a {@linkcode Tool} an agent can call.
+     *
+     * Functions are invoked by name with no server-known input schema, so you supply a
+     * `description` and (optionally) JSON Schema `parameters` for the model.
+     *
+     * @param name - The backend function name.
+     * @param opts - `description` (required) and optional JSON Schema `parameters`.
+     */
+    asTool(name: FunctionName, opts: {
+        description: string;
+        parameters?: Record<string, unknown>;
+    }): import("./agents/agents.types.js").Tool;
     /**
      * Performs a direct HTTP request to a backend function path and returns the native `Response`.
      *

package/dist/modules/types.d.ts

@@ -1,4 +1,4 @@
 export * from "./app.types.js";
-export * from "./agents.types.js";
+export * from "./agents/agents.types.js";
 export * from "./connectors.types.js";
 export * from "./analytics.types.js";

package/dist/modules/types.js

@@ -1,4 +1,4 @@
 export * from "./app.types.js";
-export * from "./agents.types.js";
+export * from "./agents/agents.types.js";
 export * from "./connectors.types.js";
 export * from "./analytics.types.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.32-pr.203.8313142",
+  "version": "0.8.32-pr.205.36088fe",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",