docs: weekly architecture docs refresh #169

enyst · 2025-12-09T07:07:34Z

Summary of updates

This weekly refresh updates the SDK architecture documentation under sdk/arch based on the latest HEAD of OpenHands/software-agent-sdk (commit 93d405c9).

Updated pages

sdk/arch/agent-server.mdx

Rewrote the page to accurately reflect the current FastAPI app, routers, services, and WebSocket endpoints.
Clarified that the Agent Server itself does not orchestrate containers; containerization is handled by workspace implementations (e.g., DockerWorkspace) that launch the server.
Added explicit endpoint inventory grouped by router, and authentication details (X-Session-API-Key header for HTTP and session_api_key query parameter for WebSockets).
Included component diagrams aligned with current code.
Added Last updated timestamp and source commit.

sdk/arch/security.mdx

Fixed incorrect source link path (openhands-sdk/openhands/sdk/security).
Added ConfirmationPolicy reference to the key components table.
Appended Last updated timestamp and source commit.

Citations (inline in the docs)

openhands-agent-server/openhands/agent_server/api.py (app wiring, lifespan)
openhands-agent-server/openhands/agent_server/dependencies.py (authentication headers and query parameter for WebSocket)
openhands-agent-server/openhands/agent_server/conversation_router.py (conversation endpoints)
openhands-agent-server/openhands/agent_server/event_router.py (event endpoints)
openhands-agent-server/openhands/agent_server/sockets.py (WebSocket endpoints)
openhands-agent-server/openhands/agent_server/file_router.py (file upload/download)
openhands-agent-server/openhands/agent_server/git_router.py (git endpoints)
openhands-agent-server/openhands/agent_server/tool_router.py (tool listing)
openhands-workspace/openhands/workspace/docker/workspace.py (server launched by workspace)
openhands-sdk/openhands/sdk/security/* (analyzers, risks, confirmation policy)

Source of truth

software-agent-sdk commit: 93d405c91edbaccd84d7b0a356340123a911a6cb

Process notes

Followed the Guide for Writing Architecture Component Documentation.
Kept changes scoped to architecture pages; no guides or API reference modified beyond necessary link fixes.
CI: Please run pre-commit hooks in CI as configured.

@enyst can click here to continue refining the PR

- Update agent-server.mdx to reflect current server responsibilities and endpoints (source: openhands-agent-server/*) - Fix security.mdx source link; add ConfirmationPolicy reference; add Last updated and Source commit footer Co-authored-by: openhands <openhands@all-hands.dev>

…)\n\nCo-authored-by: openhands <openhands@all-hands.dev>

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

xingyaoww

Weird -- i don't think agent server package is included in docs.json?

…ples, inline source links\n\nCo-authored-by: openhands <openhands@all-hands.dev>

…inline source links\n\nCo-authored-by: openhands <openhands@all-hands.dev>

Place agent-server at the end of the SDK Components section for consistent ordering. Co-authored-by: openhands <openhands@all-hands.dev>

…'Agent Server', and simplify selected endpoints Also keeps concise Client SDK REST + WebSocket examples with inline GitHub source links. Co-authored-by: openhands <openhands@all-hands.dev>

enyst · 2025-12-22T11:39:00Z

Weird -- i don't think agent server package is included in docs.json?

Added! But now I'm not sure: did we leave it out intently, for a reason like, we recommend to use the remote workspace to handle communication? That doesn't apply to communication from other languages than python, so it seems like it can be useful.

On a side note, the existing document contained a lot of hallucinations, a lot fixed. 😅

enyst · 2025-12-22T11:41:56Z

@OpenHands We have syntax errors in mintlify for the two initial diagrams, please fix. This is one, but look at the next one too:

Architecture
Syntax error in text
mermaid version 11.4.1
App construction and route wiring happen in api.py: a single /api router includes conversation, event, tool, bash, git, file, vscode, and desktop routers.
Event and VSCode/Desktop services are initialized in the lifespan context (api.py).

openhands-ai · 2025-12-22T11:42:06Z

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

…ards, avoid /* and braces in labels) - Replace '/api/*' and '/sockets/*' with safe labels in diagrams - Replace '{id}' with '<id>' in node label Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2025-12-22T11:55:04Z

Summary of changes just made

What I fixed

Resolved Mermaid syntax errors in Mintlify for the initial diagrams on the Agent Server architecture page.

Why it was failing

Labels containing “/api/” and “/sockets/” were parsed as the start of a comment (/*) by Mermaid v11, breaking the diagram.
A node label included curly braces “{id}”, which can also cause parsing issues.

Precise edits

sdk/arch/agent-server.mdx
- Architecture diagram:
  - Routers label: “Routers (/api/*)” → “Routers (/api)”
  - Events node: “conversations/{id}/events” → “conversations//events”
  - WS node: “/sockets/* (WebSocket)” → “/sockets (WebSocket)”
- Authentication diagram:
  - HTTP node: “HTTP /api/*” → “HTTP /api”
  - WS node: “/sockets/*” → “/sockets”

Validation

Checked the git diff to ensure only minimal, relevant changes were made.
Changes are concise and scoped to fixing Mermaid parsing errors in the two initial diagrams referenced.

Commit

sdk/arch(agent-server): fix Mermaid syntax for Mintlify (escape wildcards, avoid /* and braces in labels)
Co-authored-by: openhands openhands@all-hands.dev

Next steps

These diagrams should now render cleanly in Mintlify. If there are any other diagrams containing “/*” or “{…}” in labels, we should normalize them similarly.

_{View full conversation}

docs.json

…ver group\n\n- Remove sdk/arch/agent-server from SDK Components\n- Add sdk/arch/agent-server under Guides > Remote Agent Server (after overview)\n\nCo-authored-by: openhands <openhands@all-hands.dev>

xingyaoww

The more i read into this doc, the more i feel it probably make sense to combine this docs with agent-server overview page we currently have, and have this doc link to specific docs of Docker/APIWorkspace when discussing about *Workspace that spawns agent server, wdyt?

enyst · 2025-12-23T17:48:03Z

The more i read into this doc, the more i feel it probably make sense to combine this docs with agent-server overview page we currently have, and have this doc link to specific docs of Docker/APIWorkspace when discussing about *Workspace that spawns agent server, wdyt?

Yes I feel maybe there’s some duplication. @OpenHands review the pages under agent-server and use your taste to combine meaningfully; link to workspaces.

openhands-ai · 2025-12-23T17:48:12Z

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

- Refactored sdk/arch/agent-server.mdx to focus on technical architecture: - Removed duplicate content and client SDK examples - Added clear API endpoints table - Added authentication table - Added links to workspace implementations (Docker, API, Cloud) - Added See Also section linking to guides - Refactored sdk/guides/agent-server/overview.mdx to focus on practical usage: - Renamed title to 'Remote Agent Server' for clarity - Removed duplicate architecture diagrams - Added workspace types comparison table - Added OpenHands Cloud workspace example - Simplified 'How It Works' section - Added links to architecture page for technical details - Updated Next Steps sections in all agent-server guide pages for consistency Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2025-12-23T17:55:00Z

Summary of Changes

I've consolidated the agent-server documentation pages to reduce duplication and improve clarity, as requested. The changes have been pushed to the docs-weekly-arch-refresh branch.

What was done:

1. Refactored sdk/arch/agent-server.mdx (Architecture Page)

Focused on technical architecture details: API endpoints, authentication, component design
Removed duplicate client SDK examples (REST/WebSocket code snippets)
Added clear tables for API endpoints and authentication methods
Added links to workspace implementations (DockerWorkspace, APIRemoteWorkspace, OpenHandsCloudWorkspace)
Added "See Also" section linking to practical guides

2. Refactored sdk/guides/agent-server/overview.mdx (Guides Overview)

Renamed title from "Overview" to "Remote Agent Server" for clarity
Removed duplicate architecture diagrams
Added workspace types comparison table
Added OpenHands Cloud workspace example alongside Docker and API examples
Simplified "How It Works" section
Added note linking to architecture page for technical details

3. Updated cross-links in all agent-server guide pages

api-sandbox.mdx, docker-sandbox.mdx, local-server.mdx, cloud-workspace.mdx
Consistent "Next Steps" sections with proper descriptions

Result:

Architecture page → Technical reference (endpoints, auth, design)
Guides overview → Practical usage (workspace types, deployment options)
Both pages now link to each other and to specific workspace documentation
Net reduction of 79 lines while improving organization and clarity

The changes are already pushed to the PR branch.

_{View full conversation}

neubig · 2025-12-31T02:49:31Z

Just checking in @enyst are you still working on this? If so you could re-request review or make any changes.

enyst · 2025-12-31T05:43:18Z

docs.json

                "group": "Remote Agent Server",
                "pages": [
                  "sdk/guides/agent-server/overview",
+                      "sdk/arch/agent-server",


@OpenHands I think we already have in the overview page similar content with the agent-server page? Verify what I just said, and dedup: remove from agent-server page what we already basically cover in overview, and move from agent-server page to overview page the rest. Don't spend much explanations on workspaces, link to the respective workspace instead.

Do make sure to keep all contents about the seamless transition from local to remote, and of course the rest of the non-dupe content.

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

I've completed the deduplication of the overview and agent-server pages as requested. Here's a summary of the changes:

Changes Made

✅ Verified overlap and deduplicated content

Confirmed that sdk/arch/overview.mdx and sdk/arch/agent-server.mdx had significant overlap in describing the Agent Server Package

✅ Moved unique content from agent-server.mdx to overview.mdx

The following unique content was moved to the "Agent Server Package" section in overview.mdx:

Architecture diagram (FastAPI App, Routers, Services)

Key Components table with source links

API Endpoints tables (REST and WebSocket)

Authentication details (HTTP header and WebSocket query param)

✅ Removed agent-server.mdx

Deleted sdk/arch/agent-server.mdx since all its content is now consolidated in overview.mdx

✅ Updated navigation

Removed sdk/arch/agent-server from docs.json navigation

✅ Updated all references

Updated 8 files that referenced the deleted page to point to the new location (/sdk/arch/overview#agent-server-package-openhandsagent_server):

sdk/guides/agent-server/overview.mdx

sdk/guides/agent-server/api-sandbox.mdx

sdk/guides/agent-server/docker-sandbox.mdx

sdk/guides/agent-server/local-server.mdx

sdk/guides/agent-server/cloud-workspace.mdx

sdk/arch/sdk.mdx

sdk/arch/workspace.mdx

✅ Kept seamless transition content

The seamless local-to-remote transition content remains in sdk/guides/agent-server/overview.mdx (the practical guide)

✅ Linked to workspace docs instead of explaining

The overview now links to /sdk/arch/workspace for workspace implementation details rather than duplicating explanations

The changes have been pushed to the docs-weekly-arch-refresh branch on PR #169.

View full conversation

- Move unique content from sdk/arch/agent-server.mdx to sdk/arch/overview.mdx - Remove sdk/arch/agent-server.mdx (content now in overview) - Update all references to point to the new location - Update docs.json navigation to remove agent-server page Co-authored-by: openhands <openhands@all-hands.dev>

enyst requested a review from xingyaoww as a code owner December 9, 2025 07:07

mintlify bot deployed to staging December 9, 2025 07:08 View deployment

docs: add inline GitHub source links per guidelines (agent-server.mdx…

3cc7816

…)\n\nCo-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging December 9, 2025 07:12 View deployment

docs: move Last updated footer to end of file (security.mdx)\n\nCo-au…

89ebfa0

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

mintlify bot deployed to staging December 9, 2025 07:18 View deployment

xingyaoww reviewed Dec 9, 2025

View reviewed changes

docs(agent-server): add Client SDK section with REST + WebSocket exam…

334d2bf

…ples, inline source links\n\nCo-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging December 11, 2025 17:51 View deployment

docs(agent-server): add bash-events WebSocket streaming example with …

26d1402

…inline source links\n\nCo-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging December 11, 2025 17:52 View deployment

docs(nav): add SDK architecture link for agent-server to left nav

f0328fa

Place agent-server at the end of the SDK Components section for consistent ordering. Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging December 11, 2025 17:54 View deployment

enyst force-pushed the docs-weekly-arch-refresh branch from 67909cf to f0328fa Compare December 11, 2025 17:55

mintlify bot deployed to staging December 11, 2025 17:55 View deployment

docs(agent-server): resolve conflicts, fix Mermaid blocks, rename to …

4c8fa8b

…'Agent Server', and simplify selected endpoints Also keeps concise Client SDK REST + WebSocket examples with inline GitHub source links. Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging December 11, 2025 23:12 View deployment

Merge branch 'main' into docs-weekly-arch-refresh

c115861

mintlify bot deployed to staging December 22, 2025 09:36 View deployment

sdk/arch(agent-server): fix Mermaid syntax for Mintlify (escape wildc…

abf463f

…ards, avoid /* and braces in labels) - Replace '/api/*' and '/sockets/*' with safe labels in diagrams - Replace '{id}' with '<id>' in node label Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging December 22, 2025 11:54 View deployment

xingyaoww reviewed Dec 22, 2025

View reviewed changes

docs.json Outdated Show resolved Hide resolved

docs(nav): move Agent Server architecture page under Remote Agent Ser…

4cf89e8

…ver group\n\n- Remove sdk/arch/agent-server from SDK Components\n- Add sdk/arch/agent-server under Guides > Remote Agent Server (after overview)\n\nCo-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging December 22, 2025 16:46 View deployment

Merge branch 'main' into docs-weekly-arch-refresh

9310f8f

mintlify bot deployed to staging December 22, 2025 18:30 View deployment

xingyaoww reviewed Dec 22, 2025

View reviewed changes

mintlify bot deployed to staging December 23, 2025 17:54 View deployment

Merge branch 'main' into docs-weekly-arch-refresh

e729c79

mintlify bot deployed to staging December 31, 2025 05:38 View deployment

enyst commented Dec 31, 2025

View reviewed changes

mintlify bot deployed to staging December 31, 2025 05:47 View deployment

neubig marked this pull request as draft January 8, 2026 13:44

docs: weekly architecture docs refresh #169

Are you sure you want to change the base?

docs: weekly architecture docs refresh #169

Uh oh!

Conversation

enyst commented Dec 9, 2025

Uh oh!

xingyaoww left a comment

Choose a reason for hiding this comment

Uh oh!

enyst commented Dec 22, 2025

Uh oh!

enyst commented Dec 22, 2025

Uh oh!

openhands-ai bot commented Dec 22, 2025

Uh oh!

openhands-ai bot commented Dec 22, 2025

Uh oh!

Uh oh!

xingyaoww left a comment

Choose a reason for hiding this comment

Uh oh!

enyst commented Dec 23, 2025

Uh oh!

openhands-ai bot commented Dec 23, 2025

Uh oh!

openhands-ai bot commented Dec 23, 2025

Summary of Changes

What was done:

Result:

Uh oh!

neubig commented Dec 31, 2025

Uh oh!

enyst Dec 31, 2025

Choose a reason for hiding this comment

Uh oh!

openhands-ai bot Dec 31, 2025

Choose a reason for hiding this comment

Uh oh!

openhands-ai bot Dec 31, 2025

Choose a reason for hiding this comment

Changes Made

✅ Verified overlap and deduplicated content

✅ Moved unique content from agent-server.mdx to overview.mdx

✅ Removed agent-server.mdx

✅ Updated navigation

✅ Updated all references

✅ Kept seamless transition content

✅ Linked to workspace docs instead of explaining

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants