> ## Documentation Index
> Fetch the complete documentation index at: https://developers.arg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions, agents and resources

> Discover and run Actions, start agent runs, and reach comments, notifications, integrations, automations, code execution, Sites and servers from one client.

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

```ts theme={null}
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

```ts theme={null}
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`.

## Agent runs

```ts theme={null}
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`](/guides/sdk/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)`                                                                                 |
| `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. 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](/guides/sdk/server#sites-and-servers-with-their-own-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](/guides/tunnels) for the lifecycle behind `servers`.

```ts theme={null}
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](/guides/sdk/reference#availability-by-host). 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.