@sapiom/tools

@sapiom/tools

A typed TypeScript client for Sapiom capabilities — sandboxes, git repositories, coding agents, file storage, content generation, search, email, domains, orchestrations, and schedules — authenticated to your tenant.

These are the same capabilities your Sapiom agents call as tools; this package makes them callable directly from your own code.

npm install @sapiom/tools
# or
pnpm add @sapiom/tools

Quickstart

import { createClient } from "@sapiom/tools";

const sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY });

// Create a repo, have a coding agent build into it, then publish.
const repo = await sapiom.repositories.create("landing-page");
const run = await sapiom.models.coding.run({
  task: "Build a one-page marketing site in index.html.",
  gitRepository: repo, // cloned into the run's sandbox at /workspace/landing-page
});

if (run.result?.success) {
  const { sha } = await repo.pushFromSandbox(run.sandbox, {
    message: "build: landing",
  });
  console.log("published", sha);
}

Authentication

There are two ways to authenticate, both exposing the identical capability surface:

• Explicit — pass a key to createClient. This is the standalone entry point:

  const sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY });
  await sapiom.sandboxes.create({ name: "demo" });
  

• Ambient — import the namespaces directly and they resolve credentials from SAPIOM_API_KEY (or, inside a Sapiom agent step, from the client the runtime provides):

  import { sandboxes, repositories, agent } from "@sapiom/tools";
  await sandboxes.create({ name: "demo" });
  

Attribution

Calls can be attributed to an agent and trace so they show up correctly in your transaction history. Attribution is set once, on the client — not per call:

const sapiom = createClient({
  apiKey: process.env.SAPIOM_API_KEY,
  attribution: { agentName: "digest-bot", traceId },
});
// every call this client makes is now attributed to digest-bot / traceId

Inside a Sapiom agent run you don't set this at all — the runtime constructs the client with the running execution's attribution, so every tool call is attributed automatically.

If a single process makes calls on behalf of more than one agent or trace, derive a client per context with sapiom.withAttribution({ ... }).

Capabilities

Each capability is a namespace, importable from the barrel or its own subpath (e.g. @sapiom/tools/sandboxes). Every capability has its own README with usage details, preconditions, and gotchas the type signatures can't express — read it before first use.

Namespace	What it is	Docs
sandboxes	Isolated, ephemeral compute	src/sandboxes
repositories	Private, in-network git repos	src/repositories
agent	Coding agents (LLM execution)	src/agent
fileStorage	Tenant-scoped object storage (presigned URLs)	src/file-storage
contentGeneration	Media generation (images + video; audio soon), with optional storage	src/content-generation
search	Search the web (webSearch), read a page (scrape), and look up professional emails (emailSearch)	src/search
orchestrations	Run a deployed orchestration, or dispatch one from a step and await its result	src/orchestrations
schedules	Schedule a deployed orchestration to run on a cron, or once at a set time	src/schedules
database	Permanent Postgres databases (yours until you delete them), returned with direct connection credentials	src/database
email	Transactional email — inboxes, messages, sending domains, threads, and inbound webhooks	src/email
domains	Register domain names and manage their DNS records	src/domains
memory	Tenant-scoped long-term memory (namespace-isolated append-log; semantic/keyword/hybrid recall)	src/memory
google	Act as a tenant inside Google: Drive, Gmail, and the raw OAuth credential	src/google
github	List a tenant's GitHub repositories	src/github
llm	Routed LLM calls: one-shot run and deferred submit / sessions	src/llm
decisions	System One decisions: evaluate returns calibrated probabilities over a fixed answer set	src/decisions

llm.run vs decisions.evaluate

llm.run generates text or a schema-shaped output. When the answer is one of a set you can name up front — a yes/no gate, a pick-one label, a rubric level — call decisions.evaluate instead. It returns calibrated probabilities over those answers, with no schema or reply parsing, and the answers map is typed by the questions you pass:

const res = await sapiom.decisions.evaluate({
  state: { message: ticket.body },
  questions: {
    urgent: { type: "noul", instructions: "Is this urgent?" },
    team: {
      type: "choice",
      instructions: "Which team should handle `message`?",
      criteria: {
        shipping: "Delivery issues",
        billing: "Charges and refunds",
        other: null,
      },
    },
  },
});
if (res.answers.urgent.noul > 0.8) escalate(res.answers.team.choice);

Ask every independent question over the same state in one call; they are evaluated in parallel. Keep arithmetic and date math in code — decisions.evaluate judges, it does not compute.

The result contains answers, token usage, and optional cost quote metadata (estimateUsd, currency, reference, isEstimate, source). The estimate is not the settled charge. Results omit model and provider identity. The optional request model still selects a platform model; omit it to use the platform default.

Composing capabilities

Capabilities are designed to work together. A coding agent run hands back the live Sandbox it executed in, and a Repository can publish a working tree straight from that sandbox:

const run = await agent.coding.run({ task, gitRepository: repo });
await repo.pushFromSandbox(run.sandbox);

A useful pattern: let the agent do the open-ended work (writing files) and perform exact, repeatable actions — committing, pushing, deploying — in your own code rather than in the agent's prompt. The agent produces the changes; pushFromSandbox publishes them deterministically.

Some compositions need nothing but a param. contentGeneration.images.create takes an optional storage, and each generated image is persisted into fileStorage as it returns — handing you a durable fileId with no extra call:

const out = await contentGeneration.images.create({
  prompt: "a logo",
  storage: { visibility: "private" },
});
const { downloadUrl } = await fileStorage.getDownloadUrl(
  out.images![0].fileId!,
);

Usage analytics

The SDK can emit anonymous usage analytics — one capability.call event per capability request, carrying the capability name, the request URL path (query strings are stripped, never recorded), HTTP status, duration, and request size (never request or response bodies). Events describe calls to Sapiom's own API only; nothing is captured about any third-party traffic.

By default nothing is sent anywhere: the emitter (see @sapiom/analytics-core) is a no-op unless a collector endpoint is configured. Delivery is batched in the background and can never throw, block, or slow a capability call. Opt out any time with SAPIOM_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1.

If your process constructs many clients over its lifetime (one per execution, for example), call await client.shutdown() when you're done with each one: it flushes any buffered events and detaches the emitter's process exit hook. It's idempotent, never rejects, resolves immediately when there's nothing to release, and covers every client derived via withAttribution. One-shot scripts don't need it — events flush on process exit. Capability calls made after shutdown still work; they just no longer emit analytics.

License

MIT