mirror of
https://github.com/OpenHands/OpenHands.git
synced 2025-12-26 05:48:36 +08:00
Add Getting Started docs (#4224)
This commit is contained in:
Robert Brennan
GitHub
parent
e60eaf9a52
commit
42c118f4b4
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 8
|
||||
---
|
||||
|
||||
# 📚 Misc
|
||||
|
||||
## ⭐️ Research Strategy
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# 🧠 Main Agent and Capabilities
|
||||
|
||||
## CodeActAgent
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 7
|
||||
---
|
||||
|
||||
# 🏛️ System Architecture
|
||||
|
||||
<div style={{ textAlign: 'center' }}>
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# ✅ 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!
|
||||
|
||||
@ -1,67 +1,105 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
# Getting Started with OpenHands
|
||||
|
||||
# Getting Started
|
||||
So you've [installed OpenHands](./installation) and have
|
||||
[set up your LLM](./installation#setup). Now what?
|
||||
|
||||
## System Requirements
|
||||
OpenHands can help you tackle a wide variety of engineering tasks. But the technology
|
||||
is still new, and we're a long way off from having agents that can take on large, complicated
|
||||
engineering tasks without any guidance. So it's important to get a feel for what the agent
|
||||
does well, and where it might need some help.
|
||||
|
||||
* 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).
|
||||
## Hello World
|
||||
The first thing you might want to try is a simple "hello world" example.
|
||||
This can be more complicated than it sounds!
|
||||
|
||||
## Installation
|
||||
Try prompting the agent with:
|
||||
> Please write a bash script hello.sh that prints "hello world!"
|
||||
|
||||
The easiest way to run OpenHands is in Docker. You can change `WORKSPACE_BASE` below to point OpenHands to
|
||||
existing code that you'd like to modify.
|
||||
You should see that the agent not only writes the script--it sets the correct
|
||||
permissions and runs the script to check the output.
|
||||
|
||||
```bash
|
||||
export WORKSPACE_BASE=$(pwd)/workspace
|
||||
You can continue prompting the agent to refine your code. This is a great way to
|
||||
work with agents--start simple, and iterate.
|
||||
|
||||
docker pull ghcr.io/all-hands-ai/runtime:0.9-nikolaik
|
||||
> Please modify hello.sh so that it accepts a name as the first argument, but defaults to "world"
|
||||
|
||||
docker run -it --pull=always \
|
||||
-e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.9-nikolaik \
|
||||
-e SANDBOX_USER_ID=$(id -u) \
|
||||
-e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
|
||||
-v $WORKSPACE_BASE:/opt/workspace_base \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
-p 3000:3000 \
|
||||
--add-host host.docker.internal:host-gateway \
|
||||
--name openhands-app-$(date +%Y%m%d%H%M%S) \
|
||||
ghcr.io/all-hands-ai/openhands:0.9
|
||||
```
|
||||
You can also work in any language you need--though the agent might need to spend some
|
||||
time setting up its environment!
|
||||
|
||||
You can also run OpenHands in a scriptable [headless mode](https://docs.all-hands.dev/modules/usage/how-to/headless-mode), as an [interactive CLI](https://docs.all-hands.dev/modules/usage/how-to/cli-mode), or using the [OpenHands GitHub Action](https://docs.all-hands.dev/modules/usage/how-to/github-action).
|
||||
> Please convert hello.sh to a Ruby script, and run it
|
||||
|
||||
## Setup
|
||||
## Building from scratch
|
||||
Agents do exceptionally well at "greenfield" tasks--tasks where they don't need
|
||||
any context about an existing codebase, and they can just start from scratch.
|
||||
|
||||
After running the command above, you'll find OpenHands running at [http://localhost:3000](http://localhost:3000).
|
||||
It's best to start with a simple task, and then iterate on it. It's also best to be
|
||||
as specific as possible about what you want, what the tech stack should be, etc.
|
||||
|
||||
The agent will have access to the `./workspace` folder to do its work. You can copy existing code here, or change `WORKSPACE_BASE` in the
|
||||
command to point to an existing folder.
|
||||
For example, we might build a TODO app:
|
||||
|
||||
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.
|
||||
> Please build a basic TODO list app in React. It should be frontend-only, and all state
|
||||
> should be kept in localStorage.
|
||||
|
||||
If the required `LLM Model` does not exist in the list, you can toggle `Advanced Options` and manually enter it with the correct prefix
|
||||
in the `Custom Model` text box.
|
||||
The `Advanced Options` also allow you to specify a `Base URL` if required.
|
||||
We can keep iterating on the app once the skeleton is there:
|
||||
|
||||
<div style={{ display: 'flex', justifyContent: 'center', gap: '20px' }}>
|
||||
<img src="/img/settings-screenshot.png" alt="settings-modal" width="340" />
|
||||
<img src="/img/settings-advanced.png" alt="settings-modal" width="335" />
|
||||
</div>
|
||||
> Please allow adding an optional due date to every task
|
||||
|
||||
## Versions
|
||||
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.
|
||||
You can ask the agent to commit and push for you:
|
||||
|
||||
The command above pulls the most recent stable release of OpenHands. You have other options as well:
|
||||
- For a specific release, use `ghcr.io/all-hands-ai/openhands:$VERSION`, replacing $VERSION with the version number.
|
||||
- We use semver, and release major, minor, and patch tags. So `0.9` will automatically point to the latest `0.9.x` release, and `0` will point to the latest `0.x.x` release.
|
||||
- For the most up-to-date development version, you can use `ghcr.io/all-hands-ai/openhands:main`. This version is unstable and is recommended for testing or development purposes only.
|
||||
> Please commit the changes and push them to a new branch called "feature/due-dates"
|
||||
|
||||
You can choose the tag that best suits your needs based on stability requirements and desired features.
|
||||
|
||||
For the development workflow, see [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
|
||||
## Adding new code
|
||||
OpenHands can also do a great job adding new code to an existing code base.
|
||||
|
||||
Are you having trouble? Check out our [Troubleshooting Guide](https://docs.all-hands.dev/modules/usage/troubleshooting).
|
||||
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`
|
||||
|
||||
> 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 add a new React component that displays a list of Widgets to the ./frontend/components
|
||||
> directory. It should use the existing Widget component.
|
||||
|
||||
## Refactoring
|
||||
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 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
|
||||
|
||||
## Bug Fixes
|
||||
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.
|
||||
|
||||
> Currently the email field in the `/subscribe` endpoint is rejecting .io domains. Please fix this.
|
||||
|
||||
> 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.
|
||||
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
|
||||
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
|
||||
|
||||
See [Prompting Best Practices](./prompting-best-practices) for more tips on how to get the most out of OpenHands.
|
||||
|
||||
63
docs/modules/usage/installation.mdx
Normal file
63
docs/modules/usage/installation.mdx
Normal file
@ -0,0 +1,63 @@
|
||||
# Installation
|
||||
|
||||
## 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).
|
||||
|
||||
## Start the app
|
||||
|
||||
The easiest way to run OpenHands is in Docker. You can change `WORKSPACE_BASE` below to point OpenHands to
|
||||
existing code that you'd like to modify.
|
||||
|
||||
```bash
|
||||
export WORKSPACE_BASE=$(pwd)/workspace
|
||||
|
||||
docker pull ghcr.io/all-hands-ai/runtime:0.9-nikolaik
|
||||
|
||||
docker run -it --pull=always \
|
||||
-e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.9-nikolaik \
|
||||
-e SANDBOX_USER_ID=$(id -u) \
|
||||
-e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
|
||||
-v $WORKSPACE_BASE:/opt/workspace_base \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
-p 3000:3000 \
|
||||
--add-host host.docker.internal:host-gateway \
|
||||
--name openhands-app-$(date +%Y%m%d%H%M%S) \
|
||||
ghcr.io/all-hands-ai/openhands:0.9
|
||||
```
|
||||
|
||||
You can also run OpenHands in a scriptable [headless mode](https://docs.all-hands.dev/modules/usage/how-to/headless-mode), as an [interactive CLI](https://docs.all-hands.dev/modules/usage/how-to/cli-mode), or using the [OpenHands GitHub Action](https://docs.all-hands.dev/modules/usage/how-to/github-action).
|
||||
|
||||
## Setup
|
||||
|
||||
After running the command above, you'll find OpenHands running at [http://localhost:3000](http://localhost:3000).
|
||||
|
||||
The agent will have access to the `./workspace` folder to do its work. You can copy existing code here, or change `WORKSPACE_BASE` in the
|
||||
command to point to an existing folder.
|
||||
|
||||
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.
|
||||
|
||||
If the required `LLM Model` does not exist in the list, you can toggle `Advanced Options` and manually enter it with the correct prefix
|
||||
in the `Custom Model` text box.
|
||||
The `Advanced Options` also allow you to specify a `Base URL` if required.
|
||||
|
||||
<div style={{ display: 'flex', justifyContent: 'center', gap: '20px' }}>
|
||||
<img src="/img/settings-screenshot.png" alt="settings-modal" width="340" />
|
||||
<img src="/img/settings-advanced.png" alt="settings-modal" width="335" />
|
||||
</div>
|
||||
|
||||
## Versions
|
||||
|
||||
The command above pulls the most recent stable release of OpenHands. You have other options as well:
|
||||
- For a specific release, use `ghcr.io/all-hands-ai/openhands:$VERSION`, replacing $VERSION with the version number.
|
||||
- We use semver, and release major, minor, and patch tags. So `0.9` will automatically point to the latest `0.9.x` release, and `0` will point to the latest `0.x.x` release.
|
||||
- For the most up-to-date development version, you can use `ghcr.io/all-hands-ai/openhands:main`. This version is unstable and is recommended for testing or development purposes only.
|
||||
|
||||
You can choose the tag that best suits your needs based on stability requirements and desired features.
|
||||
|
||||
For the development workflow, see [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
|
||||
|
||||
Are you having trouble? Check out our [Troubleshooting Guide](https://docs.all-hands.dev/modules/usage/troubleshooting).
|
||||
@ -5,7 +5,7 @@ OpenHands uses LiteLLM to make calls to Azure's chat models. You can find their
|
||||
## Azure OpenAI Configuration
|
||||
|
||||
When running OpenHands, you'll need to set the following environment variable using `-e` in the
|
||||
[docker run command](/modules/usage/getting-started#installation):
|
||||
[docker run command](/modules/usage/installation):
|
||||
|
||||
```
|
||||
LLM_API_VERSION="<api-version>" # e.g. "2023-05-15"
|
||||
@ -37,7 +37,7 @@ OpenHands uses llama-index for embeddings. You can find their documentation on A
|
||||
### Azure OpenAI Configuration
|
||||
|
||||
When running OpenHands, set the following environment variables using `-e` in the
|
||||
[docker run command](/modules/usage/getting-started#installation):
|
||||
[docker run command](/modules/usage/installation):
|
||||
|
||||
```
|
||||
LLM_EMBEDDING_MODEL="azureopenai"
|
||||
|
||||
@ -16,7 +16,7 @@ If the model is not in the list, toggle `Advanced Options`, and enter it in `Cus
|
||||
## VertexAI - Google Cloud Platform Configs
|
||||
|
||||
To use Vertex AI through Google Cloud Platform when running OpenHands, you'll need to set the following environment
|
||||
variables using `-e` in the [docker run command](/modules/usage/getting-started#installation):
|
||||
variables using `-e` in the [docker run command](/modules/usage/installation):
|
||||
|
||||
```
|
||||
GOOGLE_APPLICATION_CREDENTIALS="<json-dump-of-gcp-service-account-json>"
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# 🤖 LLM Backends
|
||||
|
||||
OpenHands can connect to any LLM supported by LiteLLM. However, it requires a powerful model to work.
|
||||
@ -38,7 +34,7 @@ The following can be set in the OpenHands UI through the Settings:
|
||||
* `Base URL` (through `Advanced Settings`)
|
||||
|
||||
There are some settings that may be necessary for some LLMs/providers that cannot be set through the UI. Instead, these
|
||||
can be set through environment variables passed to the [docker run command](/modules/usage/getting-started#installation)
|
||||
can be set through environment variables passed to the [docker run command](/modules/usage/installation)
|
||||
using `-e`:
|
||||
|
||||
* `LLM_API_VERSION`
|
||||
|
||||
@ -37,3 +37,5 @@ Good prompts are:
|
||||
5. 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.
|
||||
|
||||
See [Getting Started with OpenHands](./getting-started) for more examples of helpful prompts.
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# 🚧 Troubleshooting
|
||||
|
||||
There are some error messages that frequently get reported by users.
|
||||
|
||||
@ -1,7 +1,3 @@
|
||||
---
|
||||
sidebar_position: 8
|
||||
---
|
||||
|
||||
# ⬆️ Upgrade Guide
|
||||
|
||||
## 0.8.0 (2024-07-13)
|
||||
|
||||
@ -3,11 +3,21 @@ import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
|
||||
const sidebars: SidebarsConfig = {
|
||||
apiSidebar: [require("./modules/python/sidebar.json")],
|
||||
docsSidebar: [
|
||||
{
|
||||
type: 'doc',
|
||||
label: 'Installation',
|
||||
id: 'usage/installation',
|
||||
},
|
||||
{
|
||||
type: 'doc',
|
||||
label: 'Getting Started',
|
||||
id: 'usage/getting-started',
|
||||
},
|
||||
{
|
||||
type: 'doc',
|
||||
label: 'Prompting Best Practices',
|
||||
id: 'usage/prompting-best-practices',
|
||||
},
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Usage Methods',
|
||||
@ -27,11 +37,6 @@ const sidebars: SidebarsConfig = {
|
||||
label: 'Github Actions',
|
||||
id: 'usage/how-to/github-action',
|
||||
},
|
||||
{
|
||||
type: 'doc',
|
||||
label: 'Prompting Best Practices',
|
||||
id: 'usage/prompting-best-practices',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user