Skip to content

Commit

Permalink
Merge branch 'main' into fix-closing-sessions
Browse files Browse the repository at this point in the history
  • Loading branch information
@tofarr
tofarr authored Jan 7, 2025
2 parents bab53a0 + 9747c9e commit 88af9f8
Show file tree
Hide file tree
Showing 7 changed files with 109 additions and 100 deletions.
22 changes: 11 additions & 11 deletions CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
[email protected]
[email protected].
All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the
Expand Down
12 changes: 6 additions & 6 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,19 @@ 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:

1. **Download and use** OpenHands, and send [issues](https://github.com/All-Hands-AI/OpenHands/issues) when you encounter something that isn't working or a feature that you'd like to see.
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
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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

Expand Down
16 changes: 8 additions & 8 deletions Development.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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!)
Expand Down Expand Up @@ -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
```
Expand All @@ -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
```
Expand All @@ -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
Expand All @@ -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.
Expand Down
8 changes: 4 additions & 4 deletions ISSUE_TRIAGE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@
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.
* **Medium**: Affecting multiple users.
* **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.
Expand Down
110 changes: 57 additions & 53 deletions docs/modules/usage/prompting/microagents.md → ...les/usage/prompting/microagents-public.md
View file
Original file line number Diff line number Diff line change
@@ -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`
Expand All @@ -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`
Expand All @@ -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:

```bash
yes | npm install package-name
```

You can create your own micro-agents by adding new markdown files to the micro-agents directory.
### 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
Expand All @@ -55,55 +83,41 @@ 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

```bash
# GitHub agent example
git checkout -b feature-branch
git commit -m "Add new feature"
git push origin feature-branch

# NPM agent example
yes | npm install package-name
```

For more information about specific agents, refer to their individual documentation files in the micro-agents directory.

## Contributing a Micro-Agent
- **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.

To contribute a new micro-agent to OpenHands, follow these guidelines:
To contribute a new micro-agent to OpenHands:

### 1. Planning Your Micro-Agent
### 1. Plan the Public 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?
- What constraints or guidelines should it follow?

### 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
Expand Down Expand Up @@ -133,23 +147,22 @@ 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.
- Verify trigger words activate the agent correctly.
- 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:

Expand Down Expand Up @@ -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.
17 changes: 8 additions & 9 deletions .../modules/usage/prompting/customization.md → ...dules/usage/prompting/microagents-repo.md
View file
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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.
Expand All @@ -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.
Loading

0 comments on commit 88af9f8

Please sign in to comment.