{"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":"en","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,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}