Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document changes for Micro-Agents and some formatting changes #6155

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+140 −221
Open

Document changes for Micro-Agents and some formatting changes #6155

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
bfbf1b5
More doc changes
mamoodi Jan 8, 2025
7795a9f
Rejig the Micro-Agents documentation
mamoodi Jan 9, 2025
ea2b104
Update docs/modules/usage/prompting/microagents-overview.md
mamoodi Jan 9, 2025
8662654
Update docs/modules/usage/prompting/microagents-overview.md
mamoodi Jan 9, 2025
1d1f874
Standardize on microagents
mamoodi Jan 9, 2025
121fd72
Missed some microagents
mamoodi Jan 9, 2025
5d898d5
Remove loading order header
mamoodi Jan 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 29 additions & 71 deletions docs/modules/usage/configuration-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,53 +7,11 @@ If you are running in [GUI Mode](https://docs.all-hands.dev/modules/usage/how-to
take precedence.
:::

---

# Table of Contents

- [Core Configuration](#core-configuration)
- [API Keys](#api-keys)
- [Workspace](#workspace)
- [Debugging and Logging](#debugging-and-logging)
- [Session Management](#session-management)
- [Trajectories](#trajectories)
- [File Store](#file-store)
- [Task Management](#task-management)
- [Sandbox Configuration](#sandbox-configuration)
- [Miscellaneous](#miscellaneous)
- [LLM Configuration](#llm-configuration)
- [AWS Credentials](#aws-credentials)
- [API Configuration](#api-configuration)
- [Custom LLM Provider](#custom-llm-provider)
- [Embeddings](#embeddings)
- [Message Handling](#message-handling)
- [Model Selection](#model-selection)
- [Retrying](#retrying)
- [Advanced Options](#advanced-options)
- [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)
- [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)
- [Security Configuration](#security-configuration)
- [Confirmation Mode](#confirmation-mode)
- [Security Analyzer](#security-analyzer)

---

## Core Configuration

The core configuration options are defined in the `[core]` section of the `config.toml` file.

**API Keys**
### API Keys
- `e2b_api_key`
- Type: `str`
- Default: `""`
Expand All @@ -69,7 +27,7 @@ The core configuration options are defined in the `[core]` section of the `confi
- Default: `""`
- Description: API token secret for Modal

**Workspace**
### Workspace
- `workspace_base`
- Type: `str`
- Default: `"./workspace"`
Expand All @@ -80,7 +38,7 @@ The core configuration options are defined in the `[core]` section of the `confi
- Default: `"/tmp/cache"`
- Description: Cache directory path

**Debugging and Logging**
### Debugging and Logging
- `debug`
- Type: `bool`
- Default: `false`
Expand All @@ -91,13 +49,13 @@ The core configuration options are defined in the `[core]` section of the `confi
- Default: `false`
- Description: Disable color in terminal output

**Trajectories**
### Trajectories
- `trajectories_path`
- Type: `str`
- Default: `"./trajectories"`
- Description: Path to store trajectories (can be a folder or a file). If it's a folder, the trajectories will be saved in a file named with the session id name and .json extension, in that folder.

**File Store**
### File Store
- `file_store_path`
- Type: `str`
- Default: `"/tmp/file_store"`
Expand Down Expand Up @@ -128,7 +86,7 @@ The core configuration options are defined in the `[core]` section of the `confi
- Default: `[".*"]`
- Description: List of allowed file extensions for uploads

**Task Management**
### Task Management
- `max_budget_per_task`
- Type: `float`
- Default: `0.0`
Expand All @@ -139,7 +97,7 @@ The core configuration options are defined in the `[core]` section of the `confi
- Default: `100`
- Description: Maximum number of iterations

**Sandbox Configuration**
### Sandbox Configuration
- `workspace_mount_path_in_sandbox`
- Type: `str`
- Default: `"/workspace"`
Expand All @@ -155,7 +113,7 @@ The core configuration options are defined in the `[core]` section of the `confi
- Default: `""`
- Description: Path to rewrite the workspace mount path to. You can usually ignore this, it refers to special cases of running inside another container.

**Miscellaneous**
### Miscellaneous
- `run_as_openhands`
- Type: `bool`
- Default: `true`
Expand All @@ -182,7 +140,7 @@ The LLM (Large Language Model) configuration options are defined in the `[llm]`

To use these with the docker command, pass in `-e LLM_<option>`. Example: `-e LLM_NUM_RETRIES`.

**AWS Credentials**
### AWS Credentials
- `aws_access_key_id`
- Type: `str`
- Default: `""`
Expand All @@ -198,7 +156,7 @@ To use these with the docker command, pass in `-e LLM_<option>`. Example: `-e LL
- Default: `""`
- Description: AWS secret access key

**API Configuration**
### API Configuration
- `api_key`
- Type: `str`
- Default: `None`
Expand All @@ -224,13 +182,13 @@ To use these with the docker command, pass in `-e LLM_<option>`. Example: `-e LL
- Default: `0.0`
- Description: Cost per output token

**Custom LLM Provider**
### Custom LLM Provider
- `custom_llm_provider`
- Type: `str`
- Default: `""`
- Description: Custom LLM provider

**Embeddings**
### Embeddings
- `embedding_base_url`
- Type: `str`
- Default: `""`
Expand All @@ -246,7 +204,7 @@ To use these with the docker command, pass in `-e LLM_<option>`. Example: `-e LL
- Default: `"local"`
- Description: Embedding model to use

**Message Handling**
### Message Handling
- `max_message_chars`
- Type: `int`
- Default: `30000`
Expand All @@ -262,13 +220,13 @@ To use these with the docker command, pass in `-e LLM_<option>`. Example: `-e LL
- Default: `0`
- Description: Maximum number of output tokens

**Model Selection**
### Model Selection
- `model`
- Type: `str`
- Default: `"claude-3-5-sonnet-20241022"`
- Description: Model to use

**Retrying**
### Retrying
- `num_retries`
- Type: `int`
- Default: `8`
Expand All @@ -289,7 +247,7 @@ To use these with the docker command, pass in `-e LLM_<option>`. Example: `-e LL
- Default: `2.0`
- Description: Multiplier for exponential backoff calculation

**Advanced Options**
### Advanced Options
- `drop_params`
- Type: `bool`
- Default: `false`
Expand Down Expand Up @@ -329,13 +287,13 @@ To use these with the docker command, pass in `-e LLM_<option>`. Example: `-e LL

The agent configuration options are defined in the `[agent]` and `[agent.<agent_name>]` sections of the `config.toml` file.

**Microagent Configuration**
### Microagent Configuration
- `micro_agent_name`
- Type: `str`
- Default: `""`
- Description: Name of the micro agent to use for this agent

**Memory Configuration**
### Memory Configuration
- `memory_enabled`
- Type: `bool`
- Default: `false`
Expand All @@ -346,13 +304,13 @@ The agent configuration options are defined in the `[agent]` and `[agent.<agent_
- Default: `3`
- Description: The maximum number of threads indexing at the same time for embeddings

**LLM Configuration**
### LLM Configuration
- `llm_config`
- Type: `str`
- Default: `'your-llm-config-group'`
- Description: The name of the LLM config to use

**ActionSpace Configuration**
### ActionSpace Configuration
- `function_calling`
- Type: `bool`
- Default: `true`
Expand All @@ -373,7 +331,7 @@ The agent configuration options are defined in the `[agent]` and `[agent.<agent_
- Default: `false`
- Description: Whether Jupyter is enabled in the action space

**Microagent Usage**
### Microagent Usage
- `use_microagents`
- Type: `bool`
- Default: `true`
Expand All @@ -390,7 +348,7 @@ The sandbox configuration options are defined in the `[sandbox]` section of the

To use these with the docker command, pass in `-e SANDBOX_<option>`. Example: `-e SANDBOX_TIMEOUT`.

**Execution**
### Execution
- `timeout`
- Type: `int`
- Default: `120`
Expand All @@ -401,19 +359,19 @@ To use these with the docker command, pass in `-e SANDBOX_<option>`. Example: `-
- Default: `1000`
- Description: Sandbox user ID

**Container Image**
### Container Image
- `base_container_image`
- Type: `str`
- Default: `"nikolaik/python-nodejs:python3.12-nodejs22"`
- Description: Container image to use for the sandbox

**Networking**
### Networking
- `use_host_network`
- Type: `bool`
- Default: `false`
- Description: Use host network

**Linting and Plugins**
### Linting and Plugins
- `enable_auto_lint`
- Type: `bool`
- Default: `false`
Expand All @@ -424,7 +382,7 @@ To use these with the docker command, pass in `-e SANDBOX_<option>`. Example: `-
- Default: `true`
- Description: Whether to initialize plugins

**Dependencies and Environment**
### Dependencies and Environment
- `runtime_extra_deps`
- Type: `str`
- Default: `""`
Expand All @@ -435,7 +393,7 @@ To use these with the docker command, pass in `-e SANDBOX_<option>`. Example: `-
- Default: `{}`
- Description: Environment variables to set at the launch of the runtime

**Evaluation**
### Evaluation
- `browsergym_eval_env`
- Type: `str`
- Default: `""`
Expand All @@ -447,13 +405,13 @@ The security configuration options are defined in the `[security]` section of th

To use these with the docker command, pass in `-e SECURITY_<option>`. Example: `-e SECURITY_CONFIRMATION_MODE`.

**Confirmation Mode**
### Confirmation Mode
- `confirmation_mode`
- Type: `bool`
- Default: `false`
- Description: Enable confirmation mode

**Security Analyzer**
### Security Analyzer
- `security_analyzer`
- Type: `str`
- Default: `""`
Expand Down
6 changes: 3 additions & 3 deletions docs/modules/usage/how-to/cli-mode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Here are some examples of CLI commands and their expected outputs:
### Example 1: Simple Task

```bash
How can I help? >> Write a Python script that prints "Hello, World!"
>> Write a Python script that prints "Hello, World!"
enyst marked this conversation as resolved.
Show resolved Hide resolved
```

Expected Output:
Expand All @@ -72,7 +72,7 @@ Expected Output:
### Example 2: Bash Command

```bash
How can I help? >> Create a directory named "test_dir"
>> Create a directory named "test_dir"
```

Expected Output:
Expand All @@ -86,7 +86,7 @@ Expected Output:
### Example 3: Error Handling

```bash
How can I help? >> Delete a non-existent file
>> Delete a non-existent file
```

Expected Output:
Expand Down
6 changes: 3 additions & 3 deletions docs/modules/usage/how-to/gui-mode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,18 +76,18 @@ When using OpenHands in online mode, the GitHub OAuth flow:

Common issues and solutions:

1. **Token Not Recognized**:
- **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.

2. **Organization Access Denied**:
- **Organization Access Denied**:
- Check if SSO is required but not enabled.
- Verify organization membership.
- Contact organization admin if token policies are blocking access.

3. **Verifying Token Works**:
- **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.
Expand Down
16 changes: 0 additions & 16 deletions docs/modules/usage/how-to/persist-session-data.md
View file
Open in desktop

This file was deleted.

38 changes: 38 additions & 0 deletions docs/modules/usage/prompting/microagents-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Micro-Agents Overview
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rbren I tried to follow your comment from the other PR and wrote this in the overview. Not sure what else to add. In its current state is it providing any value?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm leaning towards removing this right now unless you have ideas on how to add more value here.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah there is a bunch of stuff we can put here about the YAML header options. Especially the way triggers work right now

I've also been trying to standardize on Microagent as the way this is stylized

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I need to get back to this PR later. I think this Micro-Agents section needs a lot of love :D

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rejigged it.


Micro-Agents are specialized prompts that enhance OpenHands with domain-specific knowledge, repository-specific context
and task-specific workflows. They help by providing expert guidance, automating common tasks, and ensuring
consistent practices across projects.

## Micro-Agent Types

Currently OpenHands supports the following types of micro-agents:

* [Repository Micro-Agents](./microagents-repo): Repository-specific context and guidelines for OpenHands.
* [Public Micro-Agents](./microagents-public): General guidelines triggered by keywords for all OpenHands users.

## Loading Order

When OpenHands works with a repository, it:

1. Loads repository-specific instructions from `.openhands/microagents/` if present in the repository.
2. Loads general guidelines triggered by keywords in conversations.
See current [Public Micro-Agents](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge).

## Micro-Agent Format

All micro-agents use markdown files with YAML frontmatter that have special instructions to help OpenHands accomplish
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we standardize on microagent (no hyphen)?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

tasks:
```
---
name: <Name of the micro-agent>
type: <Micro-Agent type>
version: <Micro-Agent version>
agent: <The agent type (Typically CodeActAgent)>
triggers:
- <Optional keywords triggering the micro-agent. If triggers are removed, it will always be followed>
mamoodi marked this conversation as resolved.
Show resolved Hide resolved
---

<Any special guidelines, instructions, and prompts that OpenHands should follow.
mamoodi marked this conversation as resolved.
Show resolved Hide resolved
Check out the specific documentation for each micro-agent on best practices for more information.>
```
Loading
Loading