Actions, agents and resources

Actions are Arg’s typed capability catalog: file operations, integrations, code execution, agent runs and more, each with an id, an input schema and a permission. actions discovers and runs them; agents is a typed wrapper over the agent_run Action; the resource namespaces (comments, notifications, integrations, automations, code, sites, servers) wrap the workspace APIs those Actions sit on. All of it runs as the current identity, under whatever the host granted.

Discover before you run

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

const catalog = await actions.list({ query: "summarize", includeSchema: true });
const schema = await actions.schema("file_read"); // { id, inputSchema, ... }
const detail = await actions.describe("hubspot_search", { field: "object", value: "contacts" });

Action ids and their inputs evolve. list and schema are the contract; do not hard-code an input shape you have not read from schema. describe explains a single field, which is what an agent or a settings UI uses to offer valid values. actions.enabled and actions.readOnly tell you what the host granted before you try: inside a preview they mirror the Actions switch and the file grant, on a server they are always on, and in an agent script they follow the turn. await actions.ready resolves once the host has reported.

Run

const receipt = await actions.run(
  "file_write",
  { path: "out.md", content: "# Done" },
  {
    idempotencyKey: "report-2026-09-14",
  },
);
// { runId, status: "succeeded" | "failed" | "queued" | ..., output?, error? }

const batch = await actions.runBatch([
  { actionId: "file_read", input: { path: "a.md" } },
  { actionId: "file_read", input: { path: "b.md" } },
]);
const later = await actions.getRun(receipt.runId);
const recent = await actions.listRuns({ actionId: "file_write", limit: 20 });

Check status on every receipt. A run may be queued or fail after acceptance, and an accepted write must not be retried blindly; give writes an idempotencyKey so a retry after a dropped connection is safe. getRun needs a durable run: a synchronous read without an idempotency key may report a runId for audit only and answer getRun with not_found.

Connector tools

Inside an app opened in Arg, the viewer’s MCP connectors are Actions too. A tool’s id is mcp__<connector>__<tool>, the same name the agent calls it by, and it runs through the viewer’s own account (or one shared with them) for whichever connectors they switched on in this workspace. That lets a dashboard read live data straight from a connector:

const tools = await actions.list({ backend: "mcp" });

const run = await actions.run("mcp__linear__list_issues", { assignee: "me" });
// run.output: { data, text, content }
const issues = run.output.data;

data is the tool’s structuredContent when it sends one, otherwise its text parsed as JSON, otherwise null; text and the raw MCP content blocks are there for tools that answer in prose. A tool that reports an error, or a connector that needs reconnecting, rejects the call rather than returning the error as data. A viewer without the connector gets not_found, so show them which one to connect. Every connector tool needs workspace write access, since MCP tools carry no dependable read/write marking. Calls are not recorded as durable runs, so getRun does not find them. A deployed Site or Server calls Actions with its own token, which has no connectors, so connector tools are not available there.

Agent runs

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

const run = await agents.run("Summarize the notes in this folder", {
  readOnly: true,
  waitForCompletion: true,
  waitTimeoutSeconds: 120,
});
if (run.status === "succeeded" && run.output?.status === "completed") {
  console.log(run.output.result);
}

agents.run is the agent_run Action with typed options: agentName to pick a workspace subagent, chatId to continue a chat, model, maxToolIterations, readOnly, and logPath / logFormat to have the run write its own transcript into the workspace. There are two statuses to inspect: the Action’s (run.status) and the agent’s (run.output.status). Both must be terminal and successful before run.output.result is meaningful. Compare with chat, which starts a conversation you can watch and continue in the UI; agents.run is a run you wait for.

Workspace resources

Each namespace maps onto the workspace APIs and keeps their permissions. Paths are cloud workspace paths even under an authenticated arg serve, where fs reads local disk: a comment or an automation refers to the file in the cloud workspace, never to an unuploaded file on your machine.

Namespace	Methods
`comments`	`list(path, { includeResolved? })`, `create({ path, body, parentId?, metadata? })`, `update(id, body)`, `resolve(id, resolved = true)`, `remove(id)`
`permissions`	`share({ path, kind, userId, permission })`, `shareFile(path, options)`, `shareFolder(path, options)`
`permissions`	`list(path)`, `update(id, { permission })`, `revoke(id)`
`notifications`	`list({ limit?, offset?, unreadOnly? })`, `send(input)`, `sendToMe(input)`, `sendToUser(userId, input)`, `markRead(id)`, `markAllRead()`
`integrations`	`providers()`, `connections({ organizationId?, providerId? })`, `triggers(providerId)`, `proxy(alias, path, { method?, body? })`
`automations`	`run({ filePath, document?, input? })`, `getRun(id)`, `stop(id)`, `history({ limit?, offset?, filePath? })`, `deployments()`, `pause(filePath)`, `resume(filePath)`
`code`	`run(command, { sandboxId? })` returning `{ status: "completed" \| "failed", stdout, stderr, duration_ms }`
`sites`	`list()`, `create({ slug, sourcePath, framework, access, displayName? })`, `get(id)`, `build(id, { autoPromote? })`, `version(id, versionId)`, `promote(id, versionId)`, `remove(id)`
`servers`	`list()`, `start({ command, port, name?, access?, actions? })`, `get(id)`, `stop(id)`

A few notes that keep these honest:

notifications.sendToMe targets the current user. sendToUser takes a user id from users.list(). The lower-level send still accepts a users array for fan-out or email-address recipients. Notification input accepts title, body, type, metadata, target and channels; provide at least a title or target. Channels narrow delivery to ios, email and in-app, and each recipient’s preferences still apply.
permissions.shareFile and shareFolder grant an Arg user read, write or manage access; list, update and revoke read and change the direct grants on a path, so a sync script can remove access as well as add it. All of them need a user principal (a session or a user-owned API key), not a service account. The caller needs manage on the path, the recipient must belong to the workspace organization, and a folder grant applies to its descendants. admin is deliberately unavailable because it is a workspace-level permission.
integrations.connections never returns credentials, only which providers are connected. integrations.proxy is a separate server capability for Sites and Servers (see capability tokens); it is not general HTTP authority for a viewer or an agent.
code.run executes a shell command in the workspace sandbox. Inspect status; a non-zero exit is failed, not an exception.
sites frameworks are static, vite, astro, next and worker; access is public or workspace. A build that is not auto-promoted produces a version you promote later. See tunnels and servers for the lifecycle behind servers.

import { notifications, permissions, users } from "@arg/sdk";

const teammate = (await users.list()).find(
  (member) => member.kind === "user" && member.name === "Ada",
);
if (!teammate) throw new Error("Ada is not in this workspace");

await notifications.sendToMe({ title: "Export complete" });
await notifications.sendToUser(teammate.id, {
  title: "Review ready",
  body: "Please review /reports/q3.md",
});
await permissions.shareFile("/reports/q3.md", {
  userId: teammate.id,
  permission: "write",
});

Which hosts serve which namespace is in the availability table. A preview inside Arg serves actions and agents behind the Actions switch; the resource namespaces need a server, CI, arg serve in account mode, a hosted gateway, or an agent script.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Actions, agents and resources

Discover before you run

Run

Connector tools

Agent runs

Workspace resources

​Discover before you run

​Run

​Connector tools

​Agent runs

​Workspace resources

Discover before you run

Run

Connector tools

Agent runs

Workspace resources