From c66b0e774ba4e651b677b49170b5df7ecf5dfaed Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Sun, 20 Sep 2026 15:55:28 +0200 Subject: [PATCH] docs: consolidate obsolete pages and label retained legacy references --- docs.json | 28 +- openhands/usage/about.mdx | 30 -- openhands/usage/agents.mdx | 9 +- openhands/usage/developers/debugging.mdx | 73 --- .../usage/developers/development-overview.mdx | 71 --- .../usage/developers/evaluation-harness.mdx | 9 +- .../usage/developers/websocket-connection.mdx | 9 +- openhands/usage/environment-variables.mdx | 26 +- openhands/usage/get-started/tutorials.mdx | 40 ++ openhands/usage/llms/custom-llm-configs.mdx | 10 +- .../usage/tips/prompting-best-practices.mdx | 2 +- overview/faqs.mdx | 2 +- overview/first-projects.mdx | 130 ----- sdk/arch/llm.mdx | 2 +- sdk/arch/sdk.mdx | 465 ------------------ sdk/getting-started.mdx | 2 +- 16 files changed, 110 insertions(+), 798 deletions(-) delete mode 100644 openhands/usage/about.mdx delete mode 100644 openhands/usage/developers/debugging.mdx delete mode 100644 openhands/usage/developers/development-overview.mdx delete mode 100644 overview/first-projects.mdx delete mode 100644 sdk/arch/sdk.mdx diff --git a/docs.json b/docs.json index 92058d474..e6097c29c 100644 --- a/docs.json +++ b/docs.json @@ -687,11 +687,11 @@ }, { "source": "/openhands/usage/how-to/debugging", - "destination": "/openhands/usage/developers/debugging" + "destination": "/openhands/usage/agent-canvas/development" }, { "source": "/openhands/usage/how-to/development-overview", - "destination": "/openhands/usage/developers/development-overview" + "destination": "/openhands/usage/agent-canvas/development" }, { "source": "/openhands/usage/how-to/evaluation-harness", @@ -755,7 +755,7 @@ }, { "source": "/openhands/usage/start-building", - "destination": "/overview/first-projects" + "destination": "/openhands/usage/get-started/tutorials" }, { "source": "/overview/key-features", @@ -868,6 +868,26 @@ { "source": "/openhands/usage/automations/examples", "destination": "/openhands/usage/automations/overview" + }, + { + "source": "/openhands/usage/about", + "destination": "/overview/introduction" + }, + { + "source": "/openhands/usage/developers/debugging", + "destination": "/openhands/usage/agent-canvas/development" + }, + { + "source": "/openhands/usage/developers/development-overview", + "destination": "/openhands/usage/agent-canvas/development" + }, + { + "source": "/overview/first-projects", + "destination": "/openhands/usage/get-started/tutorials" + }, + { + "source": "/sdk/arch/sdk", + "destination": "/sdk/arch/overview" } ] -} \ No newline at end of file +} diff --git a/openhands/usage/about.mdx b/openhands/usage/about.mdx deleted file mode 100644 index edf3e1c75..000000000 --- a/openhands/usage/about.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: About OpenHands ---- - -## Research Strategy - -Achieving full replication of production-grade applications with LLMs is a complex endeavor. Our strategy involves: - -- **Core Technical Research:** Focusing on foundational research to understand and improve the technical aspects of code generation and handling. -- **Task Planning:** Developing capabilities for bug detection, codebase management, and optimization. -- **Evaluation:** Establishing comprehensive evaluation metrics to better understand and improve our agents. - -## Default Agent - -Our default Agent is currently the [CodeActAgent](./agents), which is capable of generating code and handling files. - -## Built With - -OpenHands is built using a combination of powerful frameworks and libraries, providing a robust foundation for its -development. Here are the key technologies used in the project: - -![FastAPI](https://img.shields.io/badge/FastAPI-black?style=for-the-badge) ![uvicorn](https://img.shields.io/badge/uvicorn-black?style=for-the-badge) ![LiteLLM](https://img.shields.io/badge/LiteLLM-black?style=for-the-badge) ![Docker](https://img.shields.io/badge/Docker-black?style=for-the-badge) ![Ruff](https://img.shields.io/badge/Ruff-black?style=for-the-badge) ![MyPy](https://img.shields.io/badge/MyPy-black?style=for-the-badge) ![LlamaIndex](https://img.shields.io/badge/LlamaIndex-black?style=for-the-badge) ![React](https://img.shields.io/badge/React-black?style=for-the-badge) - -Please note that the selection of these technologies is in progress, and additional technologies may be added or -existing ones may be removed as the project evolves. We strive to adopt the most suitable and efficient tools to -enhance the capabilities of OpenHands. - -## License - -Distributed under MIT [License](https://github.com/OpenHands/OpenHands/blob/main/LICENSE). diff --git a/openhands/usage/agents.mdx b/openhands/usage/agents.mdx index f6ae2cd63..14febdf32 100644 --- a/openhands/usage/agents.mdx +++ b/openhands/usage/agents.mdx @@ -1,7 +1,14 @@ --- -title: Main Agent and Capabilities +title: Legacy CodeAct Agent +description: Archived documentation for the former OpenHands Python monorepo +noindex: true --- + +This page describes the historical CodeAct agent. For the current Software Agent SDK, see [Agent Architecture](/sdk/arch/agent). + + + ## CodeActAgent ### Description diff --git a/openhands/usage/developers/debugging.mdx b/openhands/usage/developers/debugging.mdx deleted file mode 100644 index b8a4ead3d..000000000 --- a/openhands/usage/developers/debugging.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Debugging ---- - -The following is intended as a primer on debugging OpenHands for Development purposes. - -## Server / VSCode - -The following `launch.json` will allow debugging the agent, controller and server elements, but not the sandbox (Which runs inside docker). It will ignore any changes inside the `workspace/` directory: - -``` -{ - "version": "0.2.0", - "configurations": [ - { - "name": "OpenHands CLI", - "type": "debugpy", - "request": "launch", - "module": "openhands.cli.main", - "justMyCode": false - }, - { - "name": "OpenHands WebApp", - "type": "debugpy", - "request": "launch", - "module": "uvicorn", - "args": [ - "openhands.server.listen:app", - "--reload", - "--reload-exclude", - "${workspaceFolder}/workspace", - "--port", - "3000" - ], - "justMyCode": false - } - ] -} -``` - -More specific debugging configurations which include more parameters may be specified: - -``` - ... - { - "name": "Debug CodeAct", - "type": "debugpy", - "request": "launch", - "module": "openhands.core.main", - "args": [ - "-t", - "Ask me what your task is.", - "-d", - "${workspaceFolder}/workspace", - "-c", - "CodeActAgent", - "-l", - "llm.o1", - "-n", - "prompts" - ], - "justMyCode": false - } - ... -``` - -Values in the snippet above can be updated such that: - - * *t*: the task - * *d*: the openhands workspace directory - * *c*: the agent - * *l*: the LLM config (pre-defined in config.toml) - * *n*: session name (e.g. eventstream name) diff --git a/openhands/usage/developers/development-overview.mdx b/openhands/usage/developers/development-overview.mdx deleted file mode 100644 index fb48ec774..000000000 --- a/openhands/usage/developers/development-overview.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Development Overview -description: This guide provides an overview of the key documentation resources available in the OpenHands repository. Whether you're looking to contribute, understand the architecture, or work on specific components, these resources will help you navigate the codebase effectively. ---- - -## Core Documentation - -### Project Fundamentals -- **Main Project Overview** (`/README.md`) - The primary entry point for understanding OpenHands, including features and basic setup instructions. - -- **Development Guide** (`/Development.md`) - Guide for developers working on OpenHands, including setup, requirements, and development workflows. - -- **Contributing Guidelines** (`/CONTRIBUTING.md`) - Essential information for contributors, covering code style, PR process, and contribution workflows. - -### Component Documentation - -#### Frontend -- **Frontend Application** (`/frontend/README.md`) - Complete guide for setting up and developing the React-based frontend application. - -#### Backend -- **Backend Implementation** (`/openhands/README.md`) - Detailed documentation of the Python backend implementation and architecture. - -- **Server Documentation** (`/openhands/server/README.md`) - Server implementation details, API documentation, and service architecture. - -- **Runtime Environment** (`/openhands/runtime/README.md`) - Documentation covering the runtime environment, execution model, and runtime configurations. - -#### Infrastructure -- **Container Documentation** (`/containers/README.md`) - Information about Docker containers, deployment strategies, and container management. - -### Testing and Evaluation -- **Unit Testing Guide** (`/tests/unit/README.md`) - Instructions for writing, running, and maintaining unit tests. - -- **Evaluation Framework** (`/evaluation/README.md`) - Documentation for the evaluation framework, benchmarks, and performance testing. - -### Advanced Features -- **Skills (formerly Microagents) Architecture** (`/skills/README.md`) - Detailed information about the skills architecture, implementation, and usage. - -### Documentation Standards -- **Documentation Style Guide** (`/docs/DOC_STYLE_GUIDE.md`) - Standards and guidelines for writing and maintaining project documentation. - -## Getting Started with Development - -If you're new to developing with OpenHands, we recommend following this sequence: - -1. Start with the main `README.md` to understand the project's purpose and features -2. Review the `CONTRIBUTING.md` guidelines if you plan to contribute -3. Follow the setup instructions in `Development.md` -4. Dive into specific component documentation based on your area of interest: - - Frontend developers should focus on `/frontend/README.md` - - Backend developers should start with `/openhands/README.md` - - Infrastructure work should begin with `/containers/README.md` - -## Documentation Updates - -When making changes to the codebase, please ensure that: -1. Relevant documentation is updated to reflect your changes -2. New features are documented in the appropriate README files -3. Any API changes are reflected in the server documentation -4. Documentation follows the style guide in `/docs/DOC_STYLE_GUIDE.md` diff --git a/openhands/usage/developers/evaluation-harness.mdx b/openhands/usage/developers/evaluation-harness.mdx index 2e227e425..e68233f94 100644 --- a/openhands/usage/developers/evaluation-harness.mdx +++ b/openhands/usage/developers/evaluation-harness.mdx @@ -1,7 +1,14 @@ --- -title: Evaluation Harness +title: Legacy Evaluation Harness +description: Archived documentation for the former OpenHands Python monorepo +noindex: true --- + +This page describes the former Python monorepo evaluation harness. For current SDK-based evaluations, use the [OpenHands benchmarks repository](https://github.com/OpenHands/benchmarks). Its setup and benchmark-specific runners replace the workflow below; there is no equivalent generic harness-authoring guide in this documentation yet. + + + This guide provides an overview of how to integrate your own evaluation benchmark into the OpenHands framework. ## Setup Environment and LLM Configuration diff --git a/openhands/usage/developers/websocket-connection.mdx b/openhands/usage/developers/websocket-connection.mdx index 38c877e6b..282d6f1db 100644 --- a/openhands/usage/developers/websocket-connection.mdx +++ b/openhands/usage/developers/websocket-connection.mdx @@ -1,7 +1,14 @@ --- -title: WebSocket Connection +title: Legacy WebSocket Connection +description: Archived documentation for the former OpenHands Python monorepo +noindex: true --- + +This page describes the former Socket.IO protocol. Agent Canvas uses a native WebSocket connection instead. See [Canvas Architecture](/openhands/usage/agent-canvas/architecture) and [SDK Events](/sdk/arch/events) for current architecture and event concepts. Those pages are not a replacement wire-protocol reference; do not use the Socket.IO examples below with Canvas. + + + This guide explains how to connect to the OpenHands WebSocket API to receive real-time events and send actions to the agent. ## Overview diff --git a/openhands/usage/environment-variables.mdx b/openhands/usage/environment-variables.mdx index 4b8f50a53..2d335115e 100644 --- a/openhands/usage/environment-variables.mdx +++ b/openhands/usage/environment-variables.mdx @@ -1,8 +1,14 @@ --- -title: Environment Variables Reference -description: Complete reference of all environment variables supported by OpenHands +title: Archived Environment Variables Reference +description: Archived documentation for the former OpenHands Python monorepo +noindex: true --- + +This reference was assembled for the former Python monorepo and is retained for older deployments. It is not a complete or verified reference for current Canvas or SDK releases. For current settings, see [Canvas Development](/openhands/usage/agent-canvas/development#docker-conversation-runtime-settings) and [Agent Server Architecture](/sdk/arch/agent-server). + + + This page provides a reference of environment variables that can be used to configure OpenHands. Environment variables provide an alternative to TOML configuration files and are particularly useful for containerized deployments, CI/CD pipelines, and cloud environments. ## Environment Variable Naming Convention @@ -152,20 +158,8 @@ These variables correspond to the `[security]` section in `config.toml`: ### Docker Conversation Runtime (Canvas) -When running Agent Canvas locally via the `dev-safe.mjs` launcher, Canvas can forward conversation-runtime settings to its bundled Agent Server. This enables `OH_CONVERSATION_RUNTIME=docker`, which runs each conversation in an isolated Docker container instead of the default local process runtime. - -Canvas forwards these settings only when the operator explicitly sets them. Unset values remain absent so Agent Server defaults stay authoritative. - -| Environment Variable | Type | Default | Description | -|---------------------|------|---------|-------------| -| `OH_CONVERSATION_RUNTIME` | string | unset | Conversation runtime type. Set to `docker` to run conversations in Docker containers. | -| `OH_CONVERSATION_IMAGE` | string | unset | Docker image to use for conversation containers. | -| `OH_CONVERSATION_CONTAINER_MEMORY` | string | unset | Memory limit for conversation containers (e.g., `2g`). | -| `OH_CONVERSATION_CONTAINER_CPUS` | string | unset | CPU limit for conversation containers. | -| `OH_CONVERSATION_CONTAINER_PIDS_LIMIT` | string | unset | PID limit for conversation containers. | -| `OH_CONVERSATION_CONTAINER_STARTUP_TIMEOUT` | string | unset | Startup timeout for conversation containers (seconds). | - -These variables are specific to Canvas's `dev-safe.mjs` launcher and are forwarded to the bundled Agent Server process. Docker provisioning and setting interpretation are handled by Agent Server. +The current `OH_CONVERSATION_*` settings are documented in +[Canvas Development](/openhands/usage/agent-canvas/development#docker-conversation-runtime-settings). ### Remote Runtime | Environment Variable | Type | Default | Description | diff --git a/openhands/usage/get-started/tutorials.mdx b/openhands/usage/get-started/tutorials.mdx index 8e14fd527..fc3c72c8c 100644 --- a/openhands/usage/get-started/tutorials.mdx +++ b/openhands/usage/get-started/tutorials.mdx @@ -5,6 +5,46 @@ description: Centralized hub for OpenHands tutorials and examples Welcome to the OpenHands tutorial library. These tutorials show you how to use OpenHands for common development tasks, from testing to feature development. Each tutorial includes example prompts, expected workflows, and tips for success. +## First Projects + +After [setting up OpenHands](/overview/quickstart), start with a small task and +iterate. These prompts work as starting points without relying on a particular +interface or repository integration. + +### Hello World + +> Write a bash script hello.sh that prints "hello world!" and run it. + +Then refine it: + +> Modify hello.sh so it accepts a name as the first argument and defaults to "world". Test both cases. + +### Build a Small App + +> Build a frontend-only TODO app in React. Store its state in localStorage. + +Once the basics work: + +> Allow adding an optional due date to each task. Add tests for creating and updating due dates. + +### Work in an Existing Repository + +Give the agent the repository context and a focused goal: + +> Add a GitHub Actions workflow that runs this repository's existing lint command. + +For a small refactor: + +> Split build_and_deploy_widgets in widget.php into build_widgets and deploy_widgets. Preserve the behavior and run the relevant tests. + +For a bug fix: + +> The hello function crashes on an empty string. Write a test that reproduces the bug, then fix the code so it passes. + +Review each change before expanding the task. Include file names, expected +behavior, and examples in your prompts. See [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) +for more guidance. + ## Categories Overview | Category | Best For | Complexity | diff --git a/openhands/usage/llms/custom-llm-configs.mdx b/openhands/usage/llms/custom-llm-configs.mdx index 297d36129..eea5f1ae7 100644 --- a/openhands/usage/llms/custom-llm-configs.mdx +++ b/openhands/usage/llms/custom-llm-configs.mdx @@ -1,8 +1,14 @@ --- -title: Custom LLM Configurations -description: OpenHands supports defining multiple named LLM configurations in your `config.toml` file. This feature allows you to use different LLM configurations for different purposes, such as using a cheaper model for tasks that don't require high-quality responses, or using different models with different parameters for specific agents. +title: Legacy Custom LLM Configurations +description: Archived documentation for the former OpenHands Python monorepo +noindex: true --- + +This page describes named TOML configurations in the former Python monorepo. For current configuration, see [Canvas LLM Profiles](/openhands/usage/agent-canvas/llm-profiles) or the [SDK LLM Profile Store](/sdk/guides/llm-profile-store). + + + ## How It Works Named LLM configurations are defined in the `config.toml` file using sections that start with `llm.`. For example: diff --git a/openhands/usage/tips/prompting-best-practices.mdx b/openhands/usage/tips/prompting-best-practices.mdx index f873bb321..5ce30905b 100644 --- a/openhands/usage/tips/prompting-best-practices.mdx +++ b/openhands/usage/tips/prompting-best-practices.mdx @@ -35,4 +35,4 @@ Good prompts are: The more precise and informative your prompt, the better OpenHands can assist you. -See [First Projects](/overview/first-projects) for more examples of helpful prompts. +See [First Projects](/openhands/usage/get-started/tutorials) for more examples of helpful prompts. diff --git a/overview/faqs.mdx b/overview/faqs.mdx index babc563c8..12514da54 100644 --- a/overview/faqs.mdx +++ b/overview/faqs.mdx @@ -12,7 +12,7 @@ description: Frequently asked questions about OpenHands. [Bitbucket](/openhands/usage/cloud/bitbucket-installation), and [Slack](/openhands/usage/cloud/slack-installation) integrations. 2. **Run on your own**: If you prefer to run it on your own hardware, follow our [Getting Started guide](/openhands/usage/run-openhands/local-setup). -3. **First steps**: Read over the [first projects guidelines](/overview/first-projects) and +3. **First steps**: Read over the [first projects guidelines](/openhands/usage/get-started/tutorials) and [prompting best practices](/openhands/usage/tips/prompting-best-practices) to learn the basics. ### Can I use OpenHands for production workloads? diff --git a/overview/first-projects.mdx b/overview/first-projects.mdx deleted file mode 100644 index 56d61075f..000000000 --- a/overview/first-projects.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: First Projects -description: So you've [run OpenHands](/overview/quickstart). Now what? ---- - -Like any tool, it works best when you know how to use it effectively. Whether you're experimenting with a small -script or making changes in a large codebase, this guide will show how to apply OpenHands in different scenarios. - -Let’s walk through a natural progression of using OpenHands: -- Try a simple prompt. -- Build a project from scratch. -- Add features to existing code. -- Refactor code. -- Debug and fix bugs. - -## First Steps: Hello World - -Start with a small task to get familiar with how OpenHands responds to prompts. - -Click `New Conversation` and try prompting: -> Write a bash script hello.sh that prints "hello world!" - -OpenHands will generate script, set the correct permissions, and even run it for you. - -Now try making small changes: - -> Modify hello.sh so that it accepts a name as the first argument, but defaults to "world". - -You can experiment in any language. For example: - -> Convert hello.sh to a Ruby script, and run it. - - - Start small and iterate. This helps you understand how OpenHands interprets and responds to different prompts. - - -## Build Something from Scratch - -Agents excel at "greenfield" tasks, where they don’t need context about existing code. -Begin with a simple task and iterate from there. Be specific about what you want and the tech stack. - -Click `New Conversation` and give it a clear goal: - -> Build a frontend-only TODO app in React. All state should be stored in localStorage. - -Once the basics are working, build on it just like you would in a real project: - -> Allow adding an optional due date to each task. - -You can also ask OpenHands to help with version control: - -> Commit the changes and push them to a new branch called "feature/due-dates". - - - Break your goals into small, manageable tasks.. Keep pushing your changes often. This makes it easier to recover - if something goes off track. - - -## Expand Existing Code - -Want to add new functionality to an existing repo? OpenHands can do that too. - - -If you're running OpenHands on your own, first add a -[GitHub token](/openhands/usage/settings/integrations-settings#github-setup), -[GitLab token](/openhands/usage/settings/integrations-settings#gitlab-setup) or -[Bitbucket token](/openhands/usage/settings/integrations-settings#bitbucket-setup). - - -Choose your repository and branch via `Open Repository`, and press `Launch`. - -Examples of adding new functionality: - -> Add a GitHub action that lints the code in this repository. - -> Modify ./backend/api/routes.js to add a new route that returns a list of all tasks. - -> Add a new React component to the ./frontend/components directory to display a list of Widgets. -> It should use the existing Widget component. - - - OpenHands can explore the codebase, but giving it context upfront makes it faster and less expensive. - - -## Refactor Code - -OpenHands does great at refactoring code in small chunks. Rather than rearchitecting the entire codebase, it's more -effective in focused refactoring tasks. Start by launching a conversation with -your repo and branch. Then guide it: - -> Rename all the single-letter variables in ./app.go. - -> Split the `build_and_deploy_widgets` function into two functions, `build_widgets` and `deploy_widgets` in widget.php. - -> Break ./api/routes.js into separate files for each route. - - - Focus on small, meaningful improvements instead of full rewrites. - - -## Debug and Fix Bugs - -OpenHands can help debug and fix issues, but it’s most effective when you’ve narrowed things down. - -Give it a clear description of the problem and the file(s) involved: - -> The email field in the `/subscribe` endpoint is rejecting .io domains. Fix this. - -> The `search_widgets` function in ./app.py is doing a case-sensitive search. Make it case-insensitive. - -For bug fixing, test-driven development can be really useful. You can ask OpenHands to write a new test and iterate -until the bug is fixed: - -> The `hello` function crashes on the empty string. Write a test that reproduces this bug, then fix the code so it passes. - - - Be as specific as possible. Include expected behavior, file names, and examples to speed things up. - - -## Using OpenHands Effectively - -OpenHands can assist with nearly any coding task, but it takes some practice to get the best results. -Keep these tips in mind: -* Keep your tasks small. -* Be clear and specific. -* Provide relevant context. -* Commit and push frequently. - -See [Prompting Best Practices](/openhands/usage/tips/prompting-best-practices) for more tips on how to get the most -out of OpenHands. diff --git a/sdk/arch/llm.mdx b/sdk/arch/llm.mdx index 66feaf460..9e13d5121 100644 --- a/sdk/arch/llm.mdx +++ b/sdk/arch/llm.mdx @@ -300,7 +300,7 @@ verbatim to SDK applications because both layers wrap the same | Moonshot | [/openhands/usage/llms/moonshot](/openhands/usage/llms/moonshot) | | LiteLLM proxy | [/openhands/usage/llms/litellm-proxy](/openhands/usage/llms/litellm-proxy) | | Local LLMs (Ollama, SGLang, vLLM, LM Studio) | [/openhands/usage/llms/local-llms](/openhands/usage/llms/local-llms) | -| Custom LLM configurations | [/openhands/usage/llms/custom-llm-configs](/openhands/usage/llms/custom-llm-configs) | +| Saved SDK LLM profiles | [LLM Profile Store](/sdk/guides/llm-profile-store) | When you follow any of those guides while building with the SDK, create an `LLM` object using the documented parameters (for example, API keys, base URLs, diff --git a/sdk/arch/sdk.mdx b/sdk/arch/sdk.mdx deleted file mode 100644 index a237f36a8..000000000 --- a/sdk/arch/sdk.mdx +++ /dev/null @@ -1,465 +0,0 @@ ---- -title: SDK Package -description: Core framework components for building agents - the reasoning loop, state management, and extensibility system. ---- - -The SDK package (`openhands.sdk`) is the heart of the OpenHands Software Agent SDK. It provides the core framework for building agents locally or embedding them in applications. - -**Source**: [`sdk/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk) - -## Purpose - -The SDK package handles: -- **Agent reasoning loop**: How agents process messages and make decisions -- **State management**: Conversation lifecycle and persistence -- **LLM integration**: Provider-agnostic language model access -- **Tool system**: Typed actions and observations -- **Workspace abstraction**: Where code executes -- **Extensibility**: Skills, condensers, MCP, security - -## Core Components - -```mermaid -graph TB - Conv[Conversation
Lifecycle Manager] --> Agent[Agent
Reasoning Loop] - - Agent --> LLM[LLM
Language Model] - Agent --> Tools[Tool System
Capabilities] - Agent --> Micro[Skills
Behavior Modules] - Agent --> Cond[Condenser
Memory Manager] - - Tools --> Workspace[Workspace
Execution] - - Conv --> Events[Events
Communication] - Tools --> MCP[MCP
External Tools] - Workspace --> Security[Security
Validation] - - style Conv fill:#e1f5fe - style Agent fill:#f3e5f5 - style LLM fill:#e8f5e8 - style Tools fill:#fff3e0 - style Workspace fill:#fce4ec -``` - -### 1. Conversation - State & Lifecycle - -**What it does**: Manages the entire conversation lifecycle and state. - -**Key responsibilities**: -- Maintains conversation state (immutable) -- Handles message flow between user and agent -- Manages turn-taking and async execution -- Persists and restores conversation state -- Emits events for monitoring - -**Design decisions**: -- **Immutable state**: Each operation returns a new Conversation instance -- **Serializable**: Can be saved to disk or database and restored -- **Async-first**: Built for streaming and concurrent execution - -**When to use directly**: When you need fine-grained control over conversation state, want to implement custom persistence, or need to pause/resume conversations. - -**Example use cases**: -- Saving conversation to database after each turn -- Implementing undo/redo functionality -- Building multi-session chatbots -- Time-travel debugging - -**Learn more**: -- Guide: [Conversation Persistence](/sdk/guides/convo-persistence) -- Guide: [Pause and Resume](/sdk/guides/convo-pause-and-resume) -- Source: [`conversation/`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation) - ---- - -### 2. Agent - The Reasoning Loop - -**What it does**: The core reasoning engine that processes messages and decides what to do. - -**Key responsibilities**: -- Receives messages and current state -- Consults LLM to reason about next action -- Validates and executes tool calls -- Processes observations and loops until completion -- Integrates with skills for specialized behavior - -**Design decisions**: -- **Stateless**: Agent doesn't hold state, operates on Conversation -- **Extensible**: Behavior can be modified via skills -- **Provider-agnostic**: Works with any LLM through unified interface - -**The reasoning loop**: -1. Receive message from Conversation -2. Add message to context -3. Consult LLM with full conversation history -4. If LLM returns tool call → validate and execute tool -5. If tool returns observation → add to context, go to step 3 -6. If LLM returns response → done, return to user - -**When to customize**: When you need specialized reasoning strategies, want to implement custom agent behaviors, or need to control the execution flow. - -**Example use cases**: -- Planning agents that break tasks into steps -- Code review agents with specific checks -- Agents with domain-specific reasoning patterns - -**Learn more**: -- Guide: [Custom Agents](/sdk/guides/agent-custom) -- Guide: [Agent Stuck Detector](/sdk/guides/agent-stuck-detector) -- Source: [`agent/`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/agent) - ---- - -### 3. LLM - Language Model Integration - -**What it does**: Provides a provider-agnostic interface to language models. - -**Key responsibilities**: -- Abstracts different LLM providers (OpenAI, Anthropic, etc.) -- Handles message formatting and conversion -- Manages streaming responses -- Supports tool calling and reasoning modes -- Handles retries and error recovery - -**Design decisions**: -- **Provider-agnostic**: Same API works with any provider -- **Streaming-first**: Built for real-time responses -- **Type-safe**: Pydantic models for all messages -- **Extensible**: Easy to add new providers - -**Why provider-agnostic?** You can switch between OpenAI, Anthropic, local models, etc. without changing your agent code. This is crucial for: -- Cost optimization (switch to cheaper models) -- Testing with different models -- Avoiding vendor lock-in -- Supporting customer choice - -**When to customize**: When you need to add a new LLM provider, implement custom retries, or modify message formatting. - -**Example use cases**: -- Routing requests to different models based on complexity -- Implementing custom caching strategies -- Adding observability hooks - -**Learn more**: -- Guide: [LLM Registry](/sdk/guides/llm-registry) -- Guide: [LLM Routing](/sdk/guides/llm-routing) -- Guide: [Reasoning and Tool Use](/sdk/guides/llm-reasoning) -- Source: [`llm/`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/llm) - ---- - -### 4. Tool System - Typed Capabilities - -**What it does**: Defines what agents can do through a typed action/observation pattern. - -**Key responsibilities**: -- Defines tool schemas (inputs and outputs) -- Validates actions before execution -- Executes tools and returns typed observations -- Generates JSON schemas for LLM tool calling -- Registers tools with the agent - -**Design decisions**: -- **Action/Observation pattern**: Tools are defined as type-safe input/output pairs -- **Schema generation**: Pydantic models auto-generate JSON schemas -- **Executor pattern**: Separation of tool definition and execution -- **Composable**: Tools can call other tools - -**The three components**: -1. **Action**: Input schema (what the tool accepts) -2. **Observation**: Output schema (what the tool returns) -3. **ToolExecutor**: Logic that transforms Action → Observation - -**Why this pattern?** -- Type safety catches errors early -- LLMs get accurate schemas for tool calling -- Tools are testable in isolation -- Easy to compose tools - -**When to customize**: When you need domain-specific capabilities not covered by built-in tools. - -**Example use cases**: -- Database query tools -- API integration tools -- Custom file format parsers -- Domain-specific calculators - -**Learn more**: -- Guide: [Custom Tools](/sdk/guides/custom-tools) -- Source: [`tools/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-tools/openhands/tools) - ---- - -### 5. Workspace - Execution Abstraction - -**What it does**: Abstracts *where* code executes (local, Docker, remote). - -**Key responsibilities**: -- Provides unified interface for code execution -- Handles file operations across environments -- Manages working directories -- Supports different isolation levels - -**Design decisions**: -- **Abstract interface**: LocalWorkspace in SDK, advanced types in workspace package -- **Environment-agnostic**: Code works the same locally or remotely -- **Lazy initialization**: Workspace setup happens on first use - -**Why abstract?** You can develop locally with LocalWorkspace, then deploy with DockerWorkspace or RemoteAPIWorkspace without changing agent code. - -**When to use directly**: Rarely - usually configured when creating an agent. Use advanced workspaces for production. - -**Learn more**: -- Architecture: [Workspace Architecture](/sdk/arch/workspace) -- Guides: [Remote Agent Server](/sdk/guides/agent-server/overview) -- Source: [`workspace/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/workspace) - ---- - -### 6. Events - Component Communication - -**What it does**: Enables observability and debugging through event emissions. - -**Key responsibilities**: -- Defines event types (messages, actions, observations, errors) -- Emitted by Conversation, Agent, Tools -- Enables logging, debugging, and monitoring -- Supports custom event handlers - -**Design decisions**: -- **Immutable**: Events are snapshots, not mutable objects -- **Serializable**: Can be logged, stored, replayed -- **Type-safe**: Pydantic models for all events - -**Why events?** They provide a timeline of what happened during agent execution. Essential for: -- Debugging agent behavior -- Understanding decision-making -- Building observability dashboards -- Implementing custom logging - -**When to use**: When building monitoring systems, debugging tools, or need to track agent behavior. - -**Learn more**: -- Guide: [Metrics and Observability](/sdk/guides/metrics) -- Source: [`event/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/event) - ---- - -### 7. Condenser - Memory Management - -**What it does**: Compresses conversation history when it gets too long. - -**Key responsibilities**: -- Monitors conversation length -- Summarizes older messages -- Preserves important context -- Keeps conversation within token limits - -**Design decisions**: -- **Pluggable**: Different condensing strategies -- **Automatic**: Triggered when context gets large -- **Preserves semantics**: Important information retained - -**Why needed?** LLMs have token limits. Long conversations would eventually exceed context windows. Condensers keep conversations running indefinitely while staying within limits. - -**When to customize**: When you need domain-specific summarization strategies or want to control what gets preserved. - -**Example strategies**: -- Summarize old messages -- Keep only last N turns -- Preserve task-related messages - -**Learn more**: -- Guide: [Context Condenser](/sdk/guides/context-condenser) -- Source: [`condenser/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/context/condenser) - ---- - -### 8. MCP - Model Context Protocol - -**What it does**: Integrates external tool servers via Model Context Protocol. - -**Key responsibilities**: -- Connects to MCP-compatible tool servers -- Translates MCP tools to SDK tool format -- Manages server lifecycle -- Handles server communication - -**Design decisions**: -- **Standard protocol**: Uses MCP specification -- **Transparent integration**: MCP tools look like regular tools to agents -- **Process management**: Handles server startup/shutdown - -**Why MCP?** It lets you use external tools without writing custom SDK integrations. Many tools (databases, APIs, services) provide MCP servers. - -**When to use**: When you need tools that: -- Already have MCP servers (fetch, filesystem, etc.) -- Are too complex to rewrite as SDK tools -- Need to run in separate processes -- Are provided by third parties - -**Learn more**: -- Guide: [MCP Integration](/sdk/guides/mcp) -- Spec: [Model Context Protocol](https://modelcontextprotocol.io/) -- Source: [`mcp/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/mcp) - ---- - -### 9. Skills (formerly Microagents) - Behavior Modules - -**What it does**: Specialized modules that modify agent behavior for specific tasks. - -**Key responsibilities**: -- Provide domain-specific instructions -- Modify system prompts -- Guide agent decision-making -- Compose to create specialized agents - -**Design decisions**: -- **Composable**: Multiple skills can work together -- **Declarative**: Defined as configuration, not code -- **Reusable**: Share skills across agents - -**Why skills?** Instead of hard-coding behaviors, skills let you compose agent personalities and capabilities. Like "plugins" for agent behavior. - -**Example skills**: -- GitHub operations (issue creation, PRs) -- Code review guidelines -- Documentation style enforcement -- Project-specific conventions - -**When to use**: When you need agents with specialized knowledge or behavior patterns that apply to specific domains or tasks. - -**Learn more**: -- Guide: [Agent Skills & Context](/sdk/guides/skill) -- Source: [`skills/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/context/skills) - ---- - -### 10. Security - Validation & Sandboxing - -**What it does**: Validates inputs and enforces security constraints. - -**Key responsibilities**: -- Input validation -- Command sanitization -- Path traversal prevention -- Resource limits - -**Design decisions**: -- **Defense in depth**: Multiple validation layers -- **Fail-safe**: Rejects suspicious inputs by default -- **Configurable**: Adjust security levels as needed - -**Why needed?** Agents execute arbitrary code and file operations. Security prevents: -- Malicious prompts escaping sandboxes -- Path traversal attacks -- Resource exhaustion -- Unintended system access - -**When to customize**: When you need domain-specific validation rules or want to adjust security policies. - -**Learn more**: -- Guide: [Security and Secrets](/sdk/guides/security) -- Source: [`security/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/security) - ---- - -## How Components Work Together - -### Example: User asks agent to create a file - -``` -1. User → Conversation: "Create a file called hello.txt with 'Hello World'" - -2. Conversation → Agent: New message event - -3. Agent → LLM: Full conversation history + available tools - -4. LLM → Agent: Tool call for FileEditorTool.create() - -5. Agent → Tool System: Validate FileEditorAction - -6. Tool System → Tool Executor: Execute action - -7. Tool Executor → Workspace: Create file (local/docker/remote) - -8. Workspace → Tool Executor: Success - -9. Tool Executor → Tool System: FileEditorObservation (success=true) - -10. Tool System → Agent: Observation - -11. Agent → LLM: Updated history with observation - -12. LLM → Agent: "File created successfully" - -13. Agent → Conversation: Done, final response - -14. Conversation → User: "File created successfully" -``` - -Throughout this flow: -- **Events** are emitted for observability -- **Condenser** may trigger if history gets long -- **Skills** influence LLM's decision-making -- **Security** validates file paths and operations -- **MCP** could provide additional tools if configured - -## Design Patterns - -### Immutability - -All core objects are immutable. Operations return new instances: - -```python -conversation = Conversation(...) -new_conversation = conversation.add_message(message) -# conversation is unchanged, new_conversation has the message -``` - -**Why?** Makes debugging easier, enables time-travel, ensures serializability. - -### Composition Over Inheritance - -Agents are composed from: -- LLM provider -- Tool list -- Skill list -- Condenser strategy -- Security policy - -You don't subclass Agent - you configure it. - -**Why?** More flexible, easier to test, enables runtime configuration. - -### Type Safety - -Everything uses Pydantic models: -- Messages, actions, observations are typed -- Validation happens automatically -- Schemas generate from types - -**Why?** Catches errors early, provides IDE support, self-documenting. - -## Next Steps - -### For Usage Examples - -- [Getting Started](/sdk/getting-started) - Build your first agent -- [Custom Tools](/sdk/guides/custom-tools) - Extend capabilities -- [LLM Configuration](/sdk/guides/llm-registry) - Configure providers -- [Conversation Management](/sdk/guides/convo-persistence) - State handling - -### For Related Architecture - -- [Tool System](/sdk/arch/tool-system) - Built-in tool implementations -- [Workspace Architecture](/sdk/arch/workspace) - Execution environments -- [Agent Server Architecture](/sdk/arch/agent-server) - Remote execution - -### For Implementation Details - -- [`openhands-sdk/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk) - SDK source code -- [`openhands-tools/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-tools) - Tools source code -- [`openhands-workspace/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace) - Workspace source code -- [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples) - Working examples diff --git a/sdk/getting-started.mdx b/sdk/getting-started.mdx index b1a160521..d035284dd 100644 --- a/sdk/getting-started.mdx +++ b/sdk/getting-started.mdx @@ -203,7 +203,7 @@ ls examples/01_standalone_sdk/ ### Explore Documentation -- **[SDK Architecture](/sdk/arch/sdk)** - Deep dive into components +- **[SDK Architecture](/sdk/arch/overview)** - Deep dive into components - **[Tool System](/sdk/arch/tool-system)** - Available tools - **[Workspace Architecture](/sdk/arch/workspace)** - Execution environments - **[LLM Configuration](/sdk/arch/llm)** - Deep dive into language model configuration