From 5dba964281ae1a070f97b2f4ca4e8cff2e42df4d Mon Sep 17 00:00:00 2001 From: Caique Date: Thu, 27 Mar 2025 16:11:14 +0100 Subject: [PATCH] docs: Improve the Microagents usage documentation (#7542) --- .../usage/prompting/microagents-overview.md | 37 ++--- .../usage/prompting/microagents-public.md | 138 ++++------------ .../usage/prompting/microagents-repo.md | 151 ++++++++++++------ .../usage/prompting/microagents-syntax.md | 128 +++++++++++++++ docs/sidebars.ts | 11 +- microagents/knowledge/add_agent.md | 49 +++--- 6 files changed, 307 insertions(+), 207 deletions(-) create mode 100644 docs/modules/usage/prompting/microagents-syntax.md diff --git a/docs/modules/usage/prompting/microagents-overview.md b/docs/modules/usage/prompting/microagents-overview.md index acfe4a1ed7..c78b0c2124 100644 --- a/docs/modules/usage/prompting/microagents-overview.md +++ b/docs/modules/usage/prompting/microagents-overview.md @@ -4,33 +4,28 @@ Microagents are specialized prompts that enhance OpenHands with domain-specific and task-specific workflows. They help by providing expert guidance, automating common tasks, and ensuring consistent practices across projects. -## Microagent Types +## Microagent Categories -Currently OpenHands supports the following types of microagents: +Currently OpenHands supports two categories of microagents: -* [Repository Microagents](./microagents-repo): Repository-specific context and guidelines for OpenHands. -* [Public Microagents](./microagents-public): General guidelines triggered by keywords for all OpenHands users. +- [Repository-specific Microagents](./microagents-repo): Repository-specific context and guidelines for OpenHands. +- [Public Microagents](./microagents-public): General guidelines triggered by keywords for all OpenHands users. + +A microagent is classified as repository-specific or public depending on its location: + +- Repository-specific microagents are located in a repository's `.openhands/microagents/` directory +- Public microagents are located in the official OpenHands repository inside the `/microagents` folder 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 Microagents](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge). +1. Loads **repository-specific** microagents from `.openhands/microagents/` if present in the repository. +2. Loads **public knowledge** microagents triggered by keywords in conversations +3. Loads **public tasks** microagents when explicitly requested by the user + +You can check out the existing public microagents at the [official OpenHands repository](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/). ## Microagent Format -All microagents use markdown files with YAML frontmatter that have special instructions to help OpenHands accomplish -tasks: -``` ---- -name: -type: -version: -agent: -triggers: -- ---- +All microagents use markdown files with YAML frontmatter that have special instructions to help OpenHands activate them. - -``` +Check out the [syntax documentation](./microagents-syntax) for a comprehensive guide on how to configure your microagents. diff --git a/docs/modules/usage/prompting/microagents-public.md b/docs/modules/usage/prompting/microagents-public.md index 0902ab4433..9f62323b3b 100644 --- a/docs/modules/usage/prompting/microagents-public.md +++ b/docs/modules/usage/prompting/microagents-public.md @@ -2,64 +2,32 @@ ## Overview -Public microagents are specialized guidelines triggered by keywords for all OpenHands users. -They are defined in markdown files under the -[`microagents/knowledge/`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge) directory. +Public microagents provide specialized context and capabilities for all OpenHands users, regardless of their repository configuration. Unlike repository-specific microagents, public microagents are globally available across all repositories. + +Public microagents come in two types: + +- **Knowledge microagents**: Automatically activated when keywords in conversations match their triggers +- **Task microagents**: Explicitly invoked by users to guide through specific workflows + +Both types follow the same syntax and structure as repository-specific microagents, using markdown files with YAML frontmatter that define their behavior and capabilities. They are located in the official OpenHands repository under: + +- [`microagents/knowledge/`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge) for knowledge microagents +- [`microagents/tasks/`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/tasks) for task microagents Public microagents: + - 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. -## Current Public Microagents - -For more information about specific microagents, refer to their individual documentation files in -the [`microagents/knowledge/`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge/) directory. - -### GitHub Agent -**File**: `github.md` -**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. - -Key features: -- Branch protection (prevents direct pushes to main/master) -- Automated PR creation -- 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` - -Specializes in handling npm package management with specific focus on: -- Non-interactive shell operations. -- Automated confirmation handling using Unix 'yes' command. -- Package installation automation. - -Usage Example: - -```bash -yes | npm install package-name -``` +When loading public microagents, OpenHands scans the official repository's microagents directories recursively, processing all markdown files except README.md. The system categorizes each microagent based on its `type` field in the YAML frontmatter, regardless of its exact file location within the knowledge or tasks directories. ## Contributing a Public Microagent -You can create your own public microagents by adding new markdown files to the -[`microagents/knowledge/`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge/) directory. +You can create public microagents and share with the community by opening a pull request to the official repository. + +See the [CONTRIBUTING.md](https://github.com/All-Hands-AI/OpenHands/blob/main/CONTRIBUTING.md) for specific instructions on how to contribute to OpenHands. ### Public Microagents Best Practices @@ -74,6 +42,7 @@ You can create your own public microagents by adding new markdown files to the #### 1. Plan the Public Microagent Before creating a public microagent, 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? @@ -81,73 +50,24 @@ Before creating a public microagent, consider: #### 2. Create File -Create a new markdown file in [`microagents/knowledge/`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge/) -with a descriptive name (e.g., `docker.md` for a Docker-focused agent). +Create a new Markdown file with a descriptive name in the appropriate directory: -Update the file with the required frontmatter [according to the required format](./microagents-overview#microagent-format) -and the required specialized guidelines while following the [best practices above](#public-microagents-best-practices). +- [`microagents/knowledge/`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge) for knowledge microagents +- [`microagents/tasks/`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/tasks) for task microagents + +Ensure it follows the correct [syntax](./microagents-syntax.md) and [best practices](./microagents-syntax.md#markdown-content-best-practices). #### 3. Testing the Public Microagent -- 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. +- Test the agent with various prompts +- Verify trigger words activate the agent correctly +- Ensure instructions are clear and comprehensive +- Check for potential conflicts and overlaps with existing agents #### 4. Submission Process Submit a pull request with: -- The new microagent file. -- Updated documentation if needed. -- Description of the agent's purpose and capabilities. -### Example Public Microagent Implementation - -Here's a template for a new microagent: - -```markdown ---- -name: docker -agent: CodeActAgent -triggers: -- docker -- container ---- - -You are responsible for Docker container management and Dockerfile creation. - -Key responsibilities: -1. Create and modify Dockerfiles -2. Manage container lifecycle -3. Handle Docker Compose configurations - -Guidelines: -- Always use official base images when possible -- Include necessary security considerations -- Follow Docker best practices for layer optimization - -Examples: -1. Creating a Dockerfile: - FROM node:18-alpine - WORKDIR /app - COPY package*.json ./ - RUN npm install - COPY . . - CMD ["npm", "start"] - -2. Docker Compose usage: - version: '3' - services: - web: - build: . - ports: - - "3000:3000" - -Remember to: -- Validate Dockerfile syntax -- Check for security vulnerabilities -- Optimize for build time and image size -``` - -See the [current public micro-agents](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge) for -more examples. +- The new microagent file +- Updated documentation if needed +- Description of the agent's purpose and capabilities diff --git a/docs/modules/usage/prompting/microagents-repo.md b/docs/modules/usage/prompting/microagents-repo.md index 0eecee7618..c32830ec0b 100644 --- a/docs/modules/usage/prompting/microagents-repo.md +++ b/docs/modules/usage/prompting/microagents-repo.md @@ -1,68 +1,117 @@ -# Repository Microagents +# Repository-specific Microagents ## Overview -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. -## Creating a Repository Micro-Agent +This section explains how to optimize OpenHands for your project. + +## Creating Repository Microagents 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. -### Repository Microagents Best Practices +You can enhance OpenHands' performance by adding custom microagents to your repository: -- **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. +1. For overall repository-specific instructions, create a `.openhands/microagents/repo.md` file +2. For reusable domain knowledge triggered by keywords, add multiple `.md` files to `.openhands/microagents/knowledge/` +3. For common workflows and tasks, create multiple `.md` files to `.openhands/microagents/tasks/` -### Steps to Create a Repository Microagent +Check out the [best practices](./microagents-syntax.md#markdown-content-best-practices) for formatting the content of your custom microagent. -#### 1. Plan the Repository Microagent -When creating a repository-specific micro-agent, we suggest including the following information: -- **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. +Keep in mind that loaded microagents take up space in the context window. It's crucial to strike a balance between the additional context provided by microagents and the instructions provided in the user's inputs. -#### 2. Create File +Note that you can use OpenHands to create new microagents. The public microagent [`add_agent`](https://github.com/All-Hands-AI/OpenHands/blob/main/microagents/knowledge/add_agent.md) is loaded to all OpenHands instance and can support you on this. -Create a file in your repository under `.openhands/microagents/` (Example: `.openhands/microagents/repo.md`) +## Types of Microagents -Update the file with the required frontmatter [according to the required format](./microagents-overview#microagent-format) -and the required specialized guidelines for your repository. +OpenHands supports three primary types of microagents, each with specific purposes and features to enhance agent performance: -### Example Repository Microagent +- [repository](#repository-microagents) +- [knowledge](#knowledge-microagents) +- [tasks](#tasks-microagents) + +The standard directory structure within a repository is: + +- One main `repo.md` file containing repository-specific instructions +- Additional `Knowledge` agents in `.openhands/microagents/knowledge/` directory +- Additional `Task` agents in `.openhands/microagents/tasks/` directory + +When processing the `.openhands/microagents/` directory, OpenHands will recursively scan all subfolders and process any `.md` files (except `README.md`) it finds. The system determines the microagent type based on the `type` field in the YAML frontmatter, not by the file's location. However, for organizational clarity, it's recommended to follow the standard directory structure. + +### Repository Microagents + +The `Repository` microagent is loaded specifically from `.openhands/microagents/repo.md` and serves as the main +repository-specific instruction file. This single file is automatically loaded whenever OpenHands works with that repository +without requiring any keyword matching or explicit call from the user. + +OpenHands does not support multiple `repo.md` files in different locations or multiple microagents with type `repo`. + +If you need to organize different types of repository information, the recommended approach is to use a single `repo.md` file with well-structured sections rather than trying to create multiple microagents with the type `repo`. + +The best practice is to include project-specific instructions, team practices, coding standards, and architectural guidelines that are relevant for **all** prompts in that repository. + +Example structure: ``` ---- -name: repo -type: repo -agent: CodeActAgent ---- - -Repository: MyProject -Description: A web application for task management - -Directory Structure: -- src/: Main application code -- tests/: Test files -- docs/: Documentation - -Setup: -- Run `npm install` to install dependencies -- Use `npm run dev` for development -- Run `npm test` for testing - -Guidelines: -- Follow ESLint configuration -- Write tests for all new features -- Use TypeScript for new code - -If adding a new component in src/components, always add appropriate unit tests in tests/components/. +your-repository/ +└── .openhands/ + └── microagents/ + └── repo.md # Repository-specific instructions ``` + +[See the example in the official OpenHands repository](https://github.com/All-Hands-AI/OpenHands/blob/main/.openhands/microagents/repo.md?plain=1) + +### Knowledge Microagents + +Knowledge microagents provide specialized domain expertise: + +- Recommended to be located in `.openhands/microagents/knowledge/` +- Triggered by specific keywords in conversations +- Contain expertise on tools, languages, frameworks, and common practices + +Use knowledge microagents to trigger additional context relevant to specific technologies, tools, or workflows. For example, mentioning "git" in your conversation will automatically trigger git-related expertise to help with Git operations. + +Examples structure: + +``` +your-repository/ +└── .openhands/ + └── microagents/ + └── knowledge/ + └── git.md + └── docker.md + └── python.md + └── ... + └── repo.md +``` + +You can find several real examples of `Knowledge` microagents in the [offical OpenHands repository](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge) + +### Tasks Microagents + +Task microagents guide users through interactive workflows: + +- Recommended to be located in `.openhands/microagents/tasks/` +- Provide step-by-step processes for common development tasks +- Accept inputs and adapt to different scenarios +- Ensure consistent outcomes for complex operations + +Task microagents are a convenient way to store multi-step processes you perform regularly. For instance, you can create a `update_pr_description.md` microagent to automatically generate better pull request descriptions based on code changes. + +Examples structure: + +``` +your-repository/ +└── .openhands/ + └── microagents/ + └── tasks/ + └── update_pr_description.md + └── address_pr_comments.md + └── get_test_to_pass.md + └── ... + └── knowledge/ + └── ... + └── repo.md +``` + +You can find several real examples of `Tasks` microagents in the [offical OpenHands repository](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/tasks) diff --git a/docs/modules/usage/prompting/microagents-syntax.md b/docs/modules/usage/prompting/microagents-syntax.md new file mode 100644 index 0000000000..a722cf5022 --- /dev/null +++ b/docs/modules/usage/prompting/microagents-syntax.md @@ -0,0 +1,128 @@ +# Microagents Syntax + +Microagents are defined using markdown files with YAML frontmatter that specify their behavior, triggers, and capabilities. + +Find below a comprehensive description of the frontmatter syntax and other details about how to use each type of microagent available at OpenHands. + +## Frontmatter Schema + +Every microagent requires a YAML frontmatter section at the beginning of the file, enclosed by triple dashes (`---`). The fields are: + +| Field | Description | Required | Used By | +| ---------- | -------------------------------------------------- | ------------------------ | ---------------- | +| `name` | Unique identifier for the microagent | Yes | All types | +| `type` | Type of microagent: `repo`, `knowledge`, or `task` | Yes | All types | +| `version` | Version number (Semantic versioning recommended) | Yes | All types | +| `agent` | The agent type (typically `CodeActAgent`) | Yes | All types | +| `author` | Creator of the microagent | No | All types | +| `triggers` | List of keywords that activate the microagent | Yes for knowledge agents | Knowledge agents | +| `inputs` | Defines required user inputs for task execution | Yes for task agents | Task agents | + +## Core Fields + +### `agent` + +**Purpose**: Specifies which agent implementation processes the microagent (typically `CodeActAgent`). + +- Defines a single agent responsible for processing the microagent +- Must be available in the OpenHands system (see the [agent hub](https://github.com/All-Hands-AI/OpenHands/tree/main/openhands/agenthub)) +- If the specified agent is not active, the microagent will not be used + +### `triggers` + +**Purpose**: Defines keywords that activate the `knowledge` microagent. + +**Example**: + +```yaml +triggers: + - kubernetes + - k8s + - docker + - security + - containers cluster +``` + +**Key points**: + +- Can include both single words and multi-word phrases +- Case-insensitive matching is typically used +- More specific triggers (like "docker compose") prevent false activations +- Multiple triggers increase the chance of activation in relevant contexts +- Unique triggers like "flarglebargle" can be used for testing or special functionality +- Triggers should be carefully chosen to avoid unwanted activations or conflicts with other microagents +- Common terms used in many conversations may cause the microagent to be activated too frequently + +When using multiple triggers, the microagent will be activated if any of the trigger words or phrases appear in the +conversation. + +### `inputs` + +**Purpose**: Defines parameters required from the user when a `task` microagent is activated. + +**Schema**: + +```yaml +inputs: + - name: INPUT_NAME # Used with {{ INPUT_NAME }} + description: 'Description of what this input is for' + required: true # Optional, defaults to true +``` + +**Key points**: + +- The `name` and `description` properties are required for each input +- The `required` property is optional and defaults to `true` +- Input values are referenced in the microagent body using double curly braces (e.g., `{{ INPUT_NAME }}`) +- All inputs defined will be collected from the user before the task microagent executes + +**Variable Usage**: Reference input values using double curly braces `{{ INPUT_NAME }}`. + +## Example Formats + +### Repository Microagent + +Repository microagents provide context and guidelines for a specific repository. + +- Located at: `.openhands/microagents/repo.md` +- Automatically loaded when working with the repository +- Only one per repository + +The `Repository` microagent is loaded specifically from `.openhands/microagents/repo.md` and serves as the main +repository-specific instruction file. This single file is automatically loaded whenever OpenHands works with that repository +without requiring any keyword matching or explicit call from the user. + +[See the example in the official OpenHands repository](https://github.com/All-Hands-AI/OpenHands/blob/main/.openhands/microagents/repo.md?plain=1) + +### Knowledge Microagent + +Provides specialized domain expertise triggered by keywords. + +You can find several real examples of `Knowledge` microagents in the [offical OpenHands repository](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge) + +### Task Microagent + +When explicitly asked by the user, will guide through interactive workflows with specific inputs. + +You can find several real examples of `Tasks` microagents in the [offical OpenHands repository](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/tasks) + +## Markdown Content Best Practices + +After the frontmatter, compose the microagent body using Markdown syntax. Examples of elements you can include are: + +- Clear, concise instructions outlining the microagent's purpose and responsibilities +- Specific guidelines and constraints the microagent should adhere to +- Relevant code snippets and practical examples to illustrate key points +- Step-by-step procedures for task agents, guiding users through workflows + +**Design Tips**: + +- Keep microagents focused with a clear purpose +- Provide specific guidelines rather than general advice +- Use distinctive triggers for knowledge agents +- Keep content concise to minimize context window usage +- Break large microagents into smaller, focused ones + +Aim for clarity, brevity, and practicality in your writing. Use formatting like bullet points, code blocks, and emphasis to enhance readability and comprehension. + +Remember that balancing microagents details with user input space is important for maintaining effective interactions. diff --git a/docs/sidebars.ts b/docs/sidebars.ts index e222e814c5..4823a00f10 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -1,7 +1,7 @@ -import type { SidebarsConfig } from "@docusaurus/plugin-content-docs"; +import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; const sidebars: SidebarsConfig = { - apiSidebar: [require("./modules/python/sidebar.json")], + apiSidebar: [require('./modules/python/sidebar.json')], docsSidebar: [ { type: 'doc', @@ -38,7 +38,7 @@ const sidebars: SidebarsConfig = { }, { type: 'doc', - label: 'Repository', + label: 'Repository-specific', id: 'usage/prompting/microagents-repo', }, { @@ -46,6 +46,11 @@ const sidebars: SidebarsConfig = { label: 'Public', id: 'usage/prompting/microagents-public', }, + { + type: 'doc', + label: 'Syntax', + id: 'usage/prompting/microagents-syntax', + }, ], }, ], diff --git a/microagents/knowledge/add_agent.md b/microagents/knowledge/add_agent.md index 52594c65ee..db71f3f0c5 100644 --- a/microagents/knowledge/add_agent.md +++ b/microagents/knowledge/add_agent.md @@ -4,17 +4,17 @@ type: knowledge version: 1.0.0 agent: CodeActAgent triggers: -- new agent -- new microagent -- create agent -- create an agent -- create microagent -- create a microagent -- add agent -- add an agent -- add microagent -- add a microagent -- microagent template + - new agent + - new microagent + - create agent + - create an agent + - create microagent + - create a microagent + - add agent + - add an agent + - add microagent + - add a microagent + - microagent template --- This agent helps create new microagents in the `.openhands/microagents` directory by providing guidance and templates. @@ -22,17 +22,20 @@ This agent helps create new microagents in the `.openhands/microagents` director Microagents are specialized prompts that provide context and capabilities for specific domains or tasks. They are activated by trigger words in the conversation and help the AI assistant understand what capabilities are available, how to use specific APIs or tools, what limitations exist, and how to handle common scenarios. When creating a new microagent: -* Create a markdown file in `.openhands/microagents/` with an appropriate name (e.g., `github.md`, `google_workspace.md`) -* Include YAML frontmatter with metadata (name, type, version, agent, triggers) -* type is by DEFAULT knowledge -* version is DEFAULT 1.0.0 -* agent is by DEFAULT CodeActAgent -* Document any credentials, environment variables, or API access needed -* Keep trigger words specific to avoid false activations -* Include error handling guidance and limitations -* Provide clear usage examples -* Keep the prompt focused and concise + +- Create a markdown file in `.openhands/microagents/` with an appropriate name (e.g., `github.md`, `google_workspace.md`) +- Include YAML frontmatter with metadata (name, type, version, agent, triggers) +- type is by DEFAULT knowledge +- version is DEFAULT 1.0.0 +- agent is by DEFAULT CodeActAgent +- Document any credentials, environment variables, or API access needed +- Keep trigger words specific to avoid false activations +- Include error handling guidance and limitations +- Provide clear usage examples +- Keep the prompt focused and concise For detailed information, see: -* [Microagents Overview](https://docs.all-hands.dev/modules/usage/prompting/microagents-overview) -* [Example GitHub Microagent](https://github.com/All-Hands-AI/OpenHands/blob/main/microagents/knowledge/github.md) + +- [Microagents Overview](https://docs.all-hands.dev/modules/usage/prompting/microagents-overview) +- [Microagents Syntax](https://docs.all-hands.dev/modules/usage/prompting/microagents-syntax) +- [Example GitHub Microagent](https://github.com/All-Hands-AI/OpenHands/blob/main/microagents/knowledge/github.md)