Demystifying Microagents Syntax in OpenHands

OpenHands leverages microagents to enrich interactions by injecting domain expertise and guiding users through custom workflows. But how do we define these microagents? The magic lies in the Markdown files wrapped with a YAML frontmatter section that drives their behavior, triggers, and capabilities. In this guide, we’ll walk through the core elements of microagent syntax and best practices for creating them.

---

📝 The YAML Frontmatter: Your Microagent Blueprint

Every microagent kicks off with a YAML frontmatter block, enclosed by triple dashes (—) at both the beginning and the end. This section acts as a metadata container that instructs OpenHands how to process the file.

Key Fields in the Frontmatter

Below are the essential fields you need when defining a microagent:

• name
  • Unique identifier for your microagent.
  • (Required for all types)
• type
  • Specifies the kind of microagent: can be repo, knowledge, or task.
  • (Required for all types)
• version
  • Represents the version number of the microagent (Semantic versioning is recommended).
  • (Required for all types)
• agent
  • Indicates which agent implementation will process the microagent, typically something like CodeActAgent.
  • This must be available in the OpenHands system for the microagent to function.
  • (Required for all types)
• author
  • Optional field to denote the creator of the microagent.
• triggers
  • A list of keywords that activate a knowledge microagent.
  • For example: triggers: - kubernetes - k8s - docker - security - containers cluster • These keywords can be a mix of single words or phrases, and matching is case-insensitive.
  • (Required for knowledge agents)
• inputs
  • Specifically used in task microagents to define the parameters needed from the user before execution.
  • Each input must have a name, a description, and an optional required flag (defaults to true).
  • An example schema looks like this: inputs: - name: INPUT_NAME description: 'Description of what this input is for' required: true • Input values are then referenced in the microagent’s body using double curly braces, like {{ INPUT_NAME }}.
  • (Required for task agents)

---

📂 Organizing Your Microagents

The frontmatter doesn’t just set the tone for behavior—it also plays a role in how microagents are organized and triggered:

• Repository Microagents:
  • Located in .openhands/microagents/repo.md.
  • They provide repository-specific guidelines and are loaded automatically without needing trigger words.
• Knowledge Microagents:
  • Stored in the knowledge/ directory, for instance, .openhands/microagents/knowledge/git.md.
  • Activated automatically when conversation keywords match any of the defined triggers.
  • Use clear and distinctive triggers to avoid unwanted activations.
• Task Microagents:
  • Housed in .openhands/microagents/tasks/.
  • These microagents guide you through interactive workflows and require explicit invocation.
  • They prompt the user for inputs according to the schema defined in the frontmatter.

---

🔍 Best Practices for Crafting Effective Microagents

While it’s crucial to include all required fields in your YAML frontmatter, consider these design tips to ensure your microagents are practical and efficient:

• Specificity Is Key:
  Provide clear and concise instructions in your microagent body. Focus on a narrowly defined purpose rather than general advice.
• Balanced Content:
  Keep your content focused—while detailed enough to be useful, too much text can overload the context window. Break large microagents into smaller, focused ones if necessary.
• Distinctive Triggers:
  Choose unique and less common trigger phrases for knowledge microagents. This helps prevent frequent false activations, especially when common terms appear in everyday conversation.
• Clear Input Handling:
  For task microagents, define each input with an explanatory description, and always reference these inputs in your body using the double curly brace format (e.g., {{ INPUT_NAME }}).
• Guidelines and Examples:
  Enhance usage clarity by including code snippets, step-by-step directives, and practical examples that illustrate how the microagent should be used.

---

🛠 Practical Markdown Example

Here is a sample frontmatter for a task microagent designed to update pull request descriptions:

---
name: update_pr_description
type: task
version: "1.0.0"
agent: CodeActAgent
author: "Your Name"
inputs:
  - name: PR_ID
    description: 'The identifier of the pull request'
    required: true
  - name: CHANGE_SUMMARY
    description: 'A summary of the code changes'
    required: true
---

After this YAML section, the microagent body can then provide the guidelines using Markdown syntax, including numbered steps or bullet points to help users complete their tasks.

---

📚 Wrapping Up

Understanding and effectively utilizing the microagent syntax in OpenHands is essential to tailor your development environment. By correctly setting up the YAML frontmatter and following markdown best practices, you ensure that every microagent—whether it enhances repository-specific context, provides domain knowledge, or guides through complex workflows—is integrated seamlessly for optimal performance.

Embrace the power of microagents to customize and elevate your coding experience with both clarity and precision!

Happy coding, and may your microagents always trigger at just the right moment!