Skip to content

docs(agents): document agents CLI/SDK/MCP and drop stale references #4111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
saddlepaddle merged 1 commit into from
May 5, 2026
Merged

docs(agents): document agents CLI/SDK/MCP and drop stale references #4111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions apps/docs/content/docs/cli/cli-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -489,6 +489,63 @@ superset workspaces delete ws_a ws_b ws_c

---

### agents

Agents are terminal-agent rows configured on a host (the same rows shown in
Settings → Agents on that machine). Each row stores a `command`, `args`,
prompt-transport mode, and environment used to launch the agent in a fresh
terminal session inside a workspace.

<Command
name="superset agents list"
options={[
{ flag: "--host <id>", description: "Target host machineId." },
{ flag: "--local", description: "Target this machine. Mutually exclusive with --host; exactly one is required." },
Comment on lines +502 to +503
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot May 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Asymmetric constraint description on mutually exclusive flags

Only the --local option description says "Mutually exclusive with --host; exactly one is required." The --host description is silent about the constraint. A reader who only skims the --host row won't know that omitting both flags is an error, which could cause confusion when the command rejects bare invocations like superset agents list. Consider adding the mutual-exclusivity note to the --host description as well, to mirror the pattern used in the --local entry.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: apps/docs/content/docs/cli/cli-reference.mdx
Line: 502-503

Comment:
**Asymmetric constraint description on mutually exclusive flags**

Only the `--local` option description says "Mutually exclusive with --host; exactly one is required." The `--host` description is silent about the constraint. A reader who only skims the `--host` row won't know that omitting both flags is an error, which could cause confusion when the command rejects bare invocations like `superset agents list`. Consider adding the mutual-exclusivity note to the `--host` description as well, to mirror the pattern used in the `--local` entry.

How can I resolve this? If you propose a fix, please make it concise.

]}
output={`Array<{
id: string;
presetId: string;
label: string;
command: string;
args: string[];
promptTransport: "argv" | "stdin";
promptArgs: string[];
env: Record<string, string>;
order: number;
}>`}
humanColumns={["LABEL", "PRESET", "COMMAND", "ID"]}
quiet="agent instance IDs"
>
List agents configured on a host. First call on a fresh host seeds the
bundled defaults.

```bash
superset agents list --local
superset agents list --host host_…
```
</Command>

<Command
name="superset agents run"
options={[
{ flag: "--workspace <id>", required: true, description: "Workspace UUID to run the agent in." },
{ flag: "--agent <preset|uuid>", required: true, description: "Agent preset id (e.g. `claude`, `codex`) or HostAgentConfig instance UUID." },
{ flag: "--prompt <text>", required: true, description: "Prompt sent to the agent." },
{ flag: "--attachment-id <uuid>", description: "Host-scoped attachment UUID; pass repeatedly for multiple attachments." },
]}
output={`{ sessionId: string; label: string }`}
>
Launch an agent inside an existing workspace. Resolves the host that owns the
workspace and starts the named preset (or HostAgentConfig instance) in a
fresh terminal session on that host.

```bash
superset agents run --workspace ws_… --agent claude --prompt "Audit the login flow"
```
</Command>

---

### tasks (alias: `t`)

Tasks are units of work in your organization's task tracker.
Expand Down
8 changes: 7 additions & 1 deletion apps/docs/content/docs/mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,13 @@ API keys grant full access to your organization. Keep them secret and never comm
| `workspaces_create` | Create a workspace on a host (branch-scoped git worktree) |
| `workspaces_delete` | Delete a workspace by UUID; idempotent |

### Agents

| Tool | Description |
|------|-------------|
| `agents_list` | List agents configured on a host |
| `agents_run` | Launch an agent inside an existing workspace |

### Automations

| Tool | Description |
Expand All @@ -265,7 +272,6 @@ API keys grant full access to your organization. Keep them secret and never comm
| Tool | Description |
|------|-------------|
| `projects_list` | List projects (checked-out repos) in the active organization |
| `projects_create` | Register a project on a host: clone a Git URL or import an existing local repo |

