Skip to content

docs: weekly architecture docs refresh #169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
enyst wants to merge 7 commits into
base: main
Choose a base branch
from
Open

docs: weekly architecture docs refresh #169

enyst wants to merge 7 commits into from

Conversation

@enyst
Copy link
Collaborator

@enyst enyst commented Dec 9, 2025

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

@enyst @openhands-agent
docs: weekly architecture docs refresh
f077784 
- 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 <[email protected]>
@enyst enyst requested a review from xingyaoww as a code owner December 9, 2025 07:07
xingyaoww
xingyaoww reviewed Dec 9, 2025
View reviewed changes
Copy link
Contributor

@xingyaoww xingyaoww left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@enyst
docs(agent-server): add Client SDK section with REST + WebSocket exam…
334d2bf 
…ples, inline source links\n\nCo-authored-by: openhands <[email protected]>
@enyst @openhands-agent
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 <[email protected]>
@enyst enyst force-pushed the docs-weekly-arch-refresh branch from 67909cf to f0328fa Compare December 11, 2025 17:55
@enyst @openhands-agent
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 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@xingyaoww xingyaoww xingyaoww left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@enyst @xingyaoww