diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 8c66075aef..502058015a 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -18,24 +18,24 @@ diverse, inclusive, and healthy community. Examples of behavior that contributes to a positive environment for our community include: -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback +* Demonstrating empathy and kindness toward other people. +* Being respectful of differing opinions, viewpoints, and experiences. +* Giving and gracefully accepting constructive feedback. * Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience + and learning from the experience. * Focusing on what is best not just for us as individuals, but for the overall - community + community. Examples of unacceptable behavior include: * The use of sexualized language or imagery, and sexual attention or advances of - any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment + any kind. +* Trolling, insulting or derogatory comments, and personal or political attacks. +* Public or private harassment. * Publishing others' private information, such as a physical or email address, - without their explicit permission + without their explicit permission. * Other conduct which could reasonably be considered inappropriate in a - professional setting + professional setting. ## Enforcement Responsibilities @@ -61,7 +61,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -contact@all-hands.dev +contact@all-hands.dev. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b1914cbd5b..2ffc73c9c6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,11 +11,11 @@ To understand the codebase, please refer to the README in each module: - [agenthub](./openhands/agenthub/README.md) - [server](./openhands/server/README.md) -## Setting up your development environment +## Setting up Your Development Environment We have a separate doc [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md) that tells you how to set up a development workflow. -## How can I contribute? +## How Can I Contribute? There are many ways that you can contribute: @@ -23,7 +23,7 @@ There are many ways that you can contribute: 2. **Send feedback** after each session by [clicking the thumbs-up thumbs-down buttons](https://docs.all-hands.dev/modules/usage/feedback), so we can see where things are working and failing, and also build an open dataset for training code agents. 3. **Improve the Codebase** by sending [PRs](#sending-pull-requests-to-openhands) (see details below). In particular, we have some [good first issues](https://github.com/All-Hands-AI/OpenHands/labels/good%20first%20issue) that may be ones to start on. -## What can I build? +## What Can I Build? Here are a few ways you can help improve the codebase. #### UI/UX @@ -35,7 +35,7 @@ of the application, please open an issue first, or better, join the #frontend ch to gather consensus from our design team first. #### Improving the agent -Our main agent is the CodeAct agent. You can [see its prompts here](https://github.com/All-Hands-AI/OpenHands/tree/main/openhands/agenthub/codeact_agent) +Our main agent is the CodeAct agent. You can [see its prompts here](https://github.com/All-Hands-AI/OpenHands/tree/main/openhands/agenthub/codeact_agent). Changes to these prompts, and to the underlying behavior in Python, can have a huge impact on user experience. You can try modifying the prompts to see how they change the behavior of the agent as you use the app @@ -63,7 +63,7 @@ At the moment, we have two kinds of tests: [`unit`](./tests/unit) and [`integrat ## Sending Pull Requests to OpenHands You'll need to fork our repository to send us a Pull Request. You can learn more -about how to fork a GitHub repo and open a PR with your changes in [this article](https://medium.com/swlh/forks-and-pull-requests-how-to-contribute-to-github-repos-8843fac34ce8) +about how to fork a GitHub repo and open a PR with your changes in [this article](https://medium.com/swlh/forks-and-pull-requests-how-to-contribute-to-github-repos-8843fac34ce8). ### Pull Request title As described [here](https://github.com/commitizen/conventional-commit-types/blob/master/index.json), a valid PR title should begin with one of the following prefixes: @@ -103,7 +103,7 @@ Further, if you see an issue you like, please leave a "thumbs-up" or a comment, ### Making Pull Requests -We're generally happy to consider all [PRs](https://github.com/All-Hands-AI/OpenHands/pulls), with the evaluation process varying based on the type of change: +We're generally happy to consider all pull requests with the evaluation process varying based on the type of change: #### For Small Improvements diff --git a/Development.md b/Development.md index e28bb49f0f..3ac856c2ce 100644 --- a/Development.md +++ b/Development.md @@ -3,7 +3,7 @@ This guide is for people working on OpenHands and editing the source code. If you wish to contribute your changes, check out the [CONTRIBUTING.md](https://github.com/All-Hands-AI/OpenHands/blob/main/CONTRIBUTING.md) on how to clone and setup the project initially before moving on. Otherwise, you can clone the OpenHands project directly. -## Start the server for development +## Start the Server for Development ### 1. Requirements * Linux, Mac OS, or [WSL on Windows](https://learn.microsoft.com/en-us/windows/wsl/install) [Ubuntu <= 22.04] * [Docker](https://docs.docker.com/engine/install/) (For those on MacOS, make sure to allow the default Docker socket to be used from advanced settings!) @@ -58,7 +58,7 @@ See [our documentation](https://docs.all-hands.dev/modules/usage/llms) for recom ### 4. Running the application #### Option A: Run the Full Application -Once the setup is complete, launching OpenHands is as simple as running a single command. This command starts both the backend and frontend servers seamlessly, allowing you to interact with OpenHands: +Once the setup is complete, this command starts both the backend and frontend servers, allowing you to interact with OpenHands: ```bash make run ``` @@ -75,11 +75,11 @@ make run ``` ### 6. LLM Debugging -If you encounter any issues with the Language Model (LM) or you're simply curious, you can inspect the actual LLM prompts and responses. To do so, export DEBUG=1 in the environment and restart the backend. -OpenHands will then log the prompts and responses in the logs/llm/CURRENT_DATE directory, allowing you to identify the causes. +If you encounter any issues with the Language Model (LM) or you're simply curious, export DEBUG=1 in the environment and restart the backend. +OpenHands will log the prompts and responses in the logs/llm/CURRENT_DATE directory, allowing you to identify the causes. ### 7. Help -Need assistance or information on available targets and commands? The help command provides all the necessary guidance to ensure a smooth experience with OpenHands. +Need help or info on available targets and commands? Use the help command for all the guidance you need with OpenHands. ```bash make help ``` @@ -93,8 +93,8 @@ poetry run pytest ./tests/unit/test_*.py ``` ### 9. Add or update dependency -1. Add your dependency in `pyproject.toml` or use `poetry add xxx` -2. Update the poetry.lock file via `poetry lock --no-update` +1. Add your dependency in `pyproject.toml` or use `poetry add xxx`. +2. Update the poetry.lock file via `poetry lock --no-update`. ### 9. Use existing Docker image To reduce build time (e.g., if no changes were made to the client-runtime component), you can use an existing Docker container image by @@ -110,7 +110,7 @@ TL;DR make docker-dev ``` -See more details [here](./containers/dev/README.md) +See more details [here](./containers/dev/README.md). If you are just interested in running `OpenHands` without installing all the required tools on your host. diff --git a/ISSUE_TRIAGE.md b/ISSUE_TRIAGE.md index 1cb12cc9ea..0bec648482 100644 --- a/ISSUE_TRIAGE.md +++ b/ISSUE_TRIAGE.md @@ -2,8 +2,8 @@ These are the procedures and guidelines on how issues are triaged in this repo by the maintainers. ## General -* Most issues must be tagged with **enhancement** or **bug** -* Issues may be tagged with what it relates to (**backend**, **frontend**, **agent quality**, etc.) +* Most issues must be tagged with **enhancement** or **bug**. +* Issues may be tagged with what it relates to (**backend**, **frontend**, **agent quality**, etc.). ## Severity * **Low**: Minor issues or affecting single user. @@ -11,10 +11,10 @@ These are the procedures and guidelines on how issues are triaged in this repo b * **Critical**: Affecting all users or potential security issues. ## Effort -* Issues may be estimated with effort required (**small effort**, **medium effort**, **large effort**) +* Issues may be estimated with effort required (**small effort**, **medium effort**, **large effort**). ## Difficulty -* Issues with low implementation difficulty may be tagged with **good first issue** +* Issues with low implementation difficulty may be tagged with **good first issue**. ## Not Enough Information * User is asked to provide more information (logs, how to reproduce, etc.) when the issue is not clear. diff --git a/docs/modules/usage/prompting/microagents.md b/docs/modules/usage/prompting/microagents-public.md similarity index 70% rename from docs/modules/usage/prompting/microagents.md rename to docs/modules/usage/prompting/microagents-public.md index 51f9f91b49..f966977bf2 100644 --- a/docs/modules/usage/prompting/microagents.md +++ b/docs/modules/usage/prompting/microagents-public.md @@ -1,17 +1,31 @@ -# Micro-Agents +# Public Micro-Agents -OpenHands uses specialized micro-agents to handle specific tasks and contexts efficiently. These micro-agents are small, focused components that provide specialized behavior and knowledge for particular scenarios. +OpenHands uses specialized micro-agents to handle specific tasks and contexts efficiently. These micro-agents are small, +focused components that provide specialized behavior and knowledge for particular scenarios. ## Overview -Micro-agents are defined in markdown files under the `openhands/agenthub/codeact_agent/micro/` directory. Each micro-agent is configured with: +Public micro-agents are defined in markdown files under the +[`microagents/knowledge/`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge) 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. -## Available Micro-Agents +### Integration + +Public 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. + +## Available Public Micro-Agents + +For more information about specific micro-agents, refer to their individual documentation files in +the [`micro-agents`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents) directory. ### GitHub Agent **File**: `github.md` @@ -29,6 +43,14 @@ Key features: - Git configuration management - API-first approach for GitHub operations +Usage Example: + +```bash +git checkout -b feature-branch +git commit -m "Add new feature" +git push origin feature-branch +``` + ### NPM Agent **File**: `npm.md` **Triggers**: `npm` @@ -38,9 +60,15 @@ Specializes in handling npm package management with specific focus on: - Automated confirmation handling using Unix 'yes' command. - Package installation automation. -### Custom Micro-Agents +Usage Example: -You can create your own micro-agents by adding new markdown files to the micro-agents directory. +```bash +yes | npm install package-name +``` + +### Custom Public Micro-Agents + +You can create your own public micro-agents by adding new markdown files to the `microagents/knowledge/` directory. Each file should follow this structure: ```markdown @@ -55,43 +83,29 @@ triggers: Instructions and capabilities for the micro-agent... ``` -## Best Practices +## Working With Public Micro-Agents -When working with micro-agents: +When working with public micro-agents: - **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 +## Contributing a Public Micro-Agent -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. +Best practices for creating public micro-agents: -## Example Usage +- **Clear Scope**: Keep the micro-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 micro-agent interacts with other components. -```bash -# GitHub agent example -git checkout -b feature-branch -git commit -m "Add new feature" -git push origin feature-branch +To contribute a new micro-agent to OpenHands: -# NPM agent example -yes | npm install package-name -``` +### 1. Plan the Public Micro-Agent -For more information about specific agents, refer to their individual documentation files in the micro-agents directory. - -## Contributing a Micro-Agent - -To contribute a new micro-agent to OpenHands, follow these guidelines: - -### 1. Planning Your Micro-Agent - -Before creating a micro-agent, consider: +Before creating a public micro-agent, consider: - What specific problem or use case will it address? - What unique capabilities or knowledge should it have? - What trigger words make sense for activating it? @@ -99,11 +113,11 @@ Before creating a micro-agent, consider: ### 2. File Structure -Create a new markdown file in `openhands/agenthub/codeact_agent/micro/` with a descriptive name (e.g., `docker.md` for a Docker-focused agent). +Create a new markdown file in `microagents/knowledge/` with a descriptive name (e.g., `docker.md` for a Docker-focused agent). ### 3. Required Components -Your micro-agent file must include: +The micro-agent file must include: - **Front Matter**: YAML metadata at the start of the file: ```markdown @@ -133,15 +147,7 @@ Examples of usage: [Example 2] ``` -### 4. Best Practices for Micro-Agent Development - -- **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 +### 4. Testing the Public Micro-Agent Before submitting: - Test the agent with various prompts. @@ -149,7 +155,14 @@ Before submitting: - Ensure instructions are clear and comprehensive. - Check for potential conflicts with existing agents. -### 6. Example Implementation +### 5. Submission Process + +Submit a pull request with: +- The new micro-agent file. +- Updated documentation if needed. +- Description of the agent's purpose and capabilities. + +### Example Public Micro-Agent Implementation Here's a template for a new micro-agent: @@ -197,14 +210,5 @@ Remember to: - Optimize for build time and image size ``` -### 7. Submission Process - -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. - 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/customization.md b/docs/modules/usage/prompting/microagents-repo.md similarity index 80% rename from docs/modules/usage/prompting/customization.md rename to docs/modules/usage/prompting/microagents-repo.md index 362368d9ed..3d294f22d4 100644 --- a/docs/modules/usage/prompting/customization.md +++ b/docs/modules/usage/prompting/microagents-repo.md @@ -1,10 +1,12 @@ -# Customizing Agent Behavior +# Repository Micro-Agents -OpenHands can be customized to work more effectively with specific repositories by providing repository-specific context and guidelines. This section explains how to optimize OpenHands for your project. +OpenHands can be customized to work more effectively with specific repositories by providing repository-specific context +and guidelines. This section explains how to optimize OpenHands for your project. ## Repository Configuration -You can customize OpenHands' behavior for your repository by creating a `.openhands` directory in your repository's root. At minimum, it should contain the file +You can customize OpenHands' behavior for your repository by creating a `.openhands/microagents/` directory in your repository's root. +At minimum, it should contain the file `.openhands/microagents/repo.md`, which includes instructions that will be given to the agent every time it works with this repository. @@ -39,7 +41,8 @@ Guidelines: ### Customizing Prompts -When working with a repository: +You may also add customized prompts to the `.openhands/microagents/repo.md` file when working with a repository. +These could: - **Reference Project Standards**: Mention specific coding standards or patterns used in your project. - **Include Context**: Reference relevant documentation or existing implementations. @@ -54,14 +57,10 @@ The component should use our shared styling from src/styles/components. ### Best Practices for Repository Customization -- **Keep Instructions Updated**: Regularly update your `.openhands` directory as your project evolves. +- **Keep Instructions Updated**: Regularly update your `.openhands/microagents/` 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 [Micro-Agents](microagents.md) for more information. diff --git a/docs/sidebars.ts b/docs/sidebars.ts index f67d54cdb5..12911c3172 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -23,15 +23,21 @@ const sidebars: SidebarsConfig = { id: 'usage/prompting/prompting-best-practices', }, { - type: 'doc', - label: 'Customization', - id: 'usage/prompting/customization', - }, - { - type: 'doc', - label: 'Microagents', - id: 'usage/prompting/microagents', - }, + type: 'category', + label: 'Micro-Agents', + items: [ + { + type: 'doc', + label: 'Public', + id: 'usage/prompting/microagents-public', + }, + { + type: 'doc', + label: 'Repository', + id: 'usage/prompting/microagents-repo', + }, + ], + } ], }, {