docs(sdk): remove stale agent-delegation (DelegateTool) guide

[VascoSch92]

What

Removes the stale Sub-Agent Delegation guide (sdk/guides/agent-delegation.mdx) and repairs every reference to it.

Why

The page documents a public DelegateTool API that no longer exists in software-agent-sdk@main — every code block on it is broken, and the delegation feature has moved to TaskToolSet:

• from openhands.tools.delegate import DelegateTool → no such symbol (delegate/__init__.py exports only DelegateAction, DelegateObservation, ConfirmationHandler, DelegateExecutor, DelegationVisualizer).
• register_tool("DelegateTool", DelegateTool) / Tool(name="DelegateTool") → no such registered tool.
• class CustomDelegateTool(DelegateTool).create(max_children=...) → no such class/method (max_children=5 now lives on DelegateExecutor.__init__).
• The "ready-to-run example" embeds a copy of 25_agent_delegation.py that uses DelegateTool, but the real file now uses TaskToolSet.

Full analysis in #588.

Changes

• Delete sdk/guides/agent-delegation.mdx and its docs.json nav entry

• task-tool-set.mdx: remove the TaskToolSet vs DelegateTool comparison table and the parallel-delegation <Tip>

• Repoint the delegation cross-links in agent-acp.mdx, agent-settings.mdx, agent-tom-agent.mdx, iterative-refinement.mdx, parallel-tool-execution.mdx to the surviving task-tool-set guide

• agent-file-based.mdx: rewrite the Using with Delegation section and the ready-to-run example off the removed DelegateTool API to TaskToolSet — Tool(name=TaskToolSet.name) (the tool auto-registers on import, so register_tool(...) is dropped). File-based agents register into the same subagent registry the task tool resolves subagent_type against, so they work with TaskToolSet directly. Section now links to the task-tool-set guide. (Addresses the review on this section.)

• AGENTS.md / .agents/skills/code-review.md: drop agent-delegation.mdx from the file-naming examples

• llms context files (llms.txt / llms-full.txt): per review, scrubbed the committed overrides so the deleted guide stops shipping to LLM consumers, and mirrored the agent-file-based.mdx DelegateTool → TaskToolSet code-block fixes into llms-full.txt. Done as a targeted edit (remove the listing + the embedded section, mirror the source link repoints / table / Tip / code blocks) rather than a full make llms run, to avoid bundling ~217 lines of unrelated pre-existing drift from other pages (left to the weekly check-llms-files sync job). Verified the result is byte-identical to generator output for these changes.

No /sdk/guides/agent-delegation links remain in any .mdx, so mint broken-links stays green.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	Jun 24, 2026, 7:01 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[VascoSch92]

Good catch — fixed in 991fd69. The committed llms.txt / llms-full.txt overrides were still publishing the deleted guide, which defeats the purpose.

I went with the "equivalent targeted edit" option rather than a full python3 scripts/generate-llms-files.py, because a clean regeneration here also pulls in ~217 lines of unrelated pre-existing drift from other pages (e.g. the Analytics description changed from "Get started with LLM observability…" to "Deploy Laminar for trace analysis…"). That drift is the weekly check-llms-files.yml sync job's responsibility; folding it into this deletion PR would muddy the diff.

The targeted edit:

• removes the Sub-Agent Delegation listing from llms.txt
• removes the embedded agent-delegation page section from llms-full.txt
• mirrors the source .mdx repoints (cross-links → task-tool-set, drops the TaskToolSet vs DelegateTool table and the parallel-delegation <Tip>)

To confirm it's equivalent to a real regeneration for this change, I ran the generator onto copies and diffed: the agent-delegation/DelegateTool content is byte-identical to generator output, and the only remaining difference is the unrelated drift above. There are now zero agent-delegation references anywhere in the tree (.mdx, .json, .txt, .md).

Re-requesting review.

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

🟢 Taste Rating: Good taste — this is a focused deletion of a stale guide plus the necessary navigation, cross-link, and committed LLM-context cleanup.

Source Verification

Documentation Claim	Verified?	Source Evidence
The deleted DelegateTool guide documented a public API surface that is no longer exported.	✅	openhands.tools.delegate exports DelegateAction, DelegateObservation, ConfirmationHandler, DelegateExecutor, and DelegationVisualizer, but not DelegateTool: https://github.com/OpenHands/software-agent-sdk/blob/22408f65ffcc3115b4982b03af8a2422bb3ed16e/openhands-tools/openhands/tools/delegate/__init__.py#L3-L17
TaskToolSet is the current registered sub-agent task toolset and exposes prompt, subagent_type, and resume.	✅	TaskAction defines those fields: https://github.com/OpenHands/software-agent-sdk/blob/22408f65ffcc3115b4982b03af8a2422bb3ed16e/openhands-tools/openhands/tools/task/definition.py#L37-L54 and TaskToolSet is registered on import: https://github.com/OpenHands/software-agent-sdk/blob/22408f65ffcc3115b4982b03af8a2422bb3ed16e/openhands-tools/openhands/tools/task/definition.py#L198-L262
The replacement links point users toward an active example-based guide.	✅	The SDK example imports TaskToolSet and configures it as the tool on the main agent: https://github.com/OpenHands/software-agent-sdk/blob/22408f65ffcc3115b4982b03af8a2422bb3ed16e/examples/01_standalone_sdk/41_task_tool_set.py#L16-L20 and https://github.com/OpenHands/software-agent-sdk/blob/22408f65ffcc3115b4982b03af8a2422bb3ed16e/examples/01_standalone_sdk/41_task_tool_set.py#L69-L72
The stale /sdk/guides/agent-delegation route is no longer referenced by this docs repo's tracked files.	✅	Verified locally with git grep -n "agent-delegation" at PR head; it returns no matches.
The committed LLM context overrides no longer publish the deleted guide.	✅	Regenerated llms.txt / llms-full.txt in a temporary clone; the generated files also have no agent-delegation references. The remaining generator diff is unrelated pre-existing Laminar/analytics drift, matching the PR author's explanation.
Internal link safety for the docs site.	✅	The PR check Check Internal Links (Mintlify) is passing on this head.

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW
  Docs-only deletion and link cleanup. The main risk was stale committed LLM outputs continuing to ship the removed page; this head now addresses that, and the remaining generator drift is unrelated to this PR's scope.

VERDICT:
✅ Worth merging: The previous blocking issue is addressed, the stale guide is removed from nav and LLM-context outputs, and the replacement links target the current TaskToolSet documentation.

KEY INSIGHT:
For this repository, removing a page is complete only when docs.json, cross-links, and the committed llms overrides all stop surfacing it.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[enyst]

Is this still accurate?

[VascoSch92]

Good catch — it wasn't. Fixed in 44f916c: this section (and the ready-to-run example below it) now use TaskToolSet instead of the removed DelegateTool. register_file_agents() registers file-based agents into the same subagent registry the task tool resolves subagent_type against, so they work with the task tool directly — no register_tool() needed (it auto-registers on import). Mirrored the same edits into llms-full.txt.

[enyst]

It seems we might have a leftover, please see inline comment

[VascoSch92]

@enyst Thanks :-) I fixed it.