docs(sdk): polish SDK docs + CI follow-ups from review (PR-only sync, links, usage_id) #33

enyst · 2025-10-20T21:16:03Z

Summary

Fixes from roasted review and follow-ups on branch sdk
Keep solutions minimal; no changes to MCP filter_tools_regex example

Key changes

CI/workflows

sync-sdk-changes.yml: Stop mutating branches. Generate Agent SDK OpenAPI then create a branch and open a PR via peter-evans/create-pull-request. Added pull-requests: write permission and switched bot identity to openhands.dev.
sync-docs-code-blocks.yml (already present on this branch): guarded triggers (main,sdk), no direct pushes; uses create-pull-request when content changes.

Sync script hardening

.github/scripts/sync_code_blocks.py: No-op when agent-sdk path is not found (graceful), removed walrus operator in update path, simplified block replacement and comparison. Script no longer writes to GITHUB_OUTPUT; workflow owns outputs.

Docs information architecture

docs.json: “Agent SDK (v1)” tab is primary for v1. Added an OpenAPI tab for Agent SDK pointing to openapi/agent-sdk.json. Left the legacy “OpenHands (Core) API)” tab in place for now; it can be removed when v0 is officially retired on sdk.

Broken links and consistency

Replaced dead /sdk/architecture/* links with working destinations (or removed when no stable target existed yet). Example pages updated:
- sdk/guides/hello-world.mdx
- sdk/guides/custom-tools.mdx
- sdk/guides/mcp.mdx
Hello World import fixed to from openhands.sdk.preset.default import get_default_agent.
LLM terminology unified to usage_id across the examples shown.

Domain migration

Migrated external site links to openhands.dev where appropriate (company/blog/app/docs). Intentionally preserved docker., runtime., jira.* hosts.

Notes

openapi/agent-sdk.json is not versioned in this branch; sdk target branch contains it and the dedicated sync workflow. The new OpenAPI tab will function post-merge.
MCP examples (including filter_tools_regex) are unchanged per request.

Testing

Basic link audit via grep; docs build expected to pick up both OpenAPI tabs once merged to sdk.

Request
Please review and merge into sdk (PR #32 source branch). This keeps CI non-destructive (PR-only), fixes broken links, and aligns SDK docs with v1 expectations.

@enyst can click here to continue refining the PR

Synced from agent-sdk ref: main

Co-authored-by: Engel Nyst <enyst@users.noreply.github.com>

Update sdk/getting-started.mdx to reference the actual hello world example file (examples/01_standalone_sdk/01_hello_world.py) instead of maintaining inline code. This allows the sync_code_blocks.py workflow to automatically keep the documentation in sync with the agent-sdk repository. Co-authored-by: openhands <openhands@all-hands.dev>

- Remove agent-sdk gitlink from index and add to .gitignore - Avoid broken submodule state and clarify intended local checkout behavior Co-authored-by: openhands <openhands@all-hands.dev>

- Don’t hard-fail when agent-sdk path is missing; exit cleanly - Replace blocks using known slice instead of inner regex - Remove GITHUB_OUTPUT coupling; rely on git status in workflow Co-authored-by: openhands <openhands@all-hands.dev>

- Limit to main/sdk pushes and PRs - Use peter-evans/create-pull-request to open PR instead of direct push Co-authored-by: openhands <openhands@all-hands.dev>

- Fix /sdk/getting-started link on SDK index - Hello World: use openhands.sdk.preset.default.get_default_agent and usage_id - Remove duplicate heading in custom-tools example - Workflow: only run on main/sdk and open PR for updates - Script: no-op if agent-sdk missing; simpler replacement - Ignore local agent-sdk checkout and remove gitlink Co-authored-by: openhands <openhands@all-hands.dev>

…o-authored-by: openhands <openhands@all-hands.dev>

- Add separate API tab for agent-sdk.json (generated by workflow) - Update company/blog/cloud anchors to openhands.dev Co-authored-by: openhands <openhands@all-hands.dev>

- Replace all-hands.dev -> openhands.dev for app/docs/blog/home - Preserve docker.* and jira.* hosts as-is Co-authored-by: openhands <openhands@all-hands.dev>

…pens PRs only - Replace /sdk/architecture/* links with working /sdk/arch/llms/* or remove - Hello World imports fixed and usage_id consistent - Domain move to openhands.dev; keep docker.* and jira.* - sync_code_blocks.py: no-op if SDK missing; remove walrus operator; simpler block replace - sync-sdk-changes workflow: create branch + PR for OpenAPI updates - docs.json: Agent SDK (v1) is primary; add OpenAPI tab for Agent SDK Co-authored-by: openhands <openhands@all-hands.dev>

…ot identity - Add pull-requests: write - Use create-pull-request for agent-sdk OpenAPI updates - Update bot name/email to openhands.dev Co-authored-by: openhands <openhands@all-hands.dev>

jamiechicago312 · 2025-10-20T21:58:59Z

Will review first thing tomorrow 👍

enyst · 2025-10-20T22:04:00Z

Thank you. They're actually to Xingyao's PR, so it's like, they're meant to be:

either included in his PR
or submitted to main, after his PR is merged in main.

…g deletion (replaced by sync-agent-sdk-openapi.yml)

openhands-ai · 2025-10-20T22:12:53Z

Looks like there are a few issues preventing this PR from being merged!

GitHub Actions are failing:
- Sync Documentation Code Blocks

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #33 at branch `pr/sync-openapi-prs`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

mamoodi · 2025-10-21T12:58:08Z

Looks generally okay. I don't know what the sync job is for but wondering if it's just for SDK, it can just run when SDK changes or something.

Also can you run: mint broken-links
to make sure there's no broken links please. The API tabs will show up as broken links and that's a known issue in mintlify.

enyst · 2025-10-21T13:00:49Z

Yes, it’s a bit in flux. I think this PR or the other were trying to fix broken links.

…openapi-prs

Synced from agent-sdk ref: main

sdk/guides/custom-tools.mdx

Synced from agent-sdk ref: main

…ructure (#33) Co-authored-by: openhands <openhands@all-hands.dev>

xingyaoww and others added 30 commits October 17, 2025 16:16

add update-docs

d0ced56

add workflow to sync sdk changes

eb53362

Merge branch 'main' into sdk

f6b8805

push to same branch

9e55965

Merge commit 'f6b8805627ffd5842fe4969e2a737baf93eee584' into sdk

a282aff

remove old workflow

a7f0af2

update sync sdk changes workflow

38a8a4e

Merge branch 'main' into sdk

8a1edc4

initial docs

b78c5a8

Merge commit '8a1edc4093417e5f2936ac799af36a29f0b36bd0' into sdk

498a1da

update how to install

4a27d79

update index

12e1160

add workflow to sync code blocks

b5da598

finish agent-sdk

7212560

add mcp eample

8c37280

make mcp as a few sections

57cae33

refactor example

785d5e3

run sync docs on every push

c33885f

add repo.md

032d52a

fix ci

6ea863a

try fix workflow

54a658c

Merge branch 'main' into sdk

369e3a6

refactor

ce42986

move workflow

f8bae5e

remove overview first

7c1b0d3

reorg tests

f80e372

fix bug

30684b5

docs: sync code blocks from agent-sdk examples [skip ci]

b5b7c2e

Synced from agent-sdk ref: main

still run ci

b487387

Merge commit 'b5b7c2e8ad90e0a18904fee3cca18c4c1c100cb0' into sdk

98eae25

xingyaoww and others added 11 commits October 21, 2025 03:28

Update sdk/index.mdx

a3aaac2

Co-authored-by: Engel Nyst <enyst@users.noreply.github.com>

docs: ignore local agent-sdk checkout; remove dangling submodule gitlink

4696baf

- Remove agent-sdk gitlink from index and add to .gitignore - Avoid broken submodule state and clarify intended local checkout behavior Co-authored-by: openhands <openhands@all-hands.dev>

ci(docs): tighten sync workflow triggers and land via PR

36200cc

- Limit to main/sdk pushes and PRs - Use peter-evans/create-pull-request to open PR instead of direct push Co-authored-by: openhands <openhands@all-hands.dev>

docs(sdk): use usage_id terminology in LLM docs (was service_id)\n\nC…

edf3e59

…o-authored-by: openhands <openhands@all-hands.dev>

docs: add Agent SDK OpenAPI tab and align domain to openhands.dev

c20cae0

- Add separate API tab for agent-sdk.json (generated by workflow) - Update company/blog/cloud anchors to openhands.dev Co-authored-by: openhands <openhands@all-hands.dev>

chore: migrate external links to openhands.dev domain

1bd200b

- Replace all-hands.dev -> openhands.dev for app/docs/blog/home - Preserve docker.* and jira.* hosts as-is Co-authored-by: openhands <openhands@all-hands.dev>

ci: route OpenAPI sync via PR with proper permissions and OpenHands b…

abb27a4

…ot identity - Add pull-requests: write - Use create-pull-request for agent-sdk OpenAPI updates - Update bot name/email to openhands.dev Co-authored-by: openhands <openhands@all-hands.dev>

enyst requested review from jamiechicago312 and mamoodi as code owners October 20, 2025 21:16

merge(sdk->pr/sync-openapi-prs): resolve workflow conflict by adoptin…

9f44a1b

…g deletion (replaced by sync-agent-sdk-openapi.yml)

xingyaoww changed the base branch from sdk to main October 21, 2025 13:02

xingyaoww self-requested a review as a code owner October 21, 2025 13:02

xingyaoww and others added 2 commits October 21, 2025 09:08

Merge commit '9a3e25b74c64be42826b0e1214aa07d9ffea0279' into pr/sync-…

25236a9

…openapi-prs

docs: sync code blocks from agent-sdk examples

2fe76d7

Synced from agent-sdk ref: main

xingyaoww reviewed Oct 21, 2025

View reviewed changes

sdk/guides/custom-tools.mdx Outdated Show resolved Hide resolved

xingyaoww and others added 2 commits October 21, 2025 21:09

Apply suggestion from @xingyaoww

25f26e3

docs: sync code blocks from agent-sdk examples

a26a641

Synced from agent-sdk ref: main

xingyaoww approved these changes Oct 21, 2025

View reviewed changes

xingyaoww merged commit 9d43f75 into main Oct 21, 2025

jamiechicago312 deleted the pr/sync-openapi-prs branch October 21, 2025 17:30

enyst pushed a commit that referenced this pull request Nov 8, 2025

Restructure agent-sdk repository into UV workspace with simplified st…

f233b21

…ructure (#33) Co-authored-by: openhands <openhands@all-hands.dev>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(sdk): polish SDK docs + CI follow-ups from review (PR-only sync, links, usage_id) #33

docs(sdk): polish SDK docs + CI follow-ups from review (PR-only sync, links, usage_id) #33

Uh oh!

enyst commented Oct 20, 2025

Uh oh!

jamiechicago312 commented Oct 20, 2025

Uh oh!

enyst commented Oct 20, 2025

Uh oh!

openhands-ai bot commented Oct 20, 2025

Uh oh!

mamoodi commented Oct 21, 2025

Uh oh!

enyst commented Oct 21, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

docs(sdk): polish SDK docs + CI follow-ups from review (PR-only sync, links, usage_id) #33

docs(sdk): polish SDK docs + CI follow-ups from review (PR-only sync, links, usage_id) #33

Uh oh!

Conversation

enyst commented Oct 20, 2025

Uh oh!

jamiechicago312 commented Oct 20, 2025

Uh oh!

enyst commented Oct 20, 2025

Uh oh!

openhands-ai bot commented Oct 20, 2025

Uh oh!

mamoodi commented Oct 21, 2025

Uh oh!

enyst commented Oct 21, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants