diff --git a/.openhands/microagents/repo.md b/.openhands/microagents/sdk-guidelines.md similarity index 84% rename from .openhands/microagents/repo.md rename to .openhands/microagents/sdk-guidelines.md index 8056b0e5..f1d22510 100644 --- a/.openhands/microagents/repo.md +++ b/.openhands/microagents/sdk-guidelines.md @@ -1,43 +1,29 @@ -# OpenHands Documentation Repository +# OpenHands SDK Documentation Guidelines -This repository contains the official documentation for OpenHands, including guides for the Agent SDK and the client OpenHands applications. The documentation is deployed using Mintlify and features an automated code synchronization system. - -## Repository Purpose - -- **OpenHands Docs**: User guides, tutorials, and reference documentation for OpenHands core application -- **Agent SDK Docs**: Developer documentation for the OpenHands Agent SDK +These instructions are ONLY for modifying the documentation associated with the agent SDK which mainly lives under the +sdk folder. ## Repository Structure +Applicable files when modifying the agent SDK documentation: + ``` docs/ -├── .openhands/microagents/ # Repository microagents (like this file) +├── .openhands/microagents/sdk-guidelines.md # Guidelines for changing SDK documentation (this file) ├── .github/ │ ├── scripts/ │ │ └── sync_code_blocks.py # Code synchronization script │ └── workflows/ # CI/CD workflows -├── openhands/ # OpenHands core documentation -│ └── usage/ -│ ├── microagents/ # Microagent documentation -│ ├── cloud/ # Cloud service docs -│ ├── settings/ # Settings documentation -│ └── ... ├── sdk/ # Agent SDK documentation │ ├── guides/ # SDK tutorials and guides │ └── arch/ # Architecture documentation └── docs.json # Mintlify navigation configuration ``` -### Key Files - -- **`docs.json`**: Mintlify configuration including navigation structure, theme, and redirects -- **Microagent docs**: `openhands/usage/microagents/microagents-*.mdx` -- **Sync script**: `.github/scripts/sync_code_blocks.py` -- **This microagent**: `.openhands/microagents/repo.md` +## Agent SDK Documentation System Overview -## Documentation System Overview - -The documentation follows a synchronized approach where code examples are automatically kept in sync with actual example files in the agent-sdk repository. +The documentation follows a synchronized approach where code examples are automatically kept in sync with actual +example files in the agent-sdk repository. ## Automatic Code Synchronization @@ -79,11 +65,12 @@ pattern = r'```python[^\n]*\s+(examples/[^\s]+\.py)\n(.*?)```' - Captures file path: `examples/01_standalone_sdk/02_custom_tools.py` - Captures code content between opening and closing ``` - ## MDX Documentation Format ### Standard Structure -Documentation is deployed with Mintlify from GitHub. The files follow this pattern (see `docs/sdk/guides/custom-tools.mdx` and `docs/sdk/guides/mcp.mdx` as reference): + +Documentation is deployed with Mintlify from GitHub. The files follow this pattern +(see `docs/sdk/guides/custom-tools.mdx` and `docs/sdk/guides/mcp.mdx` as reference): 1. **Frontmatter** - YAML metadata with title and description 2. **Introduction** - Brief overview of the feature @@ -206,7 +193,6 @@ This example is available on GitHub: [examples/01_standalone_sdk/02_custom_tools 4. **Consistency**: Follow existing patterns - Use same icon/expandable syntax - Include "Running the Example" bash block - - Add component with GitHub link - Structure sections similarly to other guides 5. **Testing**: Before committing documentation @@ -265,7 +251,7 @@ You can check https://www.mintlify.com/docs for documentation on what our doc si - **File**: `.github/workflows/sync-agent-sdk-openapi.yml` - **Purpose**: Syncs OpenAPI specifications for API documentation -## Notes for Contributors +## Notes - For agent-sdk examples, ensure the file path in code blocks is correct - For short agent-sdk examples, you don't need `expandable` in example file diff --git a/openapi/agent-sdk.json b/openapi/agent-sdk.json index e499decb..62aa00b8 100644 --- a/openapi/agent-sdk.json +++ b/openapi/agent-sdk.json @@ -2015,7 +2015,7 @@ "description": "Optional AgentContext to initialize the agent with specific context.", "examples": [ { - "microagents": [ + "skills": [ { "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.", "name": "repo.md", @@ -2100,32 +2100,13 @@ }, "AgentContext-Output": { "properties": { - "microagents": { + "skills": { "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/KnowledgeMicroagent" - }, - { - "$ref": "#/components/schemas/RepoMicroagent" - }, - { - "$ref": "#/components/schemas/TaskMicroagent" - } - ], - "title": "BaseMicroagent", - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__context__microagents__microagent__KnowledgeMicroagent-Output__1": "#/components/schemas/KnowledgeMicroagent", - "openhands__sdk__context__microagents__microagent__RepoMicroagent-Output__1": "#/components/schemas/RepoMicroagent", - "openhands__sdk__context__microagents__microagent__TaskMicroagent-Output__1": "#/components/schemas/TaskMicroagent" - } - } + "$ref": "#/components/schemas/Skill" }, "type": "array", - "title": "Microagents", - "description": "List of available microagents that can extend the user's input." + "title": "Skills", + "description": "List of available skills that can extend the user's input." }, "system_message_suffix": { "anyOf": [ @@ -2154,7 +2135,7 @@ }, "type": "object", "title": "AgentContext", - "description": "Central structure for managing prompt extension.\n\nAgentContext unifies all the contextual inputs that shape how the system\nextends and interprets user prompts. It combines both static environment\ndetails and dynamic, user-activated extensions from microagents.\n\nSpecifically, it provides:\n- **Repository context / Repo Microagents**: Information about the active codebase,\n branches, and repo-specific instructions contributed by repo microagents.\n- **Runtime context**: Current execution environment (hosts, working\n directory, secrets, date, etc.).\n- **Conversation instructions**: Optional task- or channel-specific rules\n that constrain or guide the agent\u2019s behavior across the session.\n- **Knowledge Microagents**: Extensible components that can be triggered by user input\n to inject knowledge or domain-specific guidance.\n\nTogether, these elements make AgentContext the primary container responsible\nfor assembling, formatting, and injecting all prompt-relevant context into\nLLM interactions." + "description": "Central structure for managing prompt extension.\n\nAgentContext unifies all the contextual inputs that shape how the system\nextends and interprets user prompts. It combines both static environment\ndetails and dynamic, user-activated extensions from skills.\n\nSpecifically, it provides:\n- **Repository context / Repo Skills**: Information about the active codebase,\n branches, and repo-specific instructions contributed by repo skills.\n- **Runtime context**: Current execution environment (hosts, working\n directory, secrets, date, etc.).\n- **Conversation instructions**: Optional task- or channel-specific rules\n that constrain or guide the agent\u2019s behavior across the session.\n- **Knowledge Skills**: Extensible components that can be triggered by user input\n to inject knowledge or domain-specific guidance.\n\nTogether, these elements make AgentContext the primary container responsible\nfor assembling, formatting, and injecting all prompt-relevant context into\nLLM interactions." }, "AgentErrorEvent": { "properties": { @@ -3076,13 +3057,13 @@ "confirmation_policy": { "$ref": "#/components/schemas/ConfirmationPolicyBase" }, - "activated_knowledge_microagents": { + "activated_knowledge_skills": { "items": { "type": "string" }, "type": "array", - "title": "Activated Knowledge Microagents", - "description": "List of activated knowledge microagents name" + "title": "Activated Knowledge Skills", + "description": "List of activated knowledge skills name" }, "stats": { "$ref": "#/components/schemas/ConversationStats-Output", @@ -3829,62 +3810,30 @@ "description" ], "title": "InputMetadata", - "description": "Metadata for task microagent inputs." + "description": "Metadata for task skill inputs." }, - "KnowledgeMicroagent": { + "KeywordTrigger": { "properties": { - "kind": { - "type": "string", - "const": "KnowledgeMicroagent", - "title": "Kind", - "default": "KnowledgeMicroagent" - }, - "name": { - "type": "string", - "title": "Name" - }, - "content": { - "type": "string", - "title": "Content" - }, - "source": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Source", - "description": "The source path or identifier of the microagent. When it is None, it is treated as a programmatically defined microagent." - }, "type": { "type": "string", - "enum": [ - "knowledge", - "repo", - "task" - ], + "const": "keyword", "title": "Type", - "default": "knowledge" + "default": "keyword" }, - "triggers": { + "keywords": { "items": { "type": "string" }, "type": "array", - "title": "Triggers", - "description": "List of triggers for the microagent" + "title": "Keywords" } }, "type": "object", "required": [ - "name", - "content" + "keywords" ], - "title": "KnowledgeMicroagent", - "description": "Knowledge micro-agents provide specialized expertise that's triggered by keywords\nin conversations.\n\nThey help with:\n- Language best practices\n- Framework guidelines\n- Common patterns\n- Tool usage" + "title": "KeywordTrigger", + "description": "Trigger for keyword-based skills.\n\nThese skills are activated when specific keywords appear in the user's query." }, "LLM": { "properties": { @@ -4622,13 +4571,13 @@ "$ref": "#/components/schemas/Message", "description": "The exact LLM message for this message event" }, - "activated_microagents": { + "activated_skills": { "items": { "type": "string" }, "type": "array", - "title": "Activated Microagents", - "description": "List of activated microagent name" + "title": "Activated Skills", + "description": "List of activated skill name" }, "extended_content": { "items": { @@ -5074,66 +5023,6 @@ "title": "RemoteWorkspace", "description": "Remote Workspace Implementation." }, - "RepoMicroagent": { - "properties": { - "kind": { - "type": "string", - "const": "RepoMicroagent", - "title": "Kind", - "default": "RepoMicroagent" - }, - "name": { - "type": "string", - "title": "Name" - }, - "content": { - "type": "string", - "title": "Content" - }, - "source": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Source", - "description": "The source path or identifier of the microagent. When it is None, it is treated as a programmatically defined microagent." - }, - "type": { - "type": "string", - "enum": [ - "knowledge", - "repo", - "task" - ], - "title": "Type", - "default": "repo" - }, - "mcp_tools": { - "anyOf": [ - { - "additionalProperties": true, - "type": "object" - }, - { - "type": "null" - } - ], - "title": "Mcp Tools", - "description": "MCP tools configuration for the microagent. It should conform to the MCPConfig schema: https://gofastmcp.com/clients/client#configuration-format" - } - }, - "type": "object", - "required": [ - "name", - "content" - ], - "title": "RepoMicroagent", - "description": "Microagent specialized for repository-specific knowledge and guidelines.\n\nRepoMicroagents are loaded from `.openhands/microagents/repo.md` files within\nrepositories and contain private, repository-specific instructions that are\nautomatically loaded when\nworking with that repository. They are ideal for:\n - Repository-specific guidelines\n - Team practices and conventions\n - Project-specific workflows\n - Custom documentation references" - }, "ResponseLatency": { "properties": { "model": { @@ -5293,6 +5182,84 @@ "title": "SetConfirmationPolicyRequest", "description": "Payload to set confirmation policy for a conversation." }, + "Skill": { + "properties": { + "name": { + "type": "string", + "title": "Name" + }, + "content": { + "type": "string", + "title": "Content" + }, + "trigger": { + "anyOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/KeywordTrigger" + }, + { + "$ref": "#/components/schemas/TaskTrigger" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "keyword": "#/components/schemas/KeywordTrigger", + "task": "#/components/schemas/TaskTrigger" + } + } + }, + { + "type": "null" + } + ], + "title": "Trigger" + }, + "source": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Source", + "description": "The source path or identifier of the skill. When it is None, it is treated as a programmatically defined skill." + }, + "mcp_tools": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Mcp Tools", + "description": "MCP tools configuration for the skill (repo skills only). It should conform to the MCPConfig schema: https://gofastmcp.com/clients/client#configuration-format" + }, + "inputs": { + "items": { + "$ref": "#/components/schemas/InputMetadata" + }, + "type": "array", + "title": "Inputs", + "description": "Input metadata for the skill (task skills only)" + } + }, + "type": "object", + "required": [ + "name", + "content", + "trigger" + ], + "title": "Skill", + "description": "A skill provides specialized knowledge or functionality.\n\nSkills use triggers to determine when they should be activated:\n- None: Always active, for repository-specific guidelines\n- KeywordTrigger: Activated when keywords appear in user messages\n- TaskTrigger: Activated for specific tasks, may require user input" + }, "StartConversationRequest": { "properties": { "agent": { @@ -5522,69 +5489,6 @@ ], "title": "TaskItem" }, - "TaskMicroagent": { - "properties": { - "kind": { - "type": "string", - "const": "TaskMicroagent", - "title": "Kind", - "default": "TaskMicroagent" - }, - "name": { - "type": "string", - "title": "Name" - }, - "content": { - "type": "string", - "title": "Content" - }, - "source": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Source", - "description": "The source path or identifier of the microagent. When it is None, it is treated as a programmatically defined microagent." - }, - "type": { - "type": "string", - "enum": [ - "knowledge", - "repo", - "task" - ], - "title": "Type", - "default": "task" - }, - "triggers": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Triggers", - "description": "List of triggers for the microagent" - }, - "inputs": { - "items": { - "$ref": "#/components/schemas/InputMetadata" - }, - "type": "array", - "title": "Inputs", - "description": "Input metadata for the microagent. Only exists for task microagents" - } - }, - "type": "object", - "required": [ - "name", - "content" - ], - "title": "TaskMicroagent", - "description": "TaskMicroagent is a special type of KnowledgeMicroagent that requires user input.\n\nThese microagents are triggered by a special format: \"/{agent_name}\"\nand will prompt the user for any required inputs before proceeding." - }, "TaskTrackerAction": { "properties": { "kind": { @@ -5651,6 +5555,29 @@ "title": "TaskTrackerObservation", "description": "This data class represents the result of a task tracking operation." }, + "TaskTrigger": { + "properties": { + "type": { + "type": "string", + "const": "task", + "title": "Type", + "default": "task" + }, + "triggers": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Triggers" + } + }, + "type": "object", + "required": [ + "triggers" + ], + "title": "TaskTrigger", + "description": "Trigger for task-specific skills.\n\nThese skills are activated for specific task types and can modify prompts." + }, "TextContent": { "properties": { "cache_prompt": { @@ -6173,28 +6100,6 @@ }, "title": "CondenserBase" }, - "BaseMicroagent": { - "oneOf": [ - { - "$ref": "#/components/schemas/KnowledgeMicroagent" - }, - { - "$ref": "#/components/schemas/RepoMicroagent" - }, - { - "$ref": "#/components/schemas/TaskMicroagent" - } - ], - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__context__microagents__microagent__KnowledgeMicroagent-Input__1": "#/components/schemas/KnowledgeMicroagent", - "openhands__sdk__context__microagents__microagent__RepoMicroagent-Input__1": "#/components/schemas/RepoMicroagent", - "openhands__sdk__context__microagents__microagent__TaskMicroagent-Input__1": "#/components/schemas/TaskMicroagent" - } - }, - "title": "BaseMicroagent" - }, "BaseWorkspace": { "oneOf": [ {