docs: add FAQ section for common questions

[meichuanyi]

Changes

• Added FAQ section to README covering:
  • General: What is the SDK, license, documentation links
  • Installation & Setup: pip install, Python version, LLM API key requirements
  • Core Concepts: Agent, Conversation, Tool, Workspace, Agent Server components
  • Usage: Task types, container support, error handling
  • Troubleshooting: Import errors, agent timeouts, workspace permissions

Why this matters

The SDK README has a great quick start but new users may have common questions about setup, core concepts, and troubleshooting. This FAQ section provides immediate answers.

Checklist

• Content is accurate based on README and docs.openhands.dev/sdk
• FAQ is specific to the SDK's architecture and usage patterns
• No duplicate content with existing README sections

[VascoSch92]

Hey @meichuanyi

thank you for the PR.

However, you can already find all the info you added in the readme.md.

In fact,

General

• What is the SDK? → README intro paragraph (lines ~32–40, "set of Python and REST APIs for building agents that work with code…"). The FAQ answer is just a paraphrase of the same paragraph.
• What license? → MIT badge at the top of the README, plus LICENSE file.
• Where is the documentation? → "Documentation" badge at the top + dedicated Documentation section in the README (with the same docs.openhands.dev/sdk link).

Installation & Setup

• How do I install? → README already says "see the https://docs.openhands.dev/sdk/getting-started" and mentions make build. The docs page itself documents pip install openhands-sdk.
• Python version? → Not in README, but the FAQ answer is wrong. openhands-sdk/pyproject.toml declares requires-python = ">=3.12", not 3.10.
• LLM API key? → Quick Start in the README already shows api_key=os.getenv("LLM_API_KEY"). The Getting Started docs explicitly walk through key setup (Anthropic / OpenAI / OpenHands Cloud / ChatGPT).

Core Concepts

• Main components? → This is a near-copy of the docs page docs.openhands.dev/sdk/arch/overview (Agent, Conversation, LLM, Tool, Workspace, Agent Server). Already linked from the README's Documentation section.
• Tools included? → README Quick Start imports TerminalTool, FileEditorTool, TaskTrackerTool; examples/01_standalone_sdk/ and the docs cover the rest.
• Use my own LLM? → docs.openhands.dev/sdk overview states the SDK works with any LLM provider.

Usage

• What kinds of tasks? → Verbatim duplicate of the README intro bullets: "One-off tasks… Routine maintenance… Major tasks… engine behind OpenHands CLI and Cloud."
• Containers? → Verbatim duplicate of the README intro: "agents can either use the local machine as their workspace, or run inside ephemeral workspaces (e.g. in Docker or Kubernetes) using the Agent Server."
• Error handling? → The answer just says "check the documentation" — no real content added.

Troubleshooting / Community

• ImportError / hangs / workspace permissions → Generic Python/Docker advice, not SDK-specific. None of it is novel.
• How do I join the community? → Already in the README's Community section with the same Slack link.

[xingyaoww]

Hey! Thanks for your contribution, you can also consider adding these info to github.com/openhands/docs repo, where we have a dedicated faq.mdx file :)

[meichuanyi]

@maintainer 请问有空 review 吗？如有需要修改的地方请告诉我，谢谢！🙏

[meichuanyi]

@maintainer 请问有空 review 吗？这个 PR 提交 3 天了。感谢！

[meichuanyi]

@maintainer 请问有空 review 这个文档 PR 吗？谢谢！

[meichuanyi]

Hi maintainers, this PR has been open for 4 days. Could you please take a look when you have time? Thank you!

[meichuanyi]

Hi @maintainers, this PR has been open for 5 days. Could you please take a look when you have time? Thanks!

[meichuanyi]

Hi maintainers, just checking in on this PR. It's been 5 days since submission. Is there anything I can do to help move this forward? Thank you!

[meichuanyi]

Hi maintainers, this PR has been open for 7 days. Is there anything that needs to be adjusted? Happy to make changes if needed. Thanks for your time! 🙏

[meichuanyi]

Closing this PR due to lack of maintainer response after 8+ days. Thank you for the opportunity to contribute.