docs(agents): document agents CLI/SDK/MCP and drop stale references#4111
Merged
saddlepaddle merged 1 commit intomainfrom May 5, 2026
Merged
docs(agents): document agents CLI/SDK/MCP and drop stale references#4111saddlepaddle merged 1 commit intomainfrom
saddlepaddle merged 1 commit intomainfrom
Conversation
Catches the docs and skill up to PR #4097 (which added `superset agents list`, the SDK `Agents` resource, and the `agents_list` MCP tool, and demoted listPresets to a static UI const). - skills/superset/SKILL.md: drop the `superset agents list --local --presets` line — that flag was removed when the catalog stopped being a runtime API resource. - apps/docs/content/docs/cli/cli-reference.mdx: add a new `### agents` section with `superset agents list` and `superset agents run` Command blocks (the run command was never documented). - apps/docs/content/docs/mcp.mdx: add a new `### Agents` table row covering `agents_list` and `agents_run`; remove the spurious `projects_create` row (no such MCP tool exists in `register.ts`). - apps/docs/content/docs/sdk/reference.mdx: drop the stale `**TODO**` Callout in `workspaces.create` that claimed the SDK sends a minimal `agentConfig: { id: 'claude', kind: 'terminal' }`. The SDK now uses the v2 host-service launch shape directly. Add a new `## agents` section documenting `client.agents.list` and `client.agents.run`. - apps/docs/content/docs/sdk/advanced.mdx: drop the same stale `**TODO**` Callout above the Sentry recipe. Style notes for the new entries: CLI Command `output` blocks use inline structural literals (matches `hosts list` / `workspaces list`), MCP table descriptions are terse single-clauses (matches `tasks_*` / `workspaces_*`).
Contributor
|
Caution Review failedPull request was closed or merged during review 📝 WalkthroughWalkthroughDocumentation for a new agents feature is added across multiple surfaces: CLI reference, MCP tools, SDK API reference, and skill documentation. A legacy callout is removed from SDK advanced documentation. ChangesAgents Feature Documentation
🎯 2 (Simple) | ⏱️ ~15 minutes
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
🚀 Preview Deployment🔗 Preview Links
Preview updates automatically with new commits |
Greptile SummaryDocumentation-only PR that brings the CLI reference, MCP tool table, SDK reference, SDK advanced guide, and the Superset skill up to date with the agent changes introduced in #4097. All claimed additions and removals were verified against the live source (
Confidence Score: 4/5All documentation changes are consistent with the actual source code; the only open item is a minor flag description asymmetry that does not affect correctness. Every claimed addition was verified against the live implementation. The removal of
|
| Filename | Overview |
|---|---|
| apps/docs/content/docs/cli/cli-reference.mdx | Adds agents list and agents run Command blocks with correct output shapes and flag definitions; minor asymmetry in the --host mutual-exclusivity note. |
| apps/docs/content/docs/mcp.mdx | Adds agents_list/agents_run table row (verified in register.ts) and removes stale projects_create row (not present in register.ts); accurate. |
| apps/docs/content/docs/sdk/reference.mdx | Replaces stale TODO callout with accurate inline description; new agents section matches agents.ts signatures for list and run exactly. |
| apps/docs/content/docs/sdk/advanced.mdx | Removes outdated TODO callout about stale agentConfig shape; no functional logic changed. |
| skills/superset/SKILL.md | Drops the --presets flag example that was removed in #4097; remaining examples are accurate. |
Sequence Diagram
sequenceDiagram
participant User
participant CLI/SDK/MCP
participant CloudAPI
participant RelayTunnel
participant HostService
User->>CLI/SDK/MCP: agents list (--local | --host id)
CLI/SDK/MCP->>RelayTunnel: settings.agentConfigs.list
RelayTunnel->>HostService: query agentConfigs
HostService-->>RelayTunnel: Array HostAgentConfig
RelayTunnel-->>CLI/SDK/MCP: Array HostAgentConfig
CLI/SDK/MCP-->>User: agent rows
User->>CLI/SDK/MCP: agents run (workspaceId, agent, prompt)
CLI/SDK/MCP->>CloudAPI: v2Workspace.getFromHost (lookup hostId)
CloudAPI-->>CLI/SDK/MCP: hostId
CLI/SDK/MCP->>RelayTunnel: agents.run mutation
RelayTunnel->>HostService: start agent session
HostService-->>RelayTunnel: sessionId + label
RelayTunnel-->>CLI/SDK/MCP: sessionId + label
CLI/SDK/MCP-->>User: sessionId + label
Prompt To Fix All With AI
Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 1
apps/docs/content/docs/cli/cli-reference.mdx:502-503
**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.
Reviews (1): Last reviewed commit: "docs(agents): document agents CLI/SDK/MC..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Comment on lines
+502
to
+503
| { flag: "--host <id>", description: "Target host machineId." }, | ||
| { flag: "--local", description: "Target this machine. Mutually exclusive with --host; exactly one is required." }, |
There was a problem hiding this comment.
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.
saddlepaddle
added a commit
that referenced
this pull request
May 6, 2026
…4111) Catches the docs and skill up to PR #4097 (which added `superset agents list`, the SDK `Agents` resource, and the `agents_list` MCP tool, and demoted listPresets to a static UI const). - skills/superset/SKILL.md: drop the `superset agents list --local --presets` line — that flag was removed when the catalog stopped being a runtime API resource. - apps/docs/content/docs/cli/cli-reference.mdx: add a new `### agents` section with `superset agents list` and `superset agents run` Command blocks (the run command was never documented). - apps/docs/content/docs/mcp.mdx: add a new `### Agents` table row covering `agents_list` and `agents_run`; remove the spurious `projects_create` row (no such MCP tool exists in `register.ts`). - apps/docs/content/docs/sdk/reference.mdx: drop the stale `**TODO**` Callout in `workspaces.create` that claimed the SDK sends a minimal `agentConfig: { id: 'claude', kind: 'terminal' }`. The SDK now uses the v2 host-service launch shape directly. Add a new `## agents` section documenting `client.agents.list` and `client.agents.run`. - apps/docs/content/docs/sdk/advanced.mdx: drop the same stale `**TODO**` Callout above the Sentry recipe. Style notes for the new entries: CLI Command `output` blocks use inline structural literals (matches `hosts list` / `workspaces list`), MCP table descriptions are terse single-clauses (matches `tasks_*` / `workspaces_*`).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Catches the docs and the Superset CLI skill up to #4097, which added
superset agents list, the SDKAgentsresource (list+run), and theagents_listMCP tool — while removinglistPresetsand reshapingaddto take the full launch row.Changes
Skill (
skills/superset/SKILL.md, hardlinked toplugins/superset/skills/superset/SKILL.md):superset agents list --local --presetsexample — that flag was removed when the preset catalog stopped being a runtime API resource. An agent following the skill verbatim would hit "Unknown option: --presets".CLI reference (
apps/docs/content/docs/cli/cli-reference.mdx):### agentssection between### workspacesand### taskswith Command blocks forsuperset agents list(was added in feat(agents): add agents list and demote presets to UI configuration #4097) andsuperset agents run(existed before but was never documented).outputuses an inline structural literal matchinghosts list/workspaces liststyle.MCP doc (
apps/docs/content/docs/mcp.mdx):### Agentstable row coveringagents_list(added in feat(agents): add agents list and demote presets to UI configuration #4097) andagents_run(existed but undocumented).projects_createrow — there's no such MCP tool registered inpackages/mcp-v2/src/tools/register.ts. Pre-existing wrong claim, caught while auditing.SDK reference (
apps/docs/content/docs/sdk/reference.mdx):**TODO**Callout inworkspaces.createclaiming the SDK sends a minimalagentConfig: { id: 'claude', kind: 'terminal' }. The SDK now uses the v2 host-service launch shape directly ({ agent: string, prompt, attachmentIds }).## agentssection documentingclient.agents.list({ hostId })andclient.agents.run({ workspaceId, agent, prompt, attachmentIds? }, { hostId? }).SDK advanced (
apps/docs/content/docs/sdk/advanced.mdx):**TODO**Callout above the Sentry → agent recipe.Out of scope
apps/docs/content/docs/agent-integration.mdxto reflect the V2 Settings → Agents UI fields (command,args,promptTransport,promptArgs,env) instead of the V1 fields it currently lists. Tangled with the V1/V2 split and probably wants UI screenshots refreshed; deserves its own pass.Test plan
bun run lintcleanbun run devinapps/docs) to confirm the new Command blocks render correctly and the new## agentssection anchors work.Summary by cubic
Documents the Agents surface across CLI, SDK, and MCP, and removes stale flags and TODOs. Brings docs in line with
superset agents list/runand the SDKAgentsresource.agentssection withsuperset agents listandsuperset agents run(output shape, examples).agents.list({ hostId })andagents.run({ workspaceId, agent, prompt, attachmentIds? }, { hostId? }). Updateworkspaces.createto describe the v2 launch shape; remove outdated TODOs.agents_listandagents_run; removeprojects_create(no such tool).--presetsexample fromsuperset agents list(flag no longer exists).Written for commit 2b995d4. Summary will update on new commits.
Summary by CodeRabbit
Documentation
superset agents listandsuperset agents run