@base44-preview/sdk 0.8.32-pr.206.d8fc10d → 0.8.34-pr.205.d800012

package/dist/client.d.ts

@@ -12,12 +12,12 @@ export type { Base44Client, CreateClientConfig, CreateClientOptions };
  * The client supports three authentication modes:
  * - **Anonymous**: Access modules without authentication using `base44.moduleName`. Operations are scoped to public data and permissions.
  * - **User authentication**: Access modules with user-level permissions using `base44.moduleName`. Operations are scoped to the authenticated user's data and permissions. Use `base44.auth.loginViaEmailPassword()` or other auth methods to get a token.
- * - **Service role authentication**: Access modules with elevated permissions using `base44.asServiceRole.moduleName`. Operations bypass entity access rules and field-level security, giving full read and write access to all of the app's data. Only available in Base44-hosted backend functions. Create a client with service role authentication using {@linkcode createClientFromRequest | createClientFromRequest()}.
+ * - **Service role authentication**: Access modules with elevated permissions using `base44.asServiceRole.moduleName`. Operations can access any data available to the app's admin. Only available in Base44-hosted backend functions. Create a client with service role authentication using {@linkcode createClientFromRequest | createClientFromRequest()}.
  *
  * For example, when using the {@linkcode EntitiesModule | entities} module:
  * - **Anonymous**: Can only read public data.
  * - **User authentication**: Can access the current user's data.
- * - **Service role authentication**: Can read and write any record, bypassing access rules.
+ * - **Service role authentication**: Can access all data that admins can access.
  *
  * Most modules are available in all three modes, but with different permission levels. However, some modules are only available in specific authentication modes.
  *
@@ -43,7 +43,7 @@ export declare function createClient(config: CreateClientConfig): Base44Client;
  *
  * This function is designed for use in Base44-hosted backend functions. For frontends and external backends, use {@linkcode createClient | createClient()} instead.
  *
- * When used in a Base44-hosted backend function, `createClientFromRequest()` automatically extracts authentication tokens from the request headers that Base44 injects when forwarding requests. The returned client includes service role access using `base44.asServiceRole`, which bypasses entity access rules and field-level security.
+ * When used in a Base44-hosted backend function, `createClientFromRequest()` automatically extracts authentication tokens from the request headers that Base44 injects when forwarding requests. The returned client includes service role access using `base44.asServiceRole`, which provides admin-level permissions.
  *
  * To learn more about the Base44 client, see {@linkcode createClient | createClient()}.
  *
