@serverless-agents/client

This is the TypeScript platform SDK, not a TypeScript harness runtime. See the client guide and concepts.

npm install @serverless-agents/client

API access requires a project credential supplied by your platform administrator. Installing this public package does not create an account or grant access.

ESM TypeScript client for the complete public v1 API (69 operations). Version 0.3 includes JavaScript bundles, guest policies and session resource usage. Node 22.18+ with Fetch and Web Crypto. Use project credentials in a backend. Direct browser API access requires a separately configured CORS policy; do not expose project credentials in frontend assets.

import { ServerlessAgents, ApiError } from '@serverless-agents/client';

const agents = new ServerlessAgents({
  baseUrl: process.env.SERVERLESS_AGENTS_URL!,
  token: process.env.SERVERLESS_AGENTS_TOKEN!,
});
const session = await agents.sessions.create({
  request_id: 'customer-123-session',
  harness_id: harnessId,
  release: { type: 'default' }, // or { type: 'exact', release_id: releaseId }
  harness_config: { model: '...' },
});
const submission = await agents.sessions.inputs.submit(session.id, {
  input_id: 'customer-123-message-1',
  payload: { text: 'Hello' },
});
console.log(submission.receipt.status, submission.replayed);
for await (const event of agents.iterate('listEvents', {
  path: { session_id: session.id }, query: { page: { limit: 100 } },
})) console.log(event.body);

Creation commits identity and queues initialization. Submitting input returns its admission receipt. Harness acceptance does not mean application work is complete. There are no live session/event subscriptions. Cancellation ends the local request; it does not implicitly abort server execution. Explicit sessions.abort records abort intent.

Surface

project, harnesses, releases, uploads, sessions, sessions.inputs, sessions.events, credentials, secrets, pools, usage and operator resources are generated from the public OpenAPI document. Operator groups cover projects, hosts, pools and secret registration/revocation; the server enforces their authority. The generic request(operationId, { path, query, body }, options) is typed against the same document. Internal lease, worker storage and host command APIs are excluded.

iterate advances opaque cursors while retaining filters; ordinary list methods return one page. No iterator starts a background task. putUpload(ticket, bytes) uses a separate signed-URL request without API credentials. Call uploads.complete after transfer, then explicitly waitForUpload or use uploads.get to inspect progress. Blob verification is performed by the service, never by a client permission bypass.

Retries, errors and data fidelity

• Default: two retries, 25-second timeout per API attempt, bounded jittered backoff. Retry transient network failures and HTTP 429/502/503/504. Respect Retry-After up to 30 seconds; larger delays return to the caller. Revision conflicts are not retried.
• Supply request_id / input_id for durable caller-managed retries. Omitting one generates it once per call, before serialization. Every automatic retry reuses that exact identity and request body. ApiError.identity / TransportError.identity expose it after an uncertain result. A new method call without the original ID is new work.
• ApiError exposes status, code, requestId, error.details, and retry timing. Diagnostic requestId is separate from the mutation's retry identity.
• Per-call signal, timeoutMs, retries override client defaults. Token callbacks allow refreshed credentials. Redirects are refused for authenticated and signed requests.
• HTTPS is required. Explicit allowInsecureLocalhost: true permits loopback development for both the API and signed object URLs.
• Timestamps and wire u64 counters/revisions remain strings. Opaque JSON numbers that cannot round-trip safely become exported LosslessNumber values. Use parseJson / stringifyJson when reading files or persisting these values. Duplicate keys, non-finite JS numbers and unsafe integer numbers are rejected; use new LosslessNumber('9007199254740993') or bigint to submit exact integers.

Build and distribution

pnpm install --frozen-lockfile
pnpm --filter @serverless-agents/client generate:check
pnpm --filter @serverless-agents/client test
pnpm --filter @serverless-agents/client pack --out /tmp/serverless-agents-client.tgz

Only dist, the package metadata, this README, and the MIT license enter the package. Generation uses the committed public schema; it never reads an arbitrary remote OpenAPI endpoint. Generated code stays in src/generated; transport, errors, pagination and transfer helpers are handwritten. The published package does not require access to the platform repository.

Operator read requests may set projectId in client options. This sends the explicit x-project-id header; the API requires operator platform_read and never permits a project credential to switch tenants. access.get(), dashboard.summary/work/startups(), operator.hosts.diagnostics() and sessions.aborts() expose the dashboard reporting contracts.

Session state

const state = await agents.sessions.state(sessionId);

Returns the latest harness-owned JSON object, revision and update time. Requires session_read; there is no public state-write operation. See the session state guide.