{"id":3720,"library":"openhands-sdk","title":"OpenHands SDK","description":"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.","status":"active","version":"1.16.1","language":"python","source_language":"en","source_url":"https://github.com/OpenHands/software-agent-sdk","tags":["ai-agents","sdk","llm","agentic-workflow","software-development","code-generation"],"install":[{"cmd":"pip install openhands-sdk","lang":"bash","label":"Install core SDK"}],"dependencies":[{"reason":"Provides essential pre-defined tools like `FileEditorTool` and `TerminalTool` for agents, separated from the core SDK since V1.","package":"openhands-tools","optional":true},{"reason":"Used by the SDK's `LLM` class for interacting with various language models.","package":"litellm","optional":false}],"imports":[{"symbol":"LLM","correct":"from openhands.sdk import LLM"},{"symbol":"Agent","correct":"from openhands.sdk import Agent"},{"symbol":"Conversation","correct":"from openhands.sdk import Conversation"},{"symbol":"Tool","correct":"from openhands.sdk import Tool"},{"note":"Tools are now in the separate `openhands-tools` package as of V1 for modularity.","wrong":"from openhands.sdk.tools.file_editor import FileEditorTool","symbol":"FileEditorTool","correct":"from openhands.tools.file_editor import FileEditorTool"},{"note":"Tools are now in the separate `openhands-tools` package as of V1 for modularity.","wrong":"from openhands.sdk.tools.terminal import TerminalTool","symbol":"TerminalTool","correct":"from openhands.tools.terminal import TerminalTool"}],"quickstart":{"code":"import os\nfrom openhands.sdk import LLM, Agent, Conversation, Tool\nfrom openhands.tools.file_editor import FileEditorTool\nfrom openhands.tools.task_tracker import TaskTrackerTool\nfrom openhands.tools.terminal import TerminalTool\n\n# Ensure LLM_API_KEY and LLM_MODEL are set in your environment\n# Example: export LLM_API_KEY='your_api_key' / export LLM_MODEL='anthropic/claude-sonnet-4-5-20250929'\nllm_api_key = os.environ.get('LLM_API_KEY', '')\nllm_model = os.environ.get('LLM_MODEL', 'anthropic/claude-sonnet-4-5-20250929') # Placeholder model\n\nllm = LLM(model=llm_model, api_key=llm_api_key)\n\nagent = Agent(\n    llm=llm,\n    tools=[\n        Tool(name=TerminalTool.name),\n        Tool(name=FileEditorTool.name),\n        Tool(name=TaskTrackerTool.name),\n    ],\n)\n\ncwd = os.getcwd()\nconversation = Conversation(agent=agent, workspace=cwd)\n\nprint(f\"Agent will operate in: {cwd}\")\nconversation.send_message(\"Write 3 facts about the current project into FACTS.txt.\")\nconversation.run()\nprint(\"All done!\")","lang":"python","description":"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."},"warnings":[{"fix":"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.","message":"OpenHands V1, which includes this SDK, represents a significant architectural redesign from V0. Older conversations, CLI, and web API configurations are not directly compatible, and changes were made to package management (from poetry to uv) and modularity. Users upgrading from pre-V1 versions should expect to adapt their code and configurations.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Install `openhands-tools` (`pip install openhands-tools`) and import tools from `from openhands.tools.*`.","message":"Common agent tools like `FileEditorTool`, `TerminalTool`, and `TaskTrackerTool` are now part of the separate `openhands-tools` package, not `openhands-sdk`. Attempting to import them directly from `openhands.sdk.tools` will result in an `ImportError`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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).","message":"The SDK relies on environment variables like `LLM_API_KEY` and `LLM_MODEL` for LLM configuration. Ensure these are securely managed and correctly set, especially when deploying agents to different environments. A security fix in v1.12.0 for the agent-server highlighted the importance of not inadvertently forwarding sensitive API keys.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate to the equivalent functionalities within the `openhands-sdk` and `openhands-tools` packages, referring to the latest documentation for correct usage.","message":"Older, monolithic components like the `openhands-aci` (Agent Computer Interface) repository have been deprecated, with their functionalities (e.g., file editor tools) migrated into the `openhands-sdk` or `openhands-tools` packages. Relying on deprecated external repositories may lead to outdated or unsupported features.","severity":"deprecated","affected_versions":"<1.0.0"}],"env_vars":null,"search_vec":"'1.16.1':51 'agent':17,25,73,77 'agentic-workflow':76 'ai':16,72 'ai-ag':71 'aim':63 'behind':42 'build':15 'capabl':66 'cli':44 'cloud':37,47 'code':21,27,83 'code-gener':82 'compos':8 'core':12 'defin':24 'develop':81 'enabl':23 'engin':41 'enhanc':65 'experi':70 'extens':56 'focus':53 'frequent':61 'function':13 'generat':84 'improv':68 'librari':10 'llm':75 'local':31 'modular':55 'openhand':1,4,43,46 'product':58 'provid':11 'python':9 'readi':59 'releas':62 'run':29 'scale':34 'sdk':2,5,74 'serv':38 'softwar':80 'software-develop':79 'user':69 'version':50 'work':19 'workflow':78","created_at":"2026-04-11T17:41:50.238906+00:00","updated_at":"2026-04-16T17:35:35.324437+00:00","problems":[{"fix":"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.","cause":"This error occurs when the LLM's response includes a 'security_risk' parameter, but the OpenHands SDK agent's conversation configuration does not have a security analyzer enabled to handle it. This often happens when confirmation mode is disabled, which can inadvertently remove the security analyzer.","error":"RuntimeError: LLM provided a security_risk but no security analyzer is configured - THIS SHOULD NOT HAPPEN!"},{"fix":"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.","cause":"OpenHands SDK agents typically run within a sandboxed Docker environment. This error indicates that the Docker daemon is either not running or not accessible to the OpenHands application, preventing the agent from launching its execution environment.","error":"Launch docker client failed. Please make sure you have installed docker and started docker desktop/daemon."},{"fix":"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.","cause":"This error occurs when OpenHands attempts to access or modify files within the `~/.openhands` directory, but the current user lacks the necessary read/write permissions. This can happen if the directory was created with root privileges or has incorrect ownership.","error":"PermissionError: [Errno 13] Permission denied: '~/.openhands'"},{"fix":"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)`.","cause":"This exception is raised when the conversation history exceeds the maximum context window of the configured Large Language Model (LLM), and a 'condenser' is not configured to summarize older history.","error":"LLMContextWindowExceedError"},{"fix":"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.","cause":"This `AttributeError` typically arises within the `litellm` library, which OpenHands SDK uses for LLM integration. It suggests that a list object was received where a Pydantic model (expected to have a `model_dump` method) was anticipated, likely due to an unexpected format in the LLM's response or a mismatch in how `litellm` processes the output for certain models (e.g., Gemini-2.5-Pro).","error":"AttributeError: 'list' object has no attribute 'model_dump'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.44.1","cli_name":"openhands","cli_version":"","type":"library","homepage":"https://www.openhands.dev","github":"https://github.com/OpenHands/software-agent-sdk","docs":"https://docs.openhands.dev/sdk","changelog":null,"pypi":"https://pypi.org/project/openhands-sdk/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["llm-agents","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}