The OpenHands SDK is a composable Python library providing core functionality for building AI agents that work with code. It enables defining agents in code and running them locally or at scale in the cloud, serving as the engine behind OpenHands CLI and OpenHands Cloud. As of version 1.16.1, it focuses on modularity, extensibility, and production readiness, with frequent releases aimed at enhanced capabilities and improved user experience.
pip install openhands-sdkVerified import paths — ran on the pinned version, not inferred.
This quickstart initializes an LLM, an agent with basic tools (Terminal, FileEditor, TaskTracker), and runs a conversation to perform a file-writing task in the current working directory. Ensure `openhands-tools` is installed and `LLM_API_KEY` and `LLM_MODEL` environment variables are set.
Review the OpenHands V1 migration guide (if available) and adapt configurations, imports, and agent definitions to the new modular structure and API. Ensure `openhands-tools` is installed for common agent tools.
Install `openhands-tools` (`pip install openhands-tools`) and import tools from `from openhands.tools.*`.
Always use `os.environ.get()` to retrieve API keys and other sensitive configurations. Follow security best practices for credential management in your deployment environment (e.g., Kubernetes secrets, AWS Secrets Manager).
Migrate to the equivalent functionalities within the `openhands-sdk` and `openhands-tools` packages, referring to the latest documentation for correct usage.
Ensure that a security analyzer is configured for the agent, even if confirmation mode is disabled. This might involve adjusting the agent's setup to always include the security analyzer, or updating the LLM's system prompt to avoid returning 'security_risk' parameters when an analyzer isn't present. For CLI users, ensure your configuration does not inadvertently disable the security analyzer.
Verify that Docker Desktop (on Windows/macOS) or the Docker daemon (on Linux) is installed and actively running. You can check this by running `docker ps` in your terminal. For Docker Desktop, ensure 'Allow the default Docker socket to be used' is enabled in settings.
Change the ownership of the `~/.openhands` directory to your user account using `sudo chown <user>:<user> ~/.openhands` or update its permissions using `sudo chmod 777 ~/.openhands`. Alternatively, if no previous data is needed, you can delete the directory, and OpenHands will recreate it with the correct permissions.
Implement a 'condenser' in your agent's configuration. The condenser is designed to summarize older conversation history, allowing the conversation to continue without exceeding the LLM's context window. Example: `conversation = Conversation(agent=agent, condenser=my_condenser_instance)`.
This often points to an incompatibility or an unexpected response format from the LLM when integrated via `litellm`. Check the specific LLM model and `litellm` version being used. Ensure `litellm` is up to date, and if the issue persists, review the LLM's output for unexpected structures. It might require adjustments to the prompt or a specific `litellm` configuration to correctly parse the LLM's response.