Initial SDK docs & automatic way to sync agent-sdk example code

[xingyaoww]

• 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

• Updated the main page of "agent-sdk" w/ @rbren's change
• Initial scaffold for "guide" examples for hello world, custom tools, and MCP
• add a github workflow to automatically sync examples from agent-sdk codebase to the docs codebase

[enyst]

Should this reference the first, hello world, example?

[xingyaoww]

You are absolute right! (sonnet face)

@OpenHands please review examples/01_standalone_sdk/01_hello_world.py and update sdk/getting-started.mdx to reference the example there

[openhands-ai]

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

[openhands-ai]

Summary

I've successfully updated sdk/getting-started.mdx to reference the actual hello world example from the agent-sdk repository, addressing @enyst's comment on PR #32.

Changes Made:

✅ Replaced inline code with example reference: Changed the code block format from a generic inline example to use the special syntax ````python icon="python" expandable examples/01_standalone_sdk/01_hello_world.pythat enables automatic syncing via thesync_code_blocks.py` workflow.

✅ Updated code content: Replaced the simplified inline example with the actual content from examples/01_standalone_sdk/01_hello_world.py, which includes:

• Correct import path: openhands.tools.preset.default (not openhands.sdk.preset.default)
• Additional LLM configuration options: base_url, usage_id, and model environment variable
• Proper workspace initialization pattern
• More realistic task example

✅ Updated instructions: Changed the run command to reference the actual example file path and updated the description to match what the example does.

✅ Removed redundancy: Removed the duplicate reference link at the end since the code block now directly references the example file.

Result:

The documentation will now automatically stay in sync with the agent-sdk repository's hello world example through the automated workflow. The changes have been committed and pushed to the sdk branch, updating PR #32.

Commit: 6133057 - "docs: reference hello world example from agent-sdk"

_{View full conversation}

[openhands-ai]

Summary of my work on /codereview-roasted for PR #32 (branch sdk)

What I did

• Checked out branch sdk and reviewed the full diff against main.
• Audited the new sync script, workflows, and all added/modified SDK docs (guides, index, navigation).
• Validated docs.json and inspected code blocks and example references for correctness.

Top blockers (must-fix before merge)

• Broken repository structure: agent-sdk is a gitlink/submodule entry without a .gitmodules file. Decide: remove the submodule and treat agent-sdk as a non-tracked workspace dir, or add a proper .gitmodules and initialize it in CI.
• Broken link: sdk/index.mdx links to /sdk/guides/getting-started, but the file is sdk/getting-started.mdx (nav uses sdk/getting-started). Update the href.
• Inconsistent API/imports in examples:
  • hello-world.mdx imports get_default_agent from openhands.tools.preset.default, while getting-started.mdx uses openhands.sdk.preset.default. Pick one and keep it consistent.
  • hello-world uses LLM(... usage_id="agent") while the “LLM Configuration” snippet shows service_id="agent". Align on the correct parameter name.
• CI workflow scope/behavior:
  • sync-docs-code-blocks.yml triggers on push to all branches and can push directly. This risks surprise commits and churn. Limit triggers (e.g., main + PR) and prefer creating a PR on schedule.
  • The sync script exits 1 if agent-sdk path is missing; combined with set -euo this hard-fails CI for a non-critical task. Make it a no-op with a clear log.
• OpenAPI mismatch: docs.json’s API Reference points to openapi/openapi.json, but sync-sdk-changes.yml generates openapi/agent-sdk.json. Align these or consolidate to one spec.

Important improvements (should fix)

• sync_code_blocks.py robustness:
  • Regex can mis-capture if code contains backticks. Anchor the closing fence and use multiline flags.
  • Replace blocks using the known start/end slice instead of re-searching the opening line.
  • Remove the walrus alias noise (mdxx_file := mdx_file) and the duplicated “Found … code block(s)” log.
• CI outputs: You compute “changes” both in Python and via git status. Keep the git-based detection and drop the GITHUB_OUTPUT writes from the script.
• Architecture links: Navigation uses sdk/arch/... while pages link to /sdk/architecture/.... Unify path conventions across nav and prose.
• Custom tools guide polish: Remove duplicate “# Agent” comment; consider safer quoting for --include and/or a max-results parameter.
• MCP guide: The filter_tools_regex example is complex—offer a simpler pattern and call out debugging tips.
• Package install UX: If users need multiple packages (openhands-sdk, openhands-tools, openhands-workspace, openhands-agent-server), add a “install everything” snippet to prevent import errors.
• Consistent domains: Normalize all-hands.dev vs openhands.dev references.

Style/consistency notes

• Consider quieter CI logging for the sync script.
• Normalize newline handling to avoid churn on trailing newlines.
• Keep claims in marketing copy stable over time.

Verdict
Needs rework before merge. The content is strong, but user-facing correctness issues (links/imports), a submodule foot-gun, and brittle CI behavior will cause immediate breakage.

Key insight
You combined docs, automation, and repo layout changes; small inconsistencies multiply. Standardize paths/imports and make the sync workflow conservative and idempotent to avoid noisy CI and broken examples.

If you want, I can implement these fixes on sdk and re-run the checks.

_{View full conversation}

[enyst]

I'm not sure if GPT-5 is correct or not, but I had it make a PR anyway, not modify this branch directly.

Up to you if you want to merge and deal with its proposals later, I looked though the deployment and it's beautiful!