Understanding the Base44 Agent SDK (@base44/sdk)

According to the Stack Overflow 2024 Developer Survey, 76% of developers are using or planning to use AI tools in their development process, but only 42% of them trust the accuracy of AI outputs [Stack Overflow 2024 Developer Survey]. This thirty-four-point confidence gap is the primary reason why developers are moving away from loose prompt engineering and toward deterministic, code-driven agentic architectures. To build reliable systems, AI agents require structured interfaces that run within strict boundaries, which is where client libraries like the Base44 Agent SDK (@base44/sdk) become essential.

The Base44 Agent SDK (@base44/sdk) is a JavaScript/TypeScript client library for executing database operations, managing agent threads, and triggering serverless functions. By providing a typed interface, the SDK allows developers to write code that guides AI agents through specific workflow steps instead of letting them generate raw queries or interface calls. The SDK is organized into seven core modules:

1. agents: Connects to AI conversational agents, manages chat sessions, and routes message threads.
2. auth: Handles user registration, credentials, token persistence, and active sessions.
3. entities: Interacts with the database, performing standard CRUD queries and receiving real-time event updates.
4. functions: Triggers custom backend code execution, which runs in sandboxed environments.
5. integrations: Manages tokens and access configurations for third-party connector tools.
6. analytics: Registers custom user actions and tracks application metrics.
7. app-logs: Queries operational logs to debug agent behaviors and system errors.

A major challenge when developing with serverless agents is persistent data storage. When a serverless function executes or an agent sandbox runs, any files generated are temporary and are deleted once the runtime environment turns off. Standard object storage like AWS S3 or Google Cloud Storage can store these files, but configuring bucket policies, access keys, and IAM roles adds significant code complexity. Additionally, raw object storage is isolated and does not support team collaboration, making it difficult for human developers to review, edit, or sign off on files that agents produce.

Fast.io provides an alternative to raw cloud storage by introducing shared workspaces that humans and agents access together. Instead of configuring separate storage buckets and access policies for every agent, developers can connect their applications to Fast.io workspaces. These workspaces provide version control, real-time co-editing, and full file history, allowing teams to keep human members in the loop as agents output reports, documents, and data views.

To add the client library to your project, run the installation command in your application directory:

npm install @base44/sdk

This command installs the base44 js client and base44 ts library, making the client available for both frontend browser code and backend Node.js runtimes.

While the SDK is pre-configured and ready to import from the internal api folder when you build within a Base44-generated application, external projects require manual setup. Other libraries often look for environment variables automatically to handle connection setups, but the Base44 client requires you to specify your application ID during creation. Developers must pass the ID directly into the initialization helper:

import { createClient } from "@base44/sdk";

// Initialize the external client
const base44 = createClient({
  appId: "your-app-id"
});

You can locate your appId in the URL of your dashboard or inside the local configurations of your project. If your system requires custom error capture or logging, you can define an options block during initialization:

const base44 = createClient({
  appId: "your-app-id",
  options: {
    onError: (err) => {
      console.error("Base44 connection failed:", err.message);
    }
  }
});

After creating the client instance, the next step is establishing an authenticated session. Standard users can authenticate using email credentials:

async function authenticateSession() {
  const session = await base44.auth.login({
    email: "developer@example.com",
    password: "securePassword123"
  });
  console.log("Session token created for user:", session.user.id);
}

For background workers, automation scripts, and database migrations, user-level credentials can block operations due to row-level security policies. In these backend scenarios, developers can use the service role client by calling the service role helper:

// Bypassing row-level security for administrative tasks
const adminClient = base44.asServiceRole();

Because service role credentials bypass all database access rules and grant full read-and-write permissions, you must store these keys securely on your server. Never expose service role clients in client-side code or client-side files, as doing so exposes your entire database to public access.

The entities module provides a direct code interface for interacting with database tables, allowing you to run standard insert, update, and delete actions. However, polling the database to detect state updates is slow and wastes network bandwidth. To resolve this, the SDK uses WebSockets to send instant updates to your application.

This code example details how to initialize the client and subscribe to changes on a database entity:

import { createClient } from "@base44/sdk";

// Initialize the client in an external Node.js application
const base44 = createClient({
  appId: "your-app-id"
});

// Subscribe to real-time updates on a Task entity
const unsubscribe = base44.entities.Task.subscribe((event) => {
  console.log(`Update event: ${event.type}`);
  console.log(`Task ID: ${event.id}`);
  console.log("Updated data payload:", event.data);
});

// Terminate the subscription when done
// unsubscribe();

When a user or another agent edits a record in the database, the server pushes the event to the client over an active WebSocket connection, firing the callback function immediately.

To prevent memory leaks and resource depletion, developers must manage subscription lifecycles. The subscribe method returns a cleanup function. If your application starts subscriptions without calling the cleanup function when components unmount or processes exit, the WebSocket connections remain open. Over time, these dangling connections consume server memory and exhaust the available socket pool, causing subsequent connection requests to fail.