### Hosts

Expand Down
4 changes: 0 additions & 4 deletions apps/docs/content/docs/sdk/advanced.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,6 @@ The SDK's individual methods are simple. The interesting part is what you compos

## Sentry webhook → agent on the bug

<Callout type="info">
**TODO** — the `agents: [{ prompt }]` shorthand below is the API we're aiming for. Today the SDK sends a minimal `agentConfig: { id: 'claude', kind: 'terminal' }`; the host service still needs full launch info (`command`, `promptCommand`, …) to actually start the agent. We'll bake in defaults for built-in presets in a follow-up. Until then you can pass a full `agentConfig` per agent — crib one from `(await client.automations.list())[0].agentConfig`.
</Callout>

When Sentry fires an alert, file a task and spawn an agent to investigate — all in two SDK calls. (In production, verify the Sentry signature header before trusting any payload — that part is omitted here for clarity.)

```ts title="sentry-webhook.ts"
Expand Down
40 changes: 37 additions & 3 deletions apps/docs/content/docs/sdk/reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,9 +119,7 @@ Returns `Array<Workspace>`.

Create a worktree on a specific host. Optionally spawn one or more agents inside it as soon as the worktree is ready. Goes through the relay tunnel — the host must be online.

<Callout type="info">
**TODO** — the `agents` shorthand is the surface we're aiming for. The SDK currently sends a minimal `agentConfig: { id: 'claude', kind: 'terminal' }`; the host service still needs full launch info (`command`, `promptCommand`, …) to actually start the agent. We'll bake in defaults for built-in presets in a follow-up. Until then, pass a full `agentConfig` (crib one from `(await client.automations.list())[0].agentConfig`).
</Callout>
Each entry in `agents` takes a preset id (e.g. `"claude"`) or a `HostAgentConfig` instance UUID — the host service resolves it against its configured rows and copies their stored `command`, `args`, and `env`. Use [`agents.list({ hostId })`](#agentslist-hostid-) to enumerate what's installed.

```ts
const ws = await client.workspaces.create({
Expand Down Expand Up @@ -177,6 +175,42 @@ const online = hosts.filter((h) => h.online);

---

## agents

Terminal-agent rows configured on a specific host (the same rows shown in
Settings → Agents on that machine). Reads route through the relay tunnel —
the target host must be online.

### `agents.list({ hostId })`

List configured agents on a host in persisted display order. First call on a
fresh host seeds the bundled defaults. Returns `Array<HostAgentConfig>` —
each row carries `id`, `presetId`, `label`, `command`, `args`, `env`, and
prompt-transport fields used to launch the agent.

```ts
const agents = await client.agents.list({ hostId: '<machineId>' });
```

### `agents.run({ workspaceId, agent, prompt, attachmentIds? }, { hostId? })`

Launch an agent inside an existing workspace. By default looks up the host
that owns the workspace via the cloud index; pass an explicit `hostId` to
skip the lookup.

`agent` accepts either a preset id (e.g. `"claude"`) or a `HostAgentConfig`
instance UUID. Returns `{ sessionId, label }`.

```ts
const { sessionId } = await client.agents.run({
workspaceId: '<uuid>',
agent: 'claude',
prompt: 'Audit the login flow for race conditions.',
});
```

---

## automations

Recurring agent runs scheduled by RRULE. Requires a Pro subscription on the org for `create` / `update` / `delete`.
Expand Down
1 change: 0 additions & 1 deletion skills/superset/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,6 @@ Provide exactly one of `--branch` or `--pr`. With `--pr`, the host runs `gh pr c
```bash
superset agents list --host <id> # Configured agents on a host (LABEL, PRESET, COMMAND, ID)
superset agents list --local # Same, for this machine
superset agents list --local --presets # Available presets you could add
superset agents run --workspace <id> --agent claude --prompt "..."
```

Expand Down
Loading