TypeScript SDK

@arg-ai/sdk is the official TypeScript client. It wraps the quickstart golden path (auth, retries, typed errors, polling) so the same flow is a handful of typed calls instead of raw curl. It is hand-written, has zero runtime dependencies, and ships as pure ESM, so it runs unchanged in Node, the browser, and edge runtimes.

Building an app that runs inside Arg, a published Site, or a script an agent executes? Those import the host-provided app SDK described in the SDK overview - a separate module from the client on this page, even though the hosts resolve it under the @arg-ai/sdk specifier too. The installed @arg/sdk package used for servers and CI wraps this client, so everything on this page stays available there as files, workspaces, chats, keys and agentLifecycle.

Install

npm install @arg-ai/sdk

Requires Node 18+ (it uses the built-in fetch).

Authentication

The client reads ARG_API_KEY from the environment by default, or you can pass a key explicitly. Use a user-owned key for the golden path: creating a workspace requires a user principal.

import { ArgAI } from "@arg-ai/sdk";

const client = new ArgAI(); // reads ARG_API_KEY
const explicit = new ArgAI({ apiKey: "arg_live_…" });

A JWT bearer token works too via accessToken, and baseUrl overrides the host (default https://api.arg.ai).

Service-account keys cannot call POST /api/workspaces (it requires a user principal). For unattended jobs, create workspaces with client.workspaces.createInOrganization(orgId, {name}) instead.

The golden path

Create a workspace

const ws = await client.workspaces.create({ name: "quickstart" });
const scoped = client.withWorkspace(ws.id);

Upload an input file

await scoped.files.upload({
  data: "region,revenue\nAPAC,120\nEMEA,90\n",
  name: "data.csv",
});

Run an agent and collect the output

const run = await scoped.run("Read data.csv and chart revenue by region.");
const result = await run.result();
const outputs = await run.files();   // paths the run wrote

console.log(result.response, outputs);

That is the whole loop: point an agent at a workspace, give it a task, collect the artifacts.

Agent runs: the `Run` lifecycle

scoped.run(task) creates a chat, starts the turn against the workspace, and returns a Run. A Run is async-iterable for lifecycle events, awaitable for the final result, and knows which files the run produced.

const run = await client.withWorkspace(ws.id).run("Chart revenue by region from data.csv");

for await (const event of run) {
  console.log(event.status); // "running" then "completed" | "error"
}

const result = await run.result(); // { response, thinking?, toolOutputs }
const outputs = await run.files(); // ["/charts/revenue.png", …]

Follow up in the same chat, or stop an in-flight turn:

await run.queue("Now export the chart as a PDF.");
await run.stop();

The lifecycle iterator is coarse by design. The status endpoint reports only running → completed | error, so Run yields the lifecycle plus the final result, not granular token or per-tool deltas. A terminal agent error arrives as an error event, while run.result() throws on error by default (pass { throwOnError: false } to receive the error result instead).

run.files() is parsed from the write_file, edit_file, and multi_edit tool calls in the result, deduplicated. For direct control of the poll loop, drop down to client.agent.waitForResult(job).

Working with files

upload picks its transport by size. Small files go in one request; files above multipartThreshold (16 MiB) switch to a resilient multipart upload that chunks the bytes, uploads parts with bounded concurrency, and retries individual parts. A dropped connection retries only the affected part instead of restarting the whole file, and an unrecoverable failure aborts the server-side session so nothing is left dangling.

const files = client.withWorkspace(ws.id).files;

// Large file: chunked, resilient, with progress.
await files.upload(
  { data: bigBlob, name: "video.mp4" },
  {
    onProgress: (p) => console.log(`${p.bytesUploaded}/${p.totalBytes}`),
    signal: controller.signal, // aborting also aborts the multipart session
  },
);

Stream a download instead of buffering the whole file into memory, and manage files in batches:

const stream = await files.downloadStream("/video.mp4"); // ReadableStream

await files.move("/draft.md", "/final/");
await files.copy("/final/draft.md", "/final/draft.bak.md");
await files.delete(["/tmp/a.csv", "/tmp/b.csv"]); // single or batch

const tree = await files.tree();
const text = await files.content("/final/draft.md");

uploadMultipart forces the resumable path regardless of size, and partSize, concurrency, and maxPartRetries are all tunable.

Run shell commands

const { stdout } = await client.withWorkspace(ws.id).runBash("ls -la");

Errors

Every failure throws a typed error you can branch on:

import { ArgPermissionError, ArgRateLimitError } from "@arg-ai/sdk";

try {
  await client.workspaces.create({ name: "x" });
} catch (err) {
  if (err instanceof ArgPermissionError) {
    // e.g. a service-account key. Use workspaces.createInOrganization instead.
  } else if (err instanceof ArgRateLimitError) {
    console.log(`retry after ${err.retryAfter}s`);
  }
}

The hierarchy is ArgAuthenticationError (401), ArgPermissionError (403), ArgNotFoundError (404), ArgConflictError (409), ArgValidationError (422), ArgRateLimitError (429), ArgApiError (other 4xx/5xx), and ArgConnectionError (network or timeout), all extending ArgError. Transient failures (5xx, 429, network) on idempotent requests are retried with backoff automatically.

Custom headers and the escape hatch

Constructor defaultHeaders apply to every request; per-call headers apply to one (useful for trace propagation). Anything not yet on the typed surface is reachable with client.request():

const client = new ArgAI({ defaultHeaders: { "x-team": "evals" } });

const data = await client.request<MyType>("GET", "/api/some/endpoint", {
  query: { a: 1 },
});

Next steps

Browse the full surface in the API Reference.
Compare with the raw curl quickstart to see what the SDK wraps.
Bringing your own agent loop? See the OpenAI and Anthropic SDK guides for using arg.ai workspace tools directly.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

TypeScript SDK

Install

Authentication

The golden path

Agent runs: the `Run` lifecycle

Working with files

Run shell commands

Errors

Custom headers and the escape hatch

Next steps

​Install

​Authentication

​The golden path

​Agent runs: the Run lifecycle

​Working with files

​Run shell commands

​Errors

​Custom headers and the escape hatch

​Next steps

Install

Authentication

The golden path

Agent runs: the `Run` lifecycle

Working with files

Run shell commands

Errors

Custom headers and the escape hatch

Next steps