High-throughput systems must also account for occasional network drops. While the client attempts to reconnect automatically when a socket drops, transient disconnects can cause your application to miss intermediate database updates. To keep data accurate, developers should write a reconciliation routine that runs whenever a reconnection succeeds:

async function reconcileLocalState() {
  const activeTasks = await base44.entities.Task.list({
    filter: { status: "pending" }
  });
  console.log("Local state reconciled with database. Active count:", activeTasks.length);
}

By querying the database directly after a reconnection, your system ensures that any changes that occurred during the offline period are captured and applied to your local application state.

The functions module allows developers to trigger custom serverless functions hosted on Base44, which execute inside Deno runtimes [Base44 Documentation]. These functions run in isolated environments and can accept payloads from your external client:

async function triggerBillingJob(userId: string) {
  const response = await base44.functions.invoke("calculateBilling", {
    userId,
    billingDate: new Date().toISOString()
  });
  console.log("Billing function result:", response);
}

For long-running tasks or tasks that return progressive data, you can use the fetch method to handle streamed responses. This allows your Node.js application to process chunks of text or media before the serverless execution completes.

Similarly, the agents module lets you manage conversations with AI agents. You can start chat threads and send messages to conversational sandboxes:

async function runAgentChat(threadId: string, userInput: string) {
  const result = await base44.agents.sendMessage({
    threadId,
    content: userInput
  });
  console.log("Agent response reply:", result.reply);
}

However, because these agent runs and serverless functions operate in temporary sandboxes, any files they write during execution are lost once the process terminates. To keep these outputs, you need a persistent storage system.

Let's look at competing options first. Local disk storage is not viable because serverless containers delete all local files when they spin down. AWS S3 provides persistent storage, but configuring IAM roles, security credentials, and bucket access policies requires writing complex setup code. Google Drive offers shared storage, but its API is difficult to connect with serverless functions and does not support automatic indexing for search.

Fast.io offers a better alternative by providing persistent workspace storage that connects directly to your agent workflows. Fast.io workspaces include shared org-owned workspaces, per-file version history, granular access permissions, and automated webhooks. Fast.io exposes these tools using Streamable HTTP at /mcp and legacy SSE at /sse. You can learn more about how to set up workspaces on the Fast.io workspaces product page.

By pointing your Base44 serverless functions to the Fast.io streamable HTTP endpoints, your agents can read and write files directly within a persistent, shared directory. This ensures that agent outputs are saved securely and are instantly accessible to human team members.

Persist Base44 Agent Data Across Node.js App Threads

Connect your Base44 client to a persistent, shared Fast.io workspace. Keep human co-editors in the loop with version history, collaborative notes, and automated metadata extraction. Starts with a 14-day free trial.

Start 14-Day Trial

AI agents often need to read data from unstructured files like PDF invoices, text contracts, and scanned forms. Converting these documents into structured database entries usually requires setting up complex OCR templates or writing custom text-parsing regex patterns that fail whenever the document layout changes.

Fast.io solves this problem with Metadata Views. Differentiating from the general search and summarization tools in Intelligence Mode, Metadata Views serve as the structured extraction layer for your workspace. Users describe the fields they want to extract in natural language, and Fast.io designs a typed schema that supports Text, Integer, Decimal, Boolean, URL, JSON, and Date & Time formats. The system then scans the files in the workspace and extracts the data into a spreadsheet view. To see how this works, visit the Metadata Views product page.

A Base44 agent can query these Metadata Views programmatically to retrieve structured data without running manual text extraction. For example, your backend code can pull structured values from a contract workspace and trigger a Base44 serverless function:

async function processContractRenewals() {
  // Retrieve structured records from a Fast.io Metadata View
  const contracts = await fastio.queryView({
    viewId: "contract-metadata-view",
    filter: "expirationDate <= '2026-12-31'"
  });
  for (const contract of contracts) {
    console.log("Found expiring contract:", contract.filename);
    // Pass structured data directly to a Base44 serverless function
    await base44.functions.invoke("renewContract", {
      clientName: contract.clientName,
      expiration: contract.expirationDate,
      value: contract.contractValue
    });
  }
}

This workflow prevents extraction errors and keeps your data clean. To start using these tools, teams can set up an organization on Fast.io. Fast.io offers tiered pricing plans: the Starter plan costs $29/mo, the Business plan costs $99/mo, and the Growth plan costs $299/mo [Fastio Pricing]. Every plan starts with a fourteen-day free trial that requires a credit card. The signup flow supports clean agent-to-human handoff. An AI agent can sign up free, initialize the workspaces, configure the folders, and set up the initial Metadata Views. Once the setup is complete, the agent generates an ownership transfer link. A human team member clicks the link, joins the organization, and adds a credit card to start the fourteen-day trial, allowing the team to run production workflows without losing any of the agent's work.