@@ -82,7 +82,7 @@ export declare function createClient(config: CreateClientConfig): Base44Client;
  *   try {
  *     const base44 = createClientFromRequest(req);
  *
- *     // Read across all users, bypassing the Orders entity's access rules
+ *     // Access admin data with service role permissions
  *     const recentOrders = await base44.asServiceRole.entities.Orders.list('-created_at', 50);
  *
  *     return Response.json({ orders: recentOrders });

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";
@@ -23,12 +23,12 @@ import { createAnalyticsModule } from "./modules/analytics.js";
  * The client supports three authentication modes:
  * - **Anonymous**: Access modules without authentication using `base44.moduleName`. Operations are scoped to public data and permissions.
  * - **User authentication**: Access modules with user-level permissions using `base44.moduleName`. Operations are scoped to the authenticated user's data and permissions. Use `base44.auth.loginViaEmailPassword()` or other auth methods to get a token.
- * - **Service role authentication**: Access modules with elevated permissions using `base44.asServiceRole.moduleName`. Operations bypass entity access rules and field-level security, giving full read and write access to all of the app's data. Only available in Base44-hosted backend functions. Create a client with service role authentication using {@linkcode createClientFromRequest | createClientFromRequest()}.
+ * - **Service role authentication**: Access modules with elevated permissions using `base44.asServiceRole.moduleName`. Operations can access any data available to the app's admin. Only available in Base44-hosted backend functions. Create a client with service role authentication using {@linkcode createClientFromRequest | createClientFromRequest()}.
  *
  * For example, when using the {@linkcode EntitiesModule | entities} module:
  * - **Anonymous**: Can only read public data.
  * - **User authentication**: Can access the current user's data.
- * - **Service role authentication**: Can read and write any record, bypassing access rules.
+ * - **Service role authentication**: Can access all data that admins can access.
  *
  * Most modules are available in all three modes, but with different permission levels. However, some modules are only available in specific authentication modes.
  *
@@ -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: () => {
@@ -257,7 +259,7 @@ export function createClient(config) {
         /**
          * Provides access to service role modules.
          *
-         * Service role authentication provides elevated permissions for backend operations. Unlike user authentication, which is scoped to a specific user's permissions, service role authentication bypasses entity access rules and field-level security entirely, giving full read and write access to all of the app's data.
+         * Service role authentication provides elevated permissions for backend operations. Unlike user authentication, which is scoped to a specific user's permissions, service role authentication has access to the data and operations available to the app's admin.
          *
          * @throws {Error} When accessed without providing a serviceToken during client creation.
          *
@@ -268,7 +270,7 @@ export function createClient(config) {
          *   serviceToken: 'service-role-token'
          * });
          *
-         * // Read every user record, bypassing the User entity's access rules
+         * // Also access a module with elevated permissions
          * const allUsers = await base44.asServiceRole.entities.User.list();
          * ```
          */
@@ -286,7 +288,7 @@ export function createClient(config) {
  *
  * This function is designed for use in Base44-hosted backend functions. For frontends and external backends, use {@linkcode createClient | createClient()} instead.
  *
- * When used in a Base44-hosted backend function, `createClientFromRequest()` automatically extracts authentication tokens from the request headers that Base44 injects when forwarding requests. The returned client includes service role access using `base44.asServiceRole`, which bypasses entity access rules and field-level security.
+ * When used in a Base44-hosted backend function, `createClientFromRequest()` automatically extracts authentication tokens from the request headers that Base44 injects when forwarding requests. The returned client includes service role access using `base44.asServiceRole`, which provides admin-level permissions.
  *
  * To learn more about the Base44 client, see {@linkcode createClient | createClient()}.
  *
@@ -325,7 +327,7 @@ export function createClient(config) {
  *   try {
  *     const base44 = createClientFromRequest(req);
  *
- *     // Read across all users, bypassing the Orders entity's access rules
+ *     // Access admin data with service role permissions
  *     const recentOrders = await base44.asServiceRole.entities.Orders.list('-created_at', 50);
  *
  *     return Response.json({ orders: recentOrders });

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";
 /**
@@ -49,7 +49,7 @@ export interface CreateClientConfig {
      */
     token?: string;
     /**
-     * Service role authentication token. Provides elevated permissions that bypass entity access rules and field-level security. Only available in Base44-hosted backend functions. Automatically added to clients created using {@linkcode createClientFromRequest | createClientFromRequest()}.
+     * Service role authentication token. Provides elevated permissions to access data available to the app's admin. Only available in Base44-hosted backend functions. Automatically added to client's created using {@linkcode createClientFromRequest | createClientFromRequest()}.
      * @internal
      */
     serviceToken?: string;
@@ -117,7 +117,7 @@ export interface Base44Client {
     /**
      * Provides access to supported modules with elevated permissions.
      *
-     * Service role authentication provides elevated permissions for backend operations. Unlike user authentication, which is scoped to a specific user's permissions, service role authentication bypasses entity access rules and field-level security entirely, giving full read and write access to all of the app's data.
+     * Service role authentication provides elevated permissions for backend operations. Unlike user authentication, which is scoped to a specific user's permissions, service role authentication has access to the data and operations available to the app's admin.
      *
      * @throws {Error} When accessed without providing a serviceToken during client creation
      */

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, FinishReason, } 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,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.
@@ -194,7 +507,7 @@ export interface AgentsModuleConfig {
  * This module is available to use with a client in all authentication modes:
  *
  * - **Anonymous or User authentication** (`base44.agents`): Access is scoped to the current user's permissions. Users must be authenticated to create and access conversations.
- * - **Service role authentication** (`base44.asServiceRole.agents`): Operations run with elevated permissions for backend code that isn't tied to a specific user session.
+ * - **Service role authentication** (`base44.asServiceRole.agents`): Operations have elevated admin-level permissions. Can access all conversations that the app's admin role has access to.
  *
  * ## Generated Types
  *
@@ -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,34 @@
+/**
+ * Minimal authenticated JSON POST against the gateway. The provider supplies the wire-specific
+ * path (e.g. `/chat/completions`), so the transport stays neutral across provider formats.
+ * @internal
+ */
+export type GatewayTransport = {
+    post(path: string, 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): {
+    post(path: string, 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 post(path, body, opts = {}) {
+            const { baseURL, apiKey } = resolveConnection(config);
+            const res = await fetch(`${baseURL}${path}`, {
+                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;