docs: weekly architecture docs refresh

[enyst]

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

1. 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.

2. 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

[xingyaoww]

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

[enyst]

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]

@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]

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

[openhands-ai]

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 [email protected]

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}

[xingyaoww]

Shall we put it under the agent-server group and make this as a description for agent server?
https://docs.openhands.dev/sdk/guides/agent-server/overview

[enyst]

@OpenHands lets do this.

[openhands-ai]

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

[openhands-ai]

Summary of changes just made

What you asked

• “Put it under the agent-server group and make this as a description for agent server”

What I changed

• Moved the Agent Server architecture page into the Remote Agent Server group in the SDK Guides navigation:
  • Added: sdk/arch/agent-server under SDK > Guides > Remote Agent Server (immediately after overview)
  • Removed: sdk/arch/agent-server from SDK > Architecture > SDK Components

Validation

• Confirmed docs.json parses (jq OK)
• Git diff shows only the intended navigation edits (3 insertions, 2 deletions)

Commit

• Branch: docs-weekly-arch-refresh
• Commit: docs(nav): move Agent Server architecture page under Remote Agent Server group
• Co-authored-by: openhands [email protected]

Checklist

• Request fully addressed: Agent Server page is now nested under the agent-server group
• No extraneous changes
• Pushed updates to the existing PR branch

If you want it ordered differently within the group (e.g., after “local-server”), tell me and I’ll adjust.

_{View full conversation}

[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?