From dd10f37f66651f28de99dd6dbf3fb9789b4d3329 Mon Sep 17 00:00:00 2001 From: Xingyao Wang Date: Fri, 3 Jan 2025 11:02:48 -0500 Subject: [PATCH 1/6] chore: remove extra debugging print (#6005) --- openhands/controller/agent_controller.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/openhands/controller/agent_controller.py b/openhands/controller/agent_controller.py index 2b6c116fef7c..238f9e8ac106 100644 --- a/openhands/controller/agent_controller.py +++ b/openhands/controller/agent_controller.py @@ -537,9 +537,7 @@ async def _step(self) -> None: self.update_state_before_step() action: Action = NullAction() try: - print('STEP AGENT') action = self.agent.step(self.state) - print('GOT ACTION', action) if action is None: raise LLMNoActionError('No action was returned') except ( From fa44bdb390bd8546412e1a6dc8d2c7b77d4ed706 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 3 Jan 2025 17:12:08 +0100 Subject: [PATCH 2/6] chore(deps-dev): bump chromadb from 0.6.0 to 0.6.1 in the chromadb group (#6004) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- poetry.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/poetry.lock b/poetry.lock index 6afb8ff5dfb3..b1263ea1f9ca 100644 --- a/poetry.lock +++ b/poetry.lock @@ -941,13 +941,13 @@ numpy = "*" [[package]] name = "chromadb" -version = "0.6.0" +version = "0.6.1" description = "Chroma." optional = false python-versions = ">=3.9" files = [ - {file = "chromadb-0.6.0-py3-none-any.whl", hash = "sha256:02e2c07acfc22dd5fe33cc48b89e37fbf407892f0658d534a8f94187083d7457"}, - {file = "chromadb-0.6.0.tar.gz", hash = "sha256:8f72dc9bf0ed2c6358e46a80f31c39199cdcea39b0714e67b91f13acb64251ce"}, + {file = "chromadb-0.6.1-py3-none-any.whl", hash = "sha256:3483ea9e1271b647f3696e1f39ee9e464bb23a6a9913f42c57a84657c34467bb"}, + {file = "chromadb-0.6.1.tar.gz", hash = "sha256:af55d143fd887f344ff05cd40560566dda1dd13e90ec5a13fb0f5278eb8cde75"}, ] [package.dependencies] From 4c59cff2a300a469309c032df7992ca4f8c756a7 Mon Sep 17 00:00:00 2001 From: "sp.wack" <83104063+amanape@users.noreply.github.com> Date: Fri, 3 Jan 2025 20:12:28 +0400 Subject: [PATCH 3/6] fix(frontend): Memoize messages (#6006) --- frontend/.eslintrc | 1 + .../src/components/features/chat/messages.tsx | 53 ++++++++++--------- 2 files changed, 30 insertions(+), 24 deletions(-) diff --git a/frontend/.eslintrc b/frontend/.eslintrc index 29896d083c35..03d7498d3a44 100644 --- a/frontend/.eslintrc +++ b/frontend/.eslintrc @@ -73,6 +73,7 @@ } } ], + "react/prop-types": "off", "react/no-array-index-key": "off", "react-hooks/exhaustive-deps": "off", "import/no-extraneous-dependencies": "off", diff --git a/frontend/src/components/features/chat/messages.tsx b/frontend/src/components/features/chat/messages.tsx index e1bd34637472..74439e17a604 100644 --- a/frontend/src/components/features/chat/messages.tsx +++ b/frontend/src/components/features/chat/messages.tsx @@ -1,3 +1,4 @@ +import React from "react"; import { ChatMessage } from "#/components/features/chat/chat-message"; import { ConfirmationButtons } from "#/components/shared/buttons/confirmation-buttons"; import { ImageCarousel } from "../images/image-carousel"; @@ -8,32 +9,36 @@ interface MessagesProps { isAwaitingUserConfirmation: boolean; } -export function Messages({ - messages, - isAwaitingUserConfirmation, -}: MessagesProps) { - return messages.map((message, index) => { - if (message.type === "error" || message.type === "action") { +export const Messages: React.FC = React.memo( + ({ messages, isAwaitingUserConfirmation }) => + messages.map((message, index) => { + if (message.type === "error" || message.type === "action") { + return ( + + ); + } + return ( - + > + {message.imageUrls && message.imageUrls.length > 0 && ( + + )} + {messages.length - 1 === index && + message.sender === "assistant" && + isAwaitingUserConfirmation && } + ); - } + }), +); - return ( - - {message.imageUrls && message.imageUrls.length > 0 && ( - - )} - {messages.length - 1 === index && - message.sender === "assistant" && - isAwaitingUserConfirmation && } - - ); - }); -} +Messages.displayName = "Messages"; From ff466d0f17cdf9ab8c4470c98f32110c2f0d9480 Mon Sep 17 00:00:00 2001 From: "sp.wack" <83104063+amanape@users.noreply.github.com> Date: Fri, 3 Jan 2025 20:34:06 +0400 Subject: [PATCH 4/6] fix(frontend): Prevent rendering loading spinner in chat interface too frequently (#6009) --- frontend/src/context/ws-client-provider.tsx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/frontend/src/context/ws-client-provider.tsx b/frontend/src/context/ws-client-provider.tsx index 4a55f661cd2d..ac59dec7ee5f 100644 --- a/frontend/src/context/ws-client-provider.tsx +++ b/frontend/src/context/ws-client-provider.tsx @@ -5,6 +5,7 @@ import EventLogger from "#/utils/event-logger"; import { handleAssistantMessage } from "#/services/actions"; import { useRate } from "#/hooks/use-rate"; import { OpenHandsParsedEvent } from "#/types/core"; +import { AgentStateChangeObservation } from "#/types/core/observations"; const isOpenHandsMessage = (event: unknown): event is OpenHandsParsedEvent => typeof event === "object" && @@ -14,6 +15,11 @@ const isOpenHandsMessage = (event: unknown): event is OpenHandsParsedEvent => "message" in event && "timestamp" in event; +const isAgentStateChangeObservation = ( + event: OpenHandsParsedEvent, +): event is AgentStateChangeObservation => + "observation" in event && event.observation === "agent_state_changed"; + export enum WsClientProviderStatus { CONNECTED, DISCONNECTED, @@ -68,7 +74,7 @@ export function WsClientProvider({ } function handleMessage(event: Record) { - if (isOpenHandsMessage(event)) { + if (isOpenHandsMessage(event) && !isAgentStateChangeObservation(event)) { messageRateHandler.record(new Date().getTime()); } setEvents((prevEvents) => [...prevEvents, event]); From 9fef6f909a8a7902c593a736b89685316505948a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 3 Jan 2025 16:54:48 +0000 Subject: [PATCH 5/6] chore(deps): bump the version-all group across 1 directory with 5 updates (#6008) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: amanape <83104063+amanape@users.noreply.github.com> --- frontend/package-lock.json | 48 +++++++++++++++++--------------------- frontend/package.json | 8 +++---- 2 files changed, 26 insertions(+), 30 deletions(-) diff --git a/frontend/package-lock.json b/frontend/package-lock.json index e6fdb410a8b7..70ab8e4e684d 100644 --- a/frontend/package-lock.json +++ b/frontend/package-lock.json @@ -14,7 +14,7 @@ "@react-router/serve": "^7.1.1", "@react-types/shared": "^3.25.0", "@reduxjs/toolkit": "^2.5.0", - "@tanstack/react-query": "^5.62.11", + "@tanstack/react-query": "^5.62.12", "@vitejs/plugin-react": "^4.3.2", "@xterm/addon-fit": "^0.10.0", "@xterm/xterm": "^5.4.0", @@ -27,11 +27,11 @@ "isbot": "^5.1.19", "jose": "^5.9.4", "monaco-editor": "^0.52.2", - "posthog-js": "^1.203.2", + "posthog-js": "^1.203.3", "react": "^19.0.0", "react-dom": "^19.0.0", "react-highlight": "^0.15.0", - "react-hot-toast": "^2.4.1", + "react-hot-toast": "^2.5.1", "react-i18next": "^15.4.0", "react-icons": "^5.4.0", "react-markdown": "^9.0.1", @@ -56,7 +56,7 @@ "@testing-library/jest-dom": "^6.6.1", "@testing-library/react": "^16.1.0", "@testing-library/user-event": "^14.5.2", - "@types/node": "^22.10.2", + "@types/node": "^22.10.5", "@types/react": "^19.0.2", "@types/react-dom": "^19.0.2", "@types/react-highlight": "^0.12.8", @@ -5361,22 +5361,20 @@ } }, "node_modules/@tanstack/query-core": { - "version": "5.62.9", - "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.62.9.tgz", - "integrity": "sha512-lwePd8hNYhyQ4nM/iRQ+Wz2cDtspGeZZHFZmCzHJ7mfKXt+9S301fULiY2IR2byJYY6Z03T427E5PoVfMexHjw==", - "license": "MIT", + "version": "5.62.12", + "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.62.12.tgz", + "integrity": "sha512-6igFeBgymHkCxVgaEk+yiLwkMf9haui/EQLmI3o9CatOyDThEoFKe8toLWvWliZC/Jf+h7NwHi/zjfyLArr1ow==", "funding": { "type": "github", "url": "https://github.com/sponsors/tannerlinsley" } }, "node_modules/@tanstack/react-query": { - "version": "5.62.11", - "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.62.11.tgz", - "integrity": "sha512-Xb1nw0cYMdtFmwkvH9+y5yYFhXvLRCnXoqlzSw7UkqtCVFq3cG8q+rHZ2Yz1XrC+/ysUaTqbLKJqk95mCgC1oQ==", - "license": "MIT", + "version": "5.62.12", + "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.62.12.tgz", + "integrity": "sha512-yt8p7l5MlHA3QCt6xF1Cu9dw1Anf93yTK+DMDJQ64h/mshAymVAtcwj8TpsyyBrZNWAAZvza/m76bnTSR79ZtQ==", "dependencies": { - "@tanstack/query-core": "5.62.9" + "@tanstack/query-core": "5.62.12" }, "funding": { "type": "github", @@ -5627,11 +5625,10 @@ "license": "MIT" }, "node_modules/@types/node": { - "version": "22.10.2", - "resolved": "https://registry.npmjs.org/@types/node/-/node-22.10.2.tgz", - "integrity": "sha512-Xxr6BBRCAOQixvonOye19wnzyDiUtTeqldOOmj3CkeblonbccA12PFwlufvRdrpjXxqnmUaeiU5EOA+7s5diUQ==", + "version": "22.10.5", + "resolved": "https://registry.npmjs.org/@types/node/-/node-22.10.5.tgz", + "integrity": "sha512-F8Q+SeGimwOo86fiovQh8qiXfFEh2/ocYv7tU5pJ3EXMSSxk1Joj5wefpFK2fHTf/N6HKGSxIDBT9f3gCxXPkQ==", "devOptional": true, - "license": "MIT", "dependencies": { "undici-types": "~6.20.0" } @@ -13810,10 +13807,9 @@ "license": "MIT" }, "node_modules/posthog-js": { - "version": "1.203.2", - "resolved": "https://registry.npmjs.org/posthog-js/-/posthog-js-1.203.2.tgz", - "integrity": "sha512-3aLpEhM4i9sQQtobRmDttJ3rTW1+gwQ9HL7QiOeDueE2T7CguYibYS7weY1UhXMerx5lh1A7+szlOJTTibifLQ==", - "license": "MIT", + "version": "1.203.3", + "resolved": "https://registry.npmjs.org/posthog-js/-/posthog-js-1.203.3.tgz", + "integrity": "sha512-DTK6LfL87xC7PPleKDParEIfkXl7hXtuDeSOPfhcyCXLuVspq0z7YyRB5dQE9Pbalf3yoGqUKvomYFp/BGVfQg==", "dependencies": { "core-js": "^3.38.1", "fflate": "^0.4.8", @@ -14144,12 +14140,12 @@ } }, "node_modules/react-hot-toast": { - "version": "2.4.1", - "resolved": "https://registry.npmjs.org/react-hot-toast/-/react-hot-toast-2.4.1.tgz", - "integrity": "sha512-j8z+cQbWIM5LY37pR6uZR6D4LfseplqnuAO4co4u8917hBUvXlEqyP1ZzqVLcqoyUesZZv/ImreoCeHVDpE5pQ==", - "license": "MIT", + "version": "2.5.1", + "resolved": "https://registry.npmjs.org/react-hot-toast/-/react-hot-toast-2.5.1.tgz", + "integrity": "sha512-54Gq1ZD1JbmAb4psp9bvFHjS7lje+8ubboUmvKZkCsQBLH6AOpZ9JemfRvIdHcfb9AZXRaFLrb3qUobGYDJhFQ==", "dependencies": { - "goober": "^2.1.10" + "csstype": "^3.1.3", + "goober": "^2.1.16" }, "engines": { "node": ">=10" diff --git a/frontend/package.json b/frontend/package.json index b3a40a98a514..1e3e4a04f587 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -13,7 +13,7 @@ "@react-router/serve": "^7.1.1", "@react-types/shared": "^3.25.0", "@reduxjs/toolkit": "^2.5.0", - "@tanstack/react-query": "^5.62.11", + "@tanstack/react-query": "^5.62.12", "@vitejs/plugin-react": "^4.3.2", "@xterm/addon-fit": "^0.10.0", "@xterm/xterm": "^5.4.0", @@ -26,11 +26,11 @@ "isbot": "^5.1.19", "jose": "^5.9.4", "monaco-editor": "^0.52.2", - "posthog-js": "^1.203.2", + "posthog-js": "^1.203.3", "react": "^19.0.0", "react-dom": "^19.0.0", "react-highlight": "^0.15.0", - "react-hot-toast": "^2.4.1", + "react-hot-toast": "^2.5.1", "react-i18next": "^15.4.0", "react-icons": "^5.4.0", "react-markdown": "^9.0.1", @@ -83,7 +83,7 @@ "@testing-library/jest-dom": "^6.6.1", "@testing-library/react": "^16.1.0", "@testing-library/user-event": "^14.5.2", - "@types/node": "^22.10.2", + "@types/node": "^22.10.5", "@types/react": "^19.0.2", "@types/react-dom": "^19.0.2", "@types/react-highlight": "^0.12.8", From 4de6c782cc2f3d315e8577ea5eb85cd88195c242 Mon Sep 17 00:00:00 2001 From: mamoodi Date: Fri, 3 Jan 2025 12:14:14 -0500 Subject: [PATCH 6/6] Add doc style guide and make docs adhere to it (#5983) Co-authored-by: Engel Nyst --- docs/DOC_STYLE_GUIDE.md | 48 +++++++++++ docs/modules/usage/about.md | 14 ++-- docs/modules/usage/configuration-options.md | 10 +-- docs/modules/usage/feedback.md | 25 ++++-- docs/modules/usage/getting-started.mdx | 28 +++---- docs/modules/usage/how-to/cli-mode.md | 6 +- .../usage/how-to/custom-sandbox-guide.md | 8 +- docs/modules/usage/how-to/github-action.md | 8 +- docs/modules/usage/how-to/gui-mode.md | 83 ++++++++++--------- docs/modules/usage/how-to/headless-mode.md | 8 +- .../usage/how-to/persist-session-data.md | 2 +- docs/modules/usage/installation.mdx | 8 +- docs/modules/usage/llms/azure-llms.md | 11 +-- docs/modules/usage/llms/google-llms.md | 10 +-- docs/modules/usage/llms/groq.md | 17 ++-- docs/modules/usage/llms/llms.md | 10 ++- docs/modules/usage/llms/openai-llms.md | 11 +-- docs/modules/usage/prompting/customization.md | 30 +++---- docs/modules/usage/prompting/microagents.md | 77 ++++++++--------- .../prompting/prompting-best-practices.md | 32 ++++--- docs/modules/usage/runtimes.md | 49 ++++++----- 21 files changed, 277 insertions(+), 218 deletions(-) create mode 100644 docs/DOC_STYLE_GUIDE.md diff --git a/docs/DOC_STYLE_GUIDE.md b/docs/DOC_STYLE_GUIDE.md new file mode 100644 index 000000000000..a55af799b112 --- /dev/null +++ b/docs/DOC_STYLE_GUIDE.md @@ -0,0 +1,48 @@ +# Documentation Style Guide + +## General Writing Principles + +- **Clarity & Conciseness**: Always prioritize clarity and brevity. Avoid unnecessary jargon or overly complex explanations. +Keep sentences short and to the point. +- **Gradual Complexity**: Start with the simplest, most basic setup, and then gradually introduce more advanced +concepts and configurations. + +## Formatting Guidelines + +### Headers + +Use **Title Case** for the first and second level headers. + +Example: + - **Basic Usage** + - **Advanced Configuration Options** + +### Lists + +When listing items or options, use bullet points to enhance readability. + +Example: + - Option A + - Option B + - Option C + +### Procedures + +For instructions or processes that need to be followed in a specific order, use numbered steps. + +Example: + 1. Step one: Do this. + 2. Step two: Complete this action. + 3. Step three: Verify the result. + +### Code Blocks + +* Use code blocks for multi-line inputs, outputs, commands and code samples. + +Example: +```bash +docker run -it \ + -e THIS=this \ + -e THAT=that + ... +``` diff --git a/docs/modules/usage/about.md b/docs/modules/usage/about.md index 2732fbeb31b4..fea58bc747a3 100644 --- a/docs/modules/usage/about.md +++ b/docs/modules/usage/about.md @@ -4,10 +4,9 @@ Achieving full replication of production-grade applications with LLMs is a complex endeavor. Our strategy involves: -1. **Core Technical Research:** Focusing on foundational research to understand and improve the technical aspects of code generation and handling -2. **Specialist Abilities:** Enhancing the effectiveness of core components through data curation, training methods, and more -3. **Task Planning:** Developing capabilities for bug detection, codebase management, and optimization -4. **Evaluation:** Establishing comprehensive evaluation metrics to better understand and improve our models +- **Core Technical Research:** Focusing on foundational research to understand and improve the technical aspects of code generation and handling. +- **Task Planning:** Developing capabilities for bug detection, codebase management, and optimization. +- **Evaluation:** Establishing comprehensive evaluation metrics to better understand and improve our agents. ## Default Agent @@ -15,11 +14,14 @@ Our default Agent is currently the [CodeActAgent](agents), which is capable of g ## Built With -OpenHands is built using a combination of powerful frameworks and libraries, providing a robust foundation for its development. Here are the key technologies used in the project: +OpenHands is built using a combination of powerful frameworks and libraries, providing a robust foundation for its +development. Here are the key technologies used in the project: ![FastAPI](https://img.shields.io/badge/FastAPI-black?style=for-the-badge) ![uvicorn](https://img.shields.io/badge/uvicorn-black?style=for-the-badge) ![LiteLLM](https://img.shields.io/badge/LiteLLM-black?style=for-the-badge) ![Docker](https://img.shields.io/badge/Docker-black?style=for-the-badge) ![Ruff](https://img.shields.io/badge/Ruff-black?style=for-the-badge) ![MyPy](https://img.shields.io/badge/MyPy-black?style=for-the-badge) ![LlamaIndex](https://img.shields.io/badge/LlamaIndex-black?style=for-the-badge) ![React](https://img.shields.io/badge/React-black?style=for-the-badge) -Please note that the selection of these technologies is in progress, and additional technologies may be added or existing ones may be removed as the project evolves. We strive to adopt the most suitable and efficient tools to enhance the capabilities of OpenHands. +Please note that the selection of these technologies is in progress, and additional technologies may be added or +existing ones may be removed as the project evolves. We strive to adopt the most suitable and efficient tools to +enhance the capabilities of OpenHands. ## License diff --git a/docs/modules/usage/configuration-options.md b/docs/modules/usage/configuration-options.md index 7a2718d7d786..29c9b6759507 100644 --- a/docs/modules/usage/configuration-options.md +++ b/docs/modules/usage/configuration-options.md @@ -11,7 +11,7 @@ take precedence. # Table of Contents -1. [Core Configuration](#core-configuration) +- [Core Configuration](#core-configuration) - [API Keys](#api-keys) - [Workspace](#workspace) - [Debugging and Logging](#debugging-and-logging) @@ -21,7 +21,7 @@ take precedence. - [Task Management](#task-management) - [Sandbox Configuration](#sandbox-configuration) - [Miscellaneous](#miscellaneous) -2. [LLM Configuration](#llm-configuration) +- [LLM Configuration](#llm-configuration) - [AWS Credentials](#aws-credentials) - [API Configuration](#api-configuration) - [Custom LLM Provider](#custom-llm-provider) @@ -30,20 +30,20 @@ take precedence. - [Model Selection](#model-selection) - [Retrying](#retrying) - [Advanced Options](#advanced-options) -3. [Agent Configuration](#agent-configuration) +- [Agent Configuration](#agent-configuration) - [Microagent Configuration](#microagent-configuration) - [Memory Configuration](#memory-configuration) - [LLM Configuration](#llm-configuration-2) - [ActionSpace Configuration](#actionspace-configuration) - [Microagent Usage](#microagent-usage) -4. [Sandbox Configuration](#sandbox-configuration-2) +- [Sandbox Configuration](#sandbox-configuration) - [Execution](#execution) - [Container Image](#container-image) - [Networking](#networking) - [Linting and Plugins](#linting-and-plugins) - [Dependencies and Environment](#dependencies-and-environment) - [Evaluation](#evaluation) -5. [Security Configuration](#security-configuration) +- [Security Configuration](#security-configuration) - [Confirmation Mode](#confirmation-mode) - [Security Analyzer](#security-analyzer) diff --git a/docs/modules/usage/feedback.md b/docs/modules/usage/feedback.md index af26c1d1e676..4a6d3a78fda8 100644 --- a/docs/modules/usage/feedback.md +++ b/docs/modules/usage/feedback.md @@ -1,10 +1,14 @@ # ✅ Providing Feedback -When using OpenHands, you will encounter cases where things work well, and others where they don't. We encourage you to provide feedback when you use OpenHands to help give feedback to the development team, and perhaps more importantly, create an open corpus of coding agent training examples -- Share-OpenHands! +When using OpenHands, you will encounter cases where things work well, and others where they don't. We encourage you to +provide feedback when you use OpenHands to help give feedback to the development team, and perhaps more importantly, +create an open corpus of coding agent training examples -- Share-OpenHands! ## 📝 How to Provide Feedback -Providing feedback is easy! When you are using OpenHands, you can press the thumbs-up or thumbs-down button at any point during your interaction. You will be prompted to provide your email address (e.g. so we can contact you if we want to ask any follow-up questions), and you can choose whether you want to provide feedback publicly or privately. +Providing feedback is easy! When you are using OpenHands, you can press the thumbs-up or thumbs-down button at any point +during your interaction. You will be prompted to provide your email address +(e.g. so we can contact you if we want to ask any follow-up questions), and you can choose whether you want to provide feedback publicly or privately. @@ -14,8 +18,11 @@ Providing feedback is easy! When you are using OpenHands, you can press the thum When you submit data, you can submit it either publicly or privately. -* **Public** data will be distributed under the MIT License, like OpenHands itself, and can be used by the community to train and test models. Obviously, feedback that you can make public will be more valuable for the community as a whole, so when you are not dealing with sensitive information, we would encourage you to choose this option! -* **Private** data will only be shared with the OpenHands team for the purpose of improving OpenHands. +- **Public** data will be distributed under the MIT License, like OpenHands itself, and can be used by the community to +train and test models. Obviously, feedback that you can make public will be more valuable for the community as a whole, +so when you are not dealing with sensitive information, we would encourage you to choose this option! +- **Private** data will be made available to the OpenHands team for the purpose of improving OpenHands. +However, a link with a unique ID will still be created that you can share publicly with others. ### Who collects and stores the data? @@ -27,13 +34,17 @@ The public data will be released when we hit fixed milestones, such as 1,000 pub At this time, we will follow the following release process: 1. All people who contributed public feedback will receive an email describing the data release and being given an opportunity to opt out. -2. The person or people in charge of the data release will perform quality control of the data, removing low-quality feedback, removing email submitter email addresses, and attempting to remove any sensitive information. +2. The person or people in charge of the data release will perform quality control of the data, removing low-quality feedback, +removing email submitter email addresses, and attempting to remove any sensitive information. 3. The data will be released publicly under the MIT license through commonly used sites such as github or Hugging Face. ### What if I want my data deleted? For data on the All Hands AI servers, we are happy to delete it at request: -**One Piece of Data:** If you want one piece of data deleted, we will shortly be adding a mechanism to delete pieces of data using the link and password that is displayed on the interface when you submit data. +**One Piece of Data:** If you want one piece of data deleted, we will shortly be adding a mechanism to delete pieces of +data using the link and password that is displayed on the interface when you submit data. -**All Data:** If you would like all pieces of your data deleted, or you do not have the ID and password that you received when submitting the data, please contact `contact@all-hands.dev` from the email address that you registered when you originally submitted the data. +**All Data:** If you would like all pieces of your data deleted, or you do not have the ID and password that you +received when submitting the data, please contact `contact@all-hands.dev` from the email address that you registered +when you originally submitted the data. diff --git a/docs/modules/usage/getting-started.mdx b/docs/modules/usage/getting-started.mdx index 934d1bdfd77d..0a7140b91dd6 100644 --- a/docs/modules/usage/getting-started.mdx +++ b/docs/modules/usage/getting-started.mdx @@ -44,7 +44,7 @@ For example, we might build a TODO app: We can keep iterating on the app once the skeleton is there: -> Please allow adding an optional due date to every task +> Please allow adding an optional due date to every task. Just like with normal development, it's good to commit and push your code frequently. This way you can always revert back to an old state if the agent goes off track. @@ -59,15 +59,15 @@ OpenHands can also do a great job adding new code to an existing code base. For example, you can ask OpenHands to add a new GitHub action to your project which lints your code. OpenHands may take a peek at your codebase to see what language -it should use, but then it can just drop a new file into `./github/workflows/lint.yml` +it should use and then drop a new file into `./github/workflows/lint.yml`. -> Please add a GitHub action that lints the code in this repository +> Please add a GitHub action that lints the code in this repository. Some tasks might require a bit more context. While OpenHands can use `ls` and `grep` to search through your codebase, providing context up front allows it to move faster, and more accurately. And it'll cost you fewer tokens! -> Please modify ./backend/api/routes.js to add a new route that returns a list of all tasks +> Please modify ./backend/api/routes.js to add a new route that returns a list of all tasks. > Please add a new React component that displays a list of Widgets to the ./frontend/components > directory. It should use the existing Widget component. @@ -78,15 +78,15 @@ OpenHands does great at refactoring existing code, especially in small chunks. You probably don't want to try rearchitecting your whole codebase, but breaking up long files and functions, renaming variables, etc. tend to work very well. -> Please rename all the single-letter variables in ./app.go +> Please rename all the single-letter variables in ./app.go. -> Please break the function `build_and_deploy_widgets` into two functions, `build_widgets` and `deploy_widgets` in widget.php +> Please break the function `build_and_deploy_widgets` into two functions, `build_widgets` and `deploy_widgets` in widget.php. -> Please break ./api/routes.js into separate files for each route +> Please break ./api/routes.js into separate files for each route. ## Bug Fixes -OpenHands can also help you track down and fix bugs in your code. But, as any +OpenHands can also help you track down and fix bugs in your code. But as any developer knows, bug fixing can be extremely tricky, and often OpenHands will need more context. It helps if you've diagnosed the bug, but want OpenHands to figure out the logic. @@ -94,18 +94,18 @@ It helps if you've diagnosed the bug, but want OpenHands to figure out the logic > The `search_widgets` function in ./app.py is doing a case-sensitive search. Please make it case-insensitive. -It often helps to do test-driven development when bugfixing with an agent. +It often helps to do test-driven development when bug fixing with an agent. You can ask the agent to write a new test, and then iterate until it fixes the bug: > The `hello` function crashes on the empty string. Please write a test that reproduces this bug, then fix the code so it passes. ## More -OpenHands is capable of helping out on just about any coding task. But it takes some practice +OpenHands is capable of helping out on just about any coding task but it takes some practice to get the most out of it. Remember to: -* Keep your tasks small -* Be as specific as possible -* Provide as much context as possible -* Commit and push frequently +* Keep your tasks small. +* Be as specific as possible. +* Provide as much context as possible. +* Commit and push frequently. See [Prompting Best Practices](./prompting/prompting-best-practices) for more tips on how to get the most out of OpenHands. diff --git a/docs/modules/usage/how-to/cli-mode.md b/docs/modules/usage/how-to/cli-mode.md index fb256dfb420e..7f4b89a4bc16 100644 --- a/docs/modules/usage/how-to/cli-mode.md +++ b/docs/modules/usage/how-to/cli-mode.md @@ -26,9 +26,9 @@ To run OpenHands in CLI mode with Docker: 1. Set the following environmental variables in your terminal: -* `WORKSPACE_BASE` to the directory you want OpenHands to edit (Ex: `export WORKSPACE_BASE=$(pwd)/workspace`). -* `LLM_MODEL` to the model to use (Ex: `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`). -* `LLM_API_KEY` to the API key (Ex: `export LLM_API_KEY="sk_test_12345"`). +- `WORKSPACE_BASE` to the directory you want OpenHands to edit (Ex: `export WORKSPACE_BASE=$(pwd)/workspace`). +- `LLM_MODEL` to the model to use (Ex: `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`). +- `LLM_API_KEY` to the API key (Ex: `export LLM_API_KEY="sk_test_12345"`). 2. Run the following Docker command: diff --git a/docs/modules/usage/how-to/custom-sandbox-guide.md b/docs/modules/usage/how-to/custom-sandbox-guide.md index 3708584a6a1a..154e1117ae66 100644 --- a/docs/modules/usage/how-to/custom-sandbox-guide.md +++ b/docs/modules/usage/how-to/custom-sandbox-guide.md @@ -9,8 +9,8 @@ as python and Node.js but may need other software installed by default. You have two options for customization: -1. Use an existing image with the required software. -2. Create your own custom Docker image. +- Use an existing image with the required software. +- Create your own custom Docker image. If you choose the first option, you can skip the `Create Your Docker Image` section. @@ -58,7 +58,3 @@ sandbox_base_container_image="custom-image" ### Run Run OpenHands by running ```make run``` in the top level directory. - -## Technical Explanation - -Please refer to [custom docker image section of the runtime documentation](https://docs.all-hands.dev/modules/usage/architecture/runtime#advanced-how-openhands-builds-and-maintains-od-runtime-images) for more details. diff --git a/docs/modules/usage/how-to/github-action.md b/docs/modules/usage/how-to/github-action.md index 31b82a1e5c4c..3ba0227ddaaf 100644 --- a/docs/modules/usage/how-to/github-action.md +++ b/docs/modules/usage/how-to/github-action.md @@ -21,10 +21,10 @@ the [README for the OpenHands Resolver](https://github.com/All-Hands-AI/OpenHand ### Iterative resolution 1. Create an issue in the repository. -2. Add the `fix-me` label to the issue, or leave a comment starting with `@openhands-agent` -3. Review the attempt to resolve the issue by checking the pull request -4. Follow up with feedback through general comments, review comments, or inline thread comments -5. Add the `fix-me` label to the pull request, or address a specific comment by starting with `@openhands-agent` +2. Add the `fix-me` label to the issue, or leave a comment starting with `@openhands-agent`. +3. Review the attempt to resolve the issue by checking the pull request. +4. Follow up with feedback through general comments, review comments, or inline thread comments. +5. Add the `fix-me` label to the pull request, or address a specific comment by starting with `@openhands-agent`. ### Label versus Macro diff --git a/docs/modules/usage/how-to/gui-mode.md b/docs/modules/usage/how-to/gui-mode.md index 027364ea28ed..11feafb7609d 100644 --- a/docs/modules/usage/how-to/gui-mode.md +++ b/docs/modules/usage/how-to/gui-mode.md @@ -2,12 +2,12 @@ ## Introduction -OpenHands provides a user-friendly Graphical User Interface (GUI) mode for interacting with the AI assistant. This mode offers an intuitive way to set up the environment, manage settings, and communicate with the AI. +OpenHands provides a user-friendly Graphical User Interface (GUI) mode for interacting with the AI assistant. +This mode offers an intuitive way to set up the environment, manage settings, and communicate with the AI. ## Installation and Setup 1. Follow the instructions in the [Installation](../installation) guide to install OpenHands. - 2. After running the command, access OpenHands at [http://localhost:3000](http://localhost:3000). ## Interacting with the GUI @@ -23,39 +23,39 @@ OpenHands provides a user-friendly Graphical User Interface (GUI) mode for inter OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if it is available. This can happen in two ways: -1. **Locally (OSS)**: The user directly inputs their GitHub token -2. **Online (SaaS)**: The token is obtained through GitHub OAuth authentication +- **Locally (OSS)**: The user directly inputs their GitHub token. +- **Online (SaaS)**: The token is obtained through GitHub OAuth authentication. #### Setting Up a Local GitHub Token 1. **Generate a Personal Access Token (PAT)**: - - Go to GitHub Settings > Developer Settings > Personal Access Tokens > Tokens (classic) - - Click "Generate new token (classic)" + - Go to GitHub Settings > Developer Settings > Personal Access Tokens > Tokens (classic). + - Click "Generate new token (classic)". - Required scopes: - `repo` (Full control of private repositories) - `workflow` (Update GitHub Action workflows) - `read:org` (Read organization data) 2. **Enter Token in OpenHands**: - - Click the Settings button (gear icon) in the top right - - Navigate to the "GitHub" section - - Paste your token in the "GitHub Token" field - - Click "Save" to apply the changes + - Click the Settings button (gear icon) in the top right. + - Navigate to the "GitHub" section. + - Paste your token in the "GitHub Token" field. + - Click "Save" to apply the changes. #### Organizational Token Policies If you're working with organizational repositories, additional setup may be required: 1. **Check Organization Requirements**: - - Organization admins may enforce specific token policies - - Some organizations require tokens to be created with SSO enabled - - Review your organization's [token policy settings](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) + - Organization admins may enforce specific token policies. + - Some organizations require tokens to be created with SSO enabled. + - Review your organization's [token policy settings](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization). 2. **Verify Organization Access**: - - Go to your token settings on GitHub - - Look for the organization under "Organization access" - - If required, click "Enable SSO" next to your organization - - Complete the SSO authorization process + - Go to your token settings on GitHub. + - Look for the organization under "Organization access". + - If required, click "Enable SSO" next to your organization. + - Complete the SSO authorization process. #### OAuth Authentication (Online Mode) @@ -67,31 +67,31 @@ When using OpenHands in online mode, the GitHub OAuth flow: - Organization read access 2. Authentication steps: - - Click "Sign in with GitHub" when prompted - - Review the requested permissions - - Authorize OpenHands to access your GitHub account - - If using an organization, authorize organization access if prompted + - Click "Sign in with GitHub" when prompted. + - Review the requested permissions. + - Authorize OpenHands to access your GitHub account. + - If using an organization, authorize organization access if prompted. #### Troubleshooting Common issues and solutions: 1. **Token Not Recognized**: - - Ensure the token is properly saved in settings - - Check that the token hasn't expired - - Verify the token has the required scopes - - Try regenerating the token + - Ensure the token is properly saved in settings. + - Check that the token hasn't expired. + - Verify the token has the required scopes. + - Try regenerating the token. 2. **Organization Access Denied**: - - Check if SSO is required but not enabled - - Verify organization membership - - Contact organization admin if token policies are blocking access + - Check if SSO is required but not enabled. + - Verify organization membership. + - Contact organization admin if token policies are blocking access. 3. **Verifying Token Works**: - - The app will show a green checkmark if the token is valid - - Try accessing a repository to confirm permissions - - Check the browser console for any error messages - - Use the "Test Connection" button in settings if available + - The app will show a green checkmark if the token is valid. + - Try accessing a repository to confirm permissions. + - Check the browser console for any error messages. + - Use the "Test Connection" button in settings if available. ### Advanced Settings @@ -103,11 +103,11 @@ Common issues and solutions: The main interface consists of several key components: -1. **Chat Window**: The central area where you can view the conversation history with the AI assistant. -2. **Input Box**: Located at the bottom of the screen, use this to type your messages or commands to the AI. -3. **Send Button**: Click this to send your message to the AI. -4. **Settings Button**: A gear icon that opens the settings modal, allowing you to adjust your configuration at any time. -5. **Workspace Panel**: Displays the files and folders in your workspace, allowing you to navigate and view files, or the agent's past commands or web browsing history. +- **Chat Window**: The central area where you can view the conversation history with the AI assistant. +- **Input Box**: Located at the bottom of the screen, use this to type your messages or commands to the AI. +- **Send Button**: Click this to send your message to the AI. +- **Settings Button**: A gear icon that opens the settings modal, allowing you to adjust your configuration at any time. +- **Workspace Panel**: Displays the files and folders in your workspace, allowing you to navigate and view files, or the agent's past commands or web browsing history. ### Interacting with the AI @@ -118,8 +118,9 @@ The main interface consists of several key components: ## Tips for Effective Use -1. Be specific in your requests to get the most accurate and helpful responses, as described in the [prompting best practices](../prompting/prompting-best-practices). -2. Use the workspace panel to explore your project structure. -3. Use one of the recommended models, as described in the [LLMs section](usage/llms/llms.md). +- Be specific in your requests to get the most accurate and helpful responses, as described in the [prompting best practices](../prompting/prompting-best-practices). +- Use the workspace panel to explore your project structure. +- Use one of the recommended models, as described in the [LLMs section](usage/llms/llms.md). -Remember, the GUI mode of OpenHands is designed to make your interaction with the AI assistant as smooth and intuitive as possible. Don't hesitate to explore its features to maximize your productivity. +Remember, the GUI mode of OpenHands is designed to make your interaction with the AI assistant as smooth and intuitive +as possible. Don't hesitate to explore its features to maximize your productivity. diff --git a/docs/modules/usage/how-to/headless-mode.md b/docs/modules/usage/how-to/headless-mode.md index 1efc994b3913..133ba1fd4ba6 100644 --- a/docs/modules/usage/how-to/headless-mode.md +++ b/docs/modules/usage/how-to/headless-mode.md @@ -23,9 +23,9 @@ To run OpenHands in Headless mode with Docker: 1. Set the following environmental variables in your terminal: -* `WORKSPACE_BASE` to the directory you want OpenHands to edit (Ex: `export WORKSPACE_BASE=$(pwd)/workspace`). -* `LLM_MODEL` to the model to use (Ex: `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`). -* `LLM_API_KEY` to the API key (Ex: `export LLM_API_KEY="sk_test_12345"`). +- `WORKSPACE_BASE` to the directory you want OpenHands to edit (Ex: `export WORKSPACE_BASE=$(pwd)/workspace`). +- `LLM_MODEL` to the model to use (Ex: `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`). +- `LLM_API_KEY` to the API key (Ex: `export LLM_API_KEY="sk_test_12345"`). 2. Run the following Docker command: @@ -53,4 +53,4 @@ To view all available configuration options for headless mode, run the Python co ### Additional Logs -For the headless mode to log all the agent actions, in your terminal run: `export LOG_ALL_EVENTS=true` +For the headless mode to log all the agent actions, in the terminal run: `export LOG_ALL_EVENTS=true` diff --git a/docs/modules/usage/how-to/persist-session-data.md b/docs/modules/usage/how-to/persist-session-data.md index f079531498fe..fcdfab504c27 100644 --- a/docs/modules/usage/how-to/persist-session-data.md +++ b/docs/modules/usage/how-to/persist-session-data.md @@ -1,6 +1,6 @@ # Persisting Session Data -Using the standard installation, the session data is stored in memory. Currently, if OpenHands' service is restarted, +Using the standard Development Workflow, the session data is stored in memory. Currently, if OpenHands' service is restarted, previous sessions become invalid (a new secret is generated) and thus not recoverable. ## How to Persist Session Data diff --git a/docs/modules/usage/installation.mdx b/docs/modules/usage/installation.mdx index 9dd2790d9b4b..7b59b2baa121 100644 --- a/docs/modules/usage/installation.mdx +++ b/docs/modules/usage/installation.mdx @@ -2,9 +2,9 @@ ## System Requirements -* Docker version 26.0.0+ or Docker Desktop 4.31.0+. -* You must be using Linux or Mac OS. - * If you are on Windows, you must use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). +- Docker version 26.0.0+ or Docker Desktop 4.31.0+. +- You must be using Linux or Mac OS. + - If you are on Windows, you must use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). ## Start the app @@ -33,8 +33,6 @@ or run it on tagged issues with [a github action](https://docs.all-hands.dev/mod ## Setup -After running the command above, you'll find OpenHands running at [http://localhost:3000](http://localhost:3000). - Upon launching OpenHands, you'll see a settings modal. You **must** select an `LLM Provider` and `LLM Model` and enter a corresponding `API Key`. These can be changed at any time by selecting the `Settings` button (gear icon) in the UI. diff --git a/docs/modules/usage/llms/azure-llms.md b/docs/modules/usage/llms/azure-llms.md index 11653fd42c38..7046fe7bf536 100644 --- a/docs/modules/usage/llms/azure-llms.md +++ b/docs/modules/usage/llms/azure-llms.md @@ -18,17 +18,18 @@ docker run -it --pull=always \ ... ``` -Then set the following in the OpenHands UI through the Settings: +Then in the OpenHands UI Settings: :::note You will need your ChatGPT deployment name which can be found on the deployments page in Azure. This is referenced as <deployment-name> below. ::: -* Enable `Advanced Options` -* `Custom Model` to azure/<deployment-name> -* `Base URL` to your Azure API Base URL (e.g. `https://example-endpoint.openai.azure.com`) -* `API Key` to your Azure API key +1. Enable `Advanced Options` +2. Set the following: + - `Custom Model` to azure/<deployment-name> + - `Base URL` to your Azure API Base URL (e.g. `https://example-endpoint.openai.azure.com`) + - `API Key` to your Azure API key ## Embeddings diff --git a/docs/modules/usage/llms/google-llms.md b/docs/modules/usage/llms/google-llms.md index 701208b75976..d89ba389f057 100644 --- a/docs/modules/usage/llms/google-llms.md +++ b/docs/modules/usage/llms/google-llms.md @@ -8,10 +8,10 @@ OpenHands uses LiteLLM to make calls to Google's chat models. You can find their ## Gemini - Google AI Studio Configs When running OpenHands, you'll need to set the following in the OpenHands UI through the Settings: -* `LLM Provider` to `Gemini` -* `LLM Model` to the model you will be using. +- `LLM Provider` to `Gemini` +- `LLM Model` to the model you will be using. If the model is not in the list, toggle `Advanced Options`, and enter it in `Custom Model` (e.g. gemini/<model-name> like `gemini/gemini-1.5-pro`). -* `API Key` to your Gemini API key +- `API Key` to your Gemini API key ## VertexAI - Google Cloud Platform Configs @@ -25,6 +25,6 @@ VERTEXAI_LOCATION="" ``` Then set the following in the OpenHands UI through the Settings: -* `LLM Provider` to `VertexAI` -* `LLM Model` to the model you will be using. +- `LLM Provider` to `VertexAI` +- `LLM Model` to the model you will be using. If the model is not in the list, toggle `Advanced Options`, and enter it in `Custom Model` (e.g. vertex_ai/<model-name>). diff --git a/docs/modules/usage/llms/groq.md b/docs/modules/usage/llms/groq.md index 2ebd8758d696..d484d5e3a4e1 100644 --- a/docs/modules/usage/llms/groq.md +++ b/docs/modules/usage/llms/groq.md @@ -5,19 +5,20 @@ OpenHands uses LiteLLM to make calls to chat models on Groq. You can find their ## Configuration When running OpenHands, you'll need to set the following in the OpenHands UI through the Settings: -* `LLM Provider` to `Groq` -* `LLM Model` to the model you will be using. [Visit here to see the list of +- `LLM Provider` to `Groq` +- `LLM Model` to the model you will be using. [Visit here to see the list of models that Groq hosts](https://console.groq.com/docs/models). If the model is not in the list, toggle `Advanced Options`, and enter it in `Custom Model` (e.g. groq/<model-name> like `groq/llama3-70b-8192`). -* `API key` to your Groq API key. To find or create your Groq API Key, [see here](https://console.groq.com/keys). +- `API key` to your Groq API key. To find or create your Groq API Key, [see here](https://console.groq.com/keys). ## Using Groq as an OpenAI-Compatible Endpoint The Groq endpoint for chat completion is [mostly OpenAI-compatible](https://console.groq.com/docs/openai). Therefore, you can access Groq models as you -would access any OpenAI-compatible endpoint. You can set the following in the OpenHands UI through the Settings: -* Enable `Advanced Options` -* `Custom Model` to the prefix `openai/` + the model you will be using (e.g. `openai/llama3-70b-8192`) -* `Base URL` to `https://api.groq.com/openai/v1` -* `API Key` to your Groq API key +would access any OpenAI-compatible endpoint. In the OpenHands UI through the Settings: +1. Enable `Advanced Options` +2. Set the following: + - `Custom Model` to the prefix `openai/` + the model you will be using (e.g. `openai/llama3-70b-8192`) + - `Base URL` to `https://api.groq.com/openai/v1` + - `API Key` to your Groq API key diff --git a/docs/modules/usage/llms/llms.md b/docs/modules/usage/llms/llms.md index d9254b2070a4..709e86c3cf9a 100644 --- a/docs/modules/usage/llms/llms.md +++ b/docs/modules/usage/llms/llms.md @@ -4,7 +4,9 @@ OpenHands can connect to any LLM supported by LiteLLM. However, it requires a po ## Model Recommendations -Based on our evaluations of language models for coding tasks (using the SWE-bench dataset), we can provide some recommendations for model selection. Some analyses can be found in [this blog article comparing LLMs](https://www.all-hands.dev/blog/evaluation-of-llms-as-coding-agents-on-swe-bench-at-30x-speed) and [this blog article with some more recent results](https://www.all-hands.dev/blog/openhands-codeact-21-an-open-state-of-the-art-software-development-agent). +Based on our evaluations of language models for coding tasks (using the SWE-bench dataset), we can provide some +recommendations for model selection. Some analyses can be found in [this blog article comparing LLMs](https://www.all-hands.dev/blog/evaluation-of-llms-as-coding-agents-on-swe-bench-at-30x-speed) and +[this blog article with some more recent results](https://www.all-hands.dev/blog/openhands-codeact-21-an-open-state-of-the-art-software-development-agent). When choosing a model, consider both the quality of outputs and the associated costs. Here's a summary of the findings: @@ -69,9 +71,11 @@ We have a few guides for running OpenHands with specific model providers: ### API retries and rate limits -LLM providers typically have rate limits, sometimes very low, and may require retries. OpenHands will automatically retry requests if it receives a Rate Limit Error (429 error code), API connection error, or other transient errors. +LLM providers typically have rate limits, sometimes very low, and may require retries. OpenHands will automatically +retry requests if it receives a Rate Limit Error (429 error code), API connection error, or other transient errors. -You can customize these options as you need for the provider you're using. Check their documentation, and set the following environment variables to control the number of retries and the time between retries: +You can customize these options as you need for the provider you're using. Check their documentation, and set the +following environment variables to control the number of retries and the time between retries: - `LLM_NUM_RETRIES` (Default of 8) - `LLM_RETRY_MIN_WAIT` (Default of 15 seconds) diff --git a/docs/modules/usage/llms/openai-llms.md b/docs/modules/usage/llms/openai-llms.md index 6b6c34c40477..9157c7cac8bb 100644 --- a/docs/modules/usage/llms/openai-llms.md +++ b/docs/modules/usage/llms/openai-llms.md @@ -17,8 +17,9 @@ Just as for OpenAI Chat completions, we use LiteLLM for OpenAI-compatible endpoi ## Using an OpenAI Proxy -If you're using an OpenAI proxy, you'll need to set the following in the OpenHands UI through the Settings: -* Enable `Advanced Options` -* `Custom Model` to openai/<model-name> (e.g. `openai/gpt-4o` or openai/<proxy-prefix>/<model-name>) -* `Base URL` to the URL of your OpenAI proxy -* `API Key` to your OpenAI API key +If you're using an OpenAI proxy, in the OpenHands UI through the Settings: +1. Enable `Advanced Options` +2. Set the following: + - `Custom Model` to openai/<model-name> (e.g. `openai/gpt-4o` or openai/<proxy-prefix>/<model-name>) + - `Base URL` to the URL of your OpenAI proxy + - `API Key` to your OpenAI API key diff --git a/docs/modules/usage/prompting/customization.md b/docs/modules/usage/prompting/customization.md index 78eadf0f91eb..362368d9ed39 100644 --- a/docs/modules/usage/prompting/customization.md +++ b/docs/modules/usage/prompting/customization.md @@ -9,11 +9,11 @@ You can customize OpenHands' behavior for your repository by creating a `.openha be given to the agent every time it works with this repository. We suggest including the following information: -1. **Repository Overview**: A brief description of your project's purpose and architecture -2. **Directory Structure**: Key directories and their purposes -3. **Development Guidelines**: Project-specific coding standards and practices -4. **Testing Requirements**: How to run tests and what types of tests are required -5. **Setup Instructions**: Steps needed to build and run the project +- **Repository Overview**: A brief description of your project's purpose and architecture. +- **Directory Structure**: Key directories and their purposes. +- **Development Guidelines**: Project-specific coding standards and practices. +- **Testing Requirements**: How to run tests and what types of tests are required. +- **Setup Instructions**: Steps needed to build and run the project. ### Example Repository Configuration Example `.openhands/microagents/repo.md` file: @@ -39,11 +39,11 @@ Guidelines: ### Customizing Prompts -When working with a customized repository: +When working with a repository: -1. **Reference Project Standards**: Mention specific coding standards or patterns used in your project -2. **Include Context**: Reference relevant documentation or existing implementations -3. **Specify Testing Requirements**: Include project-specific testing requirements in your prompts +- **Reference Project Standards**: Mention specific coding standards or patterns used in your project. +- **Include Context**: Reference relevant documentation or existing implementations. +- **Specify Testing Requirements**: Include project-specific testing requirements in your prompts. Example customized prompt: ``` @@ -54,14 +54,14 @@ The component should use our shared styling from src/styles/components. ### Best Practices for Repository Customization -1. **Keep Instructions Updated**: Regularly update your `.openhands` directory as your project evolves -2. **Be Specific**: Include specific paths, patterns, and requirements unique to your project -3. **Document Dependencies**: List all tools and dependencies required for development -4. **Include Examples**: Provide examples of good code patterns from your project -5. **Specify Conventions**: Document naming conventions, file organization, and code style preferences +- **Keep Instructions Updated**: Regularly update your `.openhands` directory as your project evolves. +- **Be Specific**: Include specific paths, patterns, and requirements unique to your project. +- **Document Dependencies**: List all tools and dependencies required for development. +- **Include Examples**: Provide examples of good code patterns from your project. +- **Specify Conventions**: Document naming conventions, file organization, and code style preferences. By customizing OpenHands for your repository, you'll get more accurate and consistent results that align with your project's standards and requirements. ## Other Microagents You can create other instructions in the `.openhands/microagents/` directory -that will be sent to the agent if a particular keyword is found, like `test`, `frontend`, or `migration`. See [Microagents](microagents.md) for more information. +that will be sent to the agent if a particular keyword is found, like `test`, `frontend`, or `migration`. See [Micro-Agents](microagents.md) for more information. diff --git a/docs/modules/usage/prompting/microagents.md b/docs/modules/usage/prompting/microagents.md index 69bff7fed8d0..51f9f91b491c 100644 --- a/docs/modules/usage/prompting/microagents.md +++ b/docs/modules/usage/prompting/microagents.md @@ -6,10 +6,10 @@ OpenHands uses specialized micro-agents to handle specific tasks and contexts ef Micro-agents are defined in markdown files under the `openhands/agenthub/codeact_agent/micro/` directory. Each micro-agent is configured with: -- A unique name -- The agent type (typically CodeActAgent) -- Trigger keywords that activate the agent -- Specific instructions and capabilities +- A unique name. +- The agent type (typically CodeActAgent). +- Trigger keywords that activate the agent. +- Specific instructions and capabilities. ## Available Micro-Agents @@ -18,10 +18,10 @@ Micro-agents are defined in markdown files under the `openhands/agenthub/codeact **Triggers**: `github`, `git` The GitHub agent specializes in GitHub API interactions and repository management. It: -- Has access to a `GITHUB_TOKEN` for API authentication -- Follows strict guidelines for repository interactions -- Handles branch management and pull requests -- Uses the GitHub API instead of web browser interactions +- Has access to a `GITHUB_TOKEN` for API authentication. +- Follows strict guidelines for repository interactions. +- Handles branch management and pull requests. +- Uses the GitHub API instead of web browser interactions. Key features: - Branch protection (prevents direct pushes to main/master) @@ -34,13 +34,14 @@ Key features: **Triggers**: `npm` Specializes in handling npm package management with specific focus on: -- Non-interactive shell operations -- Automated confirmation handling using Unix 'yes' command -- Package installation automation +- Non-interactive shell operations. +- Automated confirmation handling using Unix 'yes' command. +- Package installation automation. ### Custom Micro-Agents -You can create your own micro-agents by adding new markdown files to the micro-agents directory. Each file should follow this structure: +You can create your own micro-agents by adding new markdown files to the micro-agents directory. +Each file should follow this structure: ```markdown --- @@ -57,19 +58,18 @@ Instructions and capabilities for the micro-agent... ## Best Practices When working with micro-agents: - -1. **Use Appropriate Triggers**: Ensure your commands include the relevant trigger words to activate the correct micro-agent -2. **Follow Agent Guidelines**: Each agent has specific instructions and limitations - respect these for optimal results -3. **API-First Approach**: When available, use API endpoints rather than web interfaces -4. **Automation Friendly**: Design commands that work well in non-interactive environments +- **Use Appropriate Triggers**: Ensure your commands include the relevant trigger words to activate the correct micro-agent. +- **Follow Agent Guidelines**: Each agent has specific instructions and limitations. Respect these for optimal results. +- **API-First Approach**: When available, use API endpoints rather than web interfaces. +- **Automation Friendly**: Design commands that work well in non-interactive environments. ## Integration Micro-agents are automatically integrated into OpenHands' workflow. They: -- Monitor incoming commands for their trigger words -- Activate when relevant triggers are detected -- Apply their specialized knowledge and capabilities -- Follow their specific guidelines and restrictions +- Monitor incoming commands for their trigger words. +- Activate when relevant triggers are detected. +- Apply their specialized knowledge and capabilities. +- Follow their specific guidelines and restrictions. ## Example Usage @@ -105,7 +105,7 @@ Create a new markdown file in `openhands/agenthub/codeact_agent/micro/` with a d Your micro-agent file must include: -1. **Front Matter**: YAML metadata at the start of the file: +- **Front Matter**: YAML metadata at the start of the file: ```markdown --- name: your_agent_name @@ -116,7 +116,7 @@ triggers: --- ``` -2. **Instructions**: Clear, specific guidelines for the agent's behavior: +- **Instructions**: Clear, specific guidelines for the agent's behavior: ```markdown You are responsible for [specific task/domain]. @@ -135,19 +135,19 @@ Examples of usage: ### 4. Best Practices for Micro-Agent Development -1. **Clear Scope**: Keep the agent focused on a specific domain or task -2. **Explicit Instructions**: Provide clear, unambiguous guidelines -3. **Useful Examples**: Include practical examples of common use cases -4. **Safety First**: Include necessary warnings and constraints -5. **Integration Awareness**: Consider how the agent interacts with other components +- **Clear Scope**: Keep the agent focused on a specific domain or task. +- **Explicit Instructions**: Provide clear, unambiguous guidelines. +- **Useful Examples**: Include practical examples of common use cases. +- **Safety First**: Include necessary warnings and constraints. +- **Integration Awareness**: Consider how the agent interacts with other components. ### 5. Testing Your Micro-Agent Before submitting: -1. Test the agent with various prompts -2. Verify trigger words activate the agent correctly -3. Ensure instructions are clear and comprehensive -4. Check for potential conflicts with existing agents +- Test the agent with various prompts. +- Verify trigger words activate the agent correctly. +- Ensure instructions are clear and comprehensive. +- Check for potential conflicts with existing agents. ### 6. Example Implementation @@ -199,11 +199,12 @@ Remember to: ### 7. Submission Process -1. Create your micro-agent file in the correct directory -2. Test thoroughly +1. Create your micro-agent file in the correct directory. +2. Test thoroughly. 3. Submit a pull request with: - - The new micro-agent file - - Updated documentation if needed - - Description of the agent's purpose and capabilities + - The new micro-agent file. + - Updated documentation if needed. + - Description of the agent's purpose and capabilities. -Remember that micro-agents are a powerful way to extend OpenHands' capabilities in specific domains. Well-designed agents can significantly improve the system's ability to handle specialized tasks. +Remember that micro-agents are a powerful way to extend OpenHands' capabilities in specific domains. Well-designed +agents can significantly improve the system's ability to handle specialized tasks. diff --git a/docs/modules/usage/prompting/prompting-best-practices.md b/docs/modules/usage/prompting/prompting-best-practices.md index 90bae497113c..35740ea0c6b2 100644 --- a/docs/modules/usage/prompting/prompting-best-practices.md +++ b/docs/modules/usage/prompting/prompting-best-practices.md @@ -6,35 +6,31 @@ When working with OpenHands AI software developer, it's crucial to provide clear Good prompts are: -1. **Concrete**: They explain exactly what functionality should be added or what error needs to be fixed. -2. **Location-specific**: If known, they explain the locations in the code base that should be modified. -3. **Appropriately scoped**: They should be the size of a single feature, typically not exceeding 100 lines of code. +- **Concrete**: They explain exactly what functionality should be added or what error needs to be fixed. +- **Location-specific**: If known, they explain the locations in the code base that should be modified. +- **Appropriately scoped**: They should be the size of a single feature, typically not exceeding 100 lines of code. ## Examples ### Good Prompt Examples -1. "Add a function `calculate_average` in `utils/math_operations.py` that takes a list of numbers as input and returns their average." - -2. "Fix the TypeError in `frontend/src/components/UserProfile.tsx` occurring on line 42. The error suggests we're trying to access a property of undefined." - -3. "Implement input validation for the email field in the registration form. Update `frontend/src/components/RegistrationForm.tsx` to check if the email is in a valid format before submission." +- "Add a function `calculate_average` in `utils/math_operations.py` that takes a list of numbers as input and returns their average." +- "Fix the TypeError in `frontend/src/components/UserProfile.tsx` occurring on line 42. The error suggests we're trying to access a property of undefined." +- "Implement input validation for the email field in the registration form. Update `frontend/src/components/RegistrationForm.tsx` to check if the email is in a valid format before submission." ### Bad Prompt Examples -1. "Make the code better." (Too vague, not concrete) - -2. "Rewrite the entire backend to use a different framework." (Not appropriately scoped) - -3. "There's a bug somewhere in the user authentication. Can you find and fix it?" (Lacks specificity and location information) +- "Make the code better." (Too vague, not concrete) +- "Rewrite the entire backend to use a different framework." (Not appropriately scoped) +- "There's a bug somewhere in the user authentication. Can you find and fix it?" (Lacks specificity and location information) ## Tips for Effective Prompting -1. Be as specific as possible about the desired outcome or the problem to be solved. -2. Provide context, including relevant file paths and line numbers if available. -3. Break down large tasks into smaller, manageable prompts. -4. Include any relevant error messages or logs. -5. Specify the programming language or framework if it's not obvious from the context. +- Be as specific as possible about the desired outcome or the problem to be solved. +- Provide context, including relevant file paths and line numbers if available. +- Break down large tasks into smaller, manageable prompts. +- Include any relevant error messages or logs. +- Specify the programming language or framework if it's not obvious from the context. Remember, the more precise and informative your prompt is, the better the AI can assist you in developing or modifying the OpenHands software. diff --git a/docs/modules/usage/runtimes.md b/docs/modules/usage/runtimes.md index 1aeb82aa00be..2b57855ea062 100644 --- a/docs/modules/usage/runtimes.md +++ b/docs/modules/usage/runtimes.md @@ -26,30 +26,29 @@ that contains our Runtime server, as well as some basic utilities for Python and You can also [build your own runtime image](how-to/custom-sandbox-guide). ### Connecting to Your filesystem -One useful feature here is the ability to connect to your local filesystem. - -To mount your filesystem into the runtime, first set WORKSPACE_BASE: -```bash -export WORKSPACE_BASE=/path/to/your/code - -# Linux and Mac Example -# export WORKSPACE_BASE=$HOME/OpenHands -# Will set $WORKSPACE_BASE to /home//OpenHands -# -# WSL on Windows Example -# export WORKSPACE_BASE=/mnt/c/dev/OpenHands -# Will set $WORKSPACE_BASE to C:\dev\OpenHands -``` - -then add the following options to the `docker run` command: - -```bash -docker run # ... - -e SANDBOX_USER_ID=$(id -u) \ - -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \ - -v $WORKSPACE_BASE:/opt/workspace_base \ - # ... -``` +One useful feature here is the ability to connect to your local filesystem. To mount your filesystem into the runtime: +1. Set `WORKSPACE_BASE`: + + ```bash + export WORKSPACE_BASE=/path/to/your/code + + # Linux and Mac Example + # export WORKSPACE_BASE=$HOME/OpenHands + # Will set $WORKSPACE_BASE to /home//OpenHands + # + # WSL on Windows Example + # export WORKSPACE_BASE=/mnt/c/dev/OpenHands + # Will set $WORKSPACE_BASE to C:\dev\OpenHands + ``` +2. Add the following options to the `docker run` command: + + ```bash + docker run # ... + -e SANDBOX_USER_ID=$(id -u) \ + -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \ + -v $WORKSPACE_BASE:/opt/workspace_base \ + # ... + ``` Be careful! There's nothing stopping the OpenHands agent from deleting or modifying any files that are mounted into its workspace. @@ -59,7 +58,7 @@ but seems to work well on most systems. ## All Hands Runtime The All Hands Runtime is currently in beta. You can request access by joining -the #remote-runtime-limited-beta channel on Slack ([see the README](https://github.com/All-Hands-AI/OpenHands?tab=readme-ov-file#-join-our-community) for an invite). +the #remote-runtime-limited-beta channel on Slack ([see the README](https://github.com/All-Hands-AI/OpenHands?tab=readme-ov-file#-how-to-join-the-community) for an invite). To use the All Hands Runtime, set the following environment variables when starting OpenHands: