docs(sdk): guide for file-based agents

[VascoSch92]

• I have read and reviewed the documentation changes to the best of my ability.
• If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

Summary of changes

Add guide for file-based agents.

[all-hands-bot]

🟡 Acceptable - Solid content with good examples, but has critical documentation gaps that will confuse readers.

[all-hands-bot]

🟡 Acceptable - Solid documentation with good structure, but has a plural/singular consistency bug that was supposedly resolved in a previous review but still exists.

[xingyaoww]

@OpenHands please review latest code from OpenHands/software-agent-sdk and tell me if the instructions documented here are actually implemented there?

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

Summary: Documentation Review of File-Based Agents

I reviewed the latest code from OpenHands/software-agent-sdk to verify whether the instructions documented in sdk/guides/agent-file-based.mdx are actually implemented.

Findings

✅ Core SDK Features - Fully Implemented

All the core file-based agent functionality documented is implemented and working in the SDK:

• AgentDefinition schema with all documented fields (name, description, tools, model, color, when_to_use_examples)
• YAML frontmatter parsing and <example> tag extraction
• load_agents_from_dir(), load_project_agents(), load_user_agents()
• register_file_agents() for auto-registration
• agent_definition_to_factory() for converting definitions to factories
• Directory conventions (.agents/agents/ and .openhands/agents/)
• Built-in "default" agent matching the documented tools
• Correct priority handling (Programmatic > Plugin > Project > User > Builtin)

❌ Example Code Path - Mismatch

The documentation references an example that doesn't exist in the expected form:

Documentation References	Actual SDK
examples/01_standalone_sdk/41_file_based_subagents/41_file_based_subagents.py	examples/01_standalone_sdk/42_file_based_subagents.py
Directory with agents/*.md files	Single .py file
Loads agents from markdown files	Defines AgentDefinition inline

Recommendation

The example referenced in the documentation (lines 305-432) should be created in the SDK repository at examples/01_standalone_sdk/41_file_based_subagents/ with the accompanying agent markdown files, OR the documentation should be updated to reference the existing example 42_file_based_subagents.py and adjust the code shown accordingly.

---

No code changes were made - this was a review/analysis task only.

[enyst]

@OpenHands fix this: the example we document in this PR should be 42_file_based_subagents.py

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[openhands-ai]

Final summary of work (PR #358 – “docs(sdk): guide for file-based agents”)

What you requested

• Update the documented example in sdk/guides/agent-file-based.mdx to use 42_file_based_subagents.py (not the old 41_* example).
• Verify the PR content matches what’s actually implemented in OpenHands/software-agent-sdk.
• Update the PR branch accordingly (commit + push), without posting PR comments.

Checklist: completion + instructions followed

• Located all references to the old example (41_file_based_subagents) in docs/sdk/guides/agent-file-based.mdx.
• Updated the doc to reference examples/01_standalone_sdk/42_file_based_subagents.py in:
  • the GitHub link
  • the synced code block header
  • the <RunExampleCode .../> snippet
• Ran the repo’s code-block sync script against the latest software-agent-sdk to ensure the embedded code block matches the real example file.
• Reverted unrelated sync changes so the diff stayed focused to the file-based agents guide only.
• Reviewed the guide against software-agent-sdk source to confirm the documented behavior exists; fixed minor doc inaccuracies found during review.
• Committed and pushed the changes to the PR branch (issue-2049).
• Did not leave PR comments (per instructions).

Conciseness / extraneous changes

• Only one doc file ended up modified in the final branch: sdk/guides/agent-file-based.mdx.
• Any unrelated auto-sync edits to other guides were reverted before committing.

What changed in the guide (net-new edits)

• Example is now 42_file_based_subagents.py everywhere (link + code block + RunExampleCode).
• Added missing Path imports in snippets that used Path(...).
• Corrected agent_definition_to_factory() explanation to match SDK behavior (AgentContext(system_message_suffix=...), not “always-active Skill”).
• Clarified wording around <example> tags so it doesn’t over-claim current runtime usage.
• Clarified default tool behavior statement (Finish/Think tools appended after filtering).
• Added a short note explaining the ready-to-run example uses AgentDefinition inline, but file-based agents load into the same AgentDefinition type.

Git / PR update

• Commit pushed to issue-2049: c931c13 (“docs(sdk): update file-based agents example to 42_file_based_subagents”)
• Remote branch updated successfully (PR docs(sdk): guide for file-based agents #358 should now reflect the corrected example).

Validation note

• I ran uv run pytest -q tests/; two failures appear unrelated to this guide (pricing test can’t extract openhands_models from upstream OpenHands llm.py).

[enyst]

The deployed page looks good to me now!

[enyst]

LGTM!