` + ``` + ** + ``` + `
` + params): + `
` + > return [cls(name=”finish”, …, executor=FinishExecutor())] + +Complex tool with initialization parameters: +: class TerminalTool(ToolDefinition[TerminalAction, + : TerminalObservation]): + @classmethod + def create(cls, conv_state, + `
` + ``` + ** + ``` + `
` + params): + `
` + > executor = TerminalExecutor( + > : working_dir=conv_state.workspace.working_dir, + > `
` + > ``` + > ** + > ``` + > `
` + > params, + `
` + > ) + > return [cls(name=”terminal”, …, executor=executor)] + + +#### Properties + +- `action_type`: type[[Action](#class-action)] +- `annotations`: [ToolAnnotations](#class-toolannotations) | None +- `description`: str +- `executor`: Annotated[[ToolExecutor](#class-toolexecutor) | None, SkipJsonSchema()] +- `meta`: dict[str, Any] | None +- `model_config`: ClassVar[ConfigDict] = (configuration object) + Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. +- `name`: ClassVar[str] = '' +- `observation_type`: type[[Observation](#class-observation)] | None +- `title`: str + +#### Methods + +#### action_from_arguments() + +Create an action from parsed arguments. + +This method can be overridden by subclasses to provide custom logic +for creating actions from arguments (e.g., for MCP tools). + +* Parameters: + `arguments` – The parsed arguments from the tool call. +* Returns: + The action instance created from the arguments. + +#### as_executable() + +Return this tool as an ExecutableTool, ensuring it has an executor. + +This method eliminates the need for runtime None checks by guaranteeing +that the returned tool has a non-None executor. + +* Returns: + This tool instance, typed as ExecutableTool. +* Raises: + `NotImplementedError` – If the tool has no executor. + +#### abstractmethod classmethod create() + +Create a sequence of Tool instances. + +This method must be implemented by all subclasses to provide custom +initialization logic, typically initializing the executor with parameters +from conv_state and other optional parameters. + +* Parameters: + args** – Variable positional arguments (typically conv_state as first arg). + kwargs* – Optional parameters for tool initialization. +* Returns: + A sequence of Tool instances. Even single tools are returned as a sequence + to provide a consistent interface and eliminate union return types. + +#### classmethod resolve_kind() + +Resolve a kind string to its corresponding tool class. + +* Parameters: + `kind` – The name of the tool class to resolve +* Returns: + The tool class corresponding to the kind +* Raises: + `ValueError` – If the kind is unknown + +#### set_executor() + +Create a new Tool instance with the given executor. + +#### to_mcp_tool() + +Convert a Tool to an MCP tool definition. + +Allow overriding input/output schemas (usually by subclasses). + +* Parameters: + * `input_schema` – Optionally override the input schema. + * `output_schema` – Optionally override the output schema. + +#### to_openai_tool() + +Convert a Tool to an OpenAI tool. + +* Parameters: + * `add_security_risk_prediction` – Whether to add a security_risk field + to the action schema for LLM to predict. This is useful for + tools that may have safety risks, so the LLM can reason about + the risk level before calling the tool. + * `action_type` – Optionally override the action_type to use for the schema. + This is useful for MCPTool to use a dynamically created action type + based on the tool’s input schema. + +#### NOTE +Summary field is always added to the schema for transparency and +explainability of agent actions. + +#### to_responses_tool() + +Convert a Tool to a Responses API function tool (LiteLLM typed). + +For Responses API, function tools expect top-level keys: +(JSON configuration object) + +* Parameters: + * `add_security_risk_prediction` – Whether to add a security_risk field + * `action_type` – Optional override for the action type + +#### NOTE +Summary field is always added to the schema for transparency and +explainability of agent actions. + +### class ToolExecutor + +Bases: `ABC`, `Generic` + +Executor function type for a Tool. + +#### Methods + +#### close() + +Close the executor and clean up resources. + +Default implementation does nothing. Subclasses should override +this method to perform cleanup (e.g., closing connections, +terminating processes, etc.). + +### openhands.sdk.utils +Source: https://docs.openhands.dev/sdk/api-reference/openhands.sdk.utils.md + +Utility functions for the OpenHands SDK. + +### deprecated() + +Return a decorator that deprecates a callable with explicit metadata. + +Use this helper when you can annotate a function, method, or property with +@deprecated(…). It transparently forwards to `deprecation.deprecated()` +while filling in the SDK’s current version metadata unless custom values are +supplied. + +### maybe_truncate() + +Truncate the middle of content if it exceeds the specified length. + +Keeps the head and tail of the content to preserve context at both ends. +Optionally saves the full content to a file for later investigation. + +* Parameters: + * `content` – The text content to potentially truncate + * `truncate_after` – Maximum length before truncation. If None, no truncation occurs + * `truncate_notice` – Notice to insert in the middle when content is truncated + * `save_dir` – Working directory to save full content file in + * `tool_prefix` – Prefix for the saved file (e.g., “bash”, “browser”, “editor”) +* Returns: + Original content if under limit, or truncated content with head and tail + preserved and reference to saved file if applicable + +### sanitize_openhands_mentions() + +Sanitize @OpenHands mentions in text to prevent self-mention loops. + +This function inserts a zero-width joiner (ZWJ) after the @ symbol in +@OpenHands mentions, making them non-clickable in GitHub comments while +preserving readability. The original case of the mention is preserved. + +* Parameters: + `text` – The text to sanitize +* Returns: + Text with sanitized @OpenHands mentions (e.g., “@OpenHands” -> “@OpenHands”) + +### Examples + +```pycon +>>> sanitize_openhands_mentions("Thanks @OpenHands for the help!") +'Thanks @u200dOpenHands for the help!' +>>> sanitize_openhands_mentions("Check @openhands and @OPENHANDS") +'Check @u200dopenhands and @u200dOPENHANDS' +>>> sanitize_openhands_mentions("No mention here") +'No mention here' +``` + +### sanitized_env() + +Return a copy of env with sanitized values. + +PyInstaller-based binaries rewrite `LD_LIBRARY_PATH` so their vendored +libraries win. This function restores the original value so that subprocess +will not use them. + +### warn_deprecated() + +Emit a deprecation warning for dynamic access to a legacy feature. + +Prefer this helper when a decorator is not practical—e.g. attribute accessors, +data migrations, or other runtime paths that must conditionally warn. Provide +explicit version metadata so the SDK reports consistent messages and upgrades +to `deprecation.UnsupportedWarning` after the removal threshold. + +### openhands.sdk.workspace +Source: https://docs.openhands.dev/sdk/api-reference/openhands.sdk.workspace.md + +### class BaseWorkspace + +Bases: `DiscriminatedUnionMixin`, `ABC` + +Abstract base class for workspace implementations. + +Workspaces provide a sandboxed environment where agents can execute commands, +read/write files, and perform other operations. All workspace implementations +support the context manager protocol for safe resource management. + +#### Example + +```pycon +>>> with workspace: +... result = workspace.execute_command("echo 'hello'") +... content = workspace.read_file("example.txt") +``` + + +#### Properties + +- `working_dir`: Annotated[str, BeforeValidator(func=_convert_path_to_str, json_schema_input_type=PydanticUndefined), FieldInfo(annotation=NoneType, required=True, description='The working directory for agent operations and tool execution. Accepts both string paths and Path objects. Path objects are automatically converted to strings.')] + +#### Methods + +#### abstractmethod execute_command() + +Execute a bash command on the system. + +* Parameters: + * `command` – The bash command to execute + * `cwd` – Working directory for the command (optional) + * `timeout` – Timeout in seconds (defaults to 30.0) +* Returns: + Result containing stdout, stderr, exit_code, and other + : metadata +* Return type: + [CommandResult](#class-commandresult) +* Raises: + `Exception` – If command execution fails + +#### abstractmethod file_download() + +Download a file from the system. + +* Parameters: + * `source_path` – Path to the source file on the system + * `destination_path` – Path where the file should be downloaded +* Returns: + Result containing success status and metadata +* Return type: + [FileOperationResult](#class-fileoperationresult) +* Raises: + `Exception` – If file download fails + +#### abstractmethod file_upload() + +Upload a file to the system. + +* Parameters: + * `source_path` – Path to the source file + * `destination_path` – Path where the file should be uploaded +* Returns: + Result containing success status and metadata +* Return type: + [FileOperationResult](#class-fileoperationresult) +* Raises: + `Exception` – If file upload fails + +#### abstractmethod git_changes() + +Get the git changes for the repository at the path given. + +* Parameters: + `path` – Path to the git repository +* Returns: + List of changes +* Return type: + list[GitChange] +* Raises: + `Exception` – If path is not a git repository or getting changes failed + +#### abstractmethod git_diff() + +Get the git diff for the file at the path given. + +* Parameters: + `path` – Path to the file +* Returns: + Git diff +* Return type: + GitDiff +* Raises: + `Exception` – If path is not a git repository or getting diff failed + +#### model_config = (configuration object) + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### pause() + +Pause the workspace to conserve resources. + +For local workspaces, this is a no-op. +For container-based workspaces, this pauses the container. + +* Raises: + `NotImplementedError` – If the workspace type does not support pausing. + +#### resume() + +Resume a paused workspace. + +For local workspaces, this is a no-op. +For container-based workspaces, this resumes the container. + +* Raises: + `NotImplementedError` – If the workspace type does not support resuming. + +### class CommandResult + +Bases: `BaseModel` + +Result of executing a command in the workspace. + + +#### Properties + +- `command`: str +- `exit_code`: int +- `stderr`: str +- `stdout`: str +- `timeout_occurred`: bool + +#### Methods + +#### model_config = (configuration object) + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +### class FileOperationResult + +Bases: `BaseModel` + +Result of a file upload or download operation. + + +#### Properties + +- `destination_path`: str +- `error`: str | None +- `file_size`: int | None +- `source_path`: str +- `success`: bool + +#### Methods + +#### model_config = (configuration object) + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +### class LocalWorkspace + +Bases: [`BaseWorkspace`](#class-baseworkspace) + +Local workspace implementation that operates on the host filesystem. + +LocalWorkspace provides direct access to the local filesystem and command execution +environment. It’s suitable for development and testing scenarios where the agent +should operate directly on the host system. + +#### Example + +```pycon +>>> workspace = LocalWorkspace(working_dir="/path/to/project") +>>> with workspace: +... result = workspace.execute_command("ls -la") +... content = workspace.read_file("README.md") +``` + +#### Methods + +#### __init__() + +Create a new model by parsing and validating input data from keyword arguments. + +Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be +validated to form a valid model. + +self is explicitly positional-only to allow self as a field name. + +#### execute_command() + +Execute a bash command locally. + +Uses the shared shell execution utility to run commands with proper +timeout handling, output streaming, and error management. + +* Parameters: + * `command` – The bash command to execute + * `cwd` – Working directory (optional) + * `timeout` – Timeout in seconds +* Returns: + Result with stdout, stderr, exit_code, command, and + : timeout_occurred +* Return type: + [CommandResult](#class-commandresult) + +#### file_download() + +Download (copy) a file locally. + +For local systems, file download is implemented as a file copy operation +using shutil.copy2 to preserve metadata. + +* Parameters: + * `source_path` – Path to the source file + * `destination_path` – Path where the file should be copied +* Returns: + Result with success status and file information +* Return type: + [FileOperationResult](#class-fileoperationresult) + +#### file_upload() + +Upload (copy) a file locally. + +For local systems, file upload is implemented as a file copy operation +using shutil.copy2 to preserve metadata. + +* Parameters: + * `source_path` – Path to the source file + * `destination_path` – Path where the file should be copied +* Returns: + Result with success status and file information +* Return type: + [FileOperationResult](#class-fileoperationresult) + +#### git_changes() + +Get the git changes for the repository at the path given. + +* Parameters: + `path` – Path to the git repository +* Returns: + List of changes +* Return type: + list[GitChange] +* Raises: + `Exception` – If path is not a git repository or getting changes failed + +#### git_diff() + +Get the git diff for the file at the path given. + +* Parameters: + `path` – Path to the file +* Returns: + Git diff +* Return type: + GitDiff +* Raises: + `Exception` – If path is not a git repository or getting diff failed + +#### model_config = (configuration object) + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### pause() + +Pause the workspace (no-op for local workspaces). + +Local workspaces have nothing to pause since they operate directly +on the host filesystem. + +#### resume() + +Resume the workspace (no-op for local workspaces). + +Local workspaces have nothing to resume since they operate directly +on the host filesystem. + +### class RemoteWorkspace + +Bases: `RemoteWorkspaceMixin`, [`BaseWorkspace`](#class-baseworkspace) + +Remote workspace implementation that connects to an OpenHands agent server. + +RemoteWorkspace provides access to a sandboxed environment running on a remote +OpenHands agent server. This is the recommended approach for production deployments +as it provides better isolation and security. + +#### Example + +```pycon +>>> workspace = RemoteWorkspace( +... host="https://agent-server.example.com", +... working_dir="/workspace" +... ) +>>> with workspace: +... result = workspace.execute_command("ls -la") +... content = workspace.read_file("README.md") +``` + + +#### Properties + +- `alive`: bool + Check if the remote workspace is alive by querying the health endpoint. + * Returns: + True if the health endpoint returns a successful response, False otherwise. +- `client`: Client + +#### Methods + +#### execute_command() + +Execute a bash command on the remote system. + +This method starts a bash command via the remote agent server API, +then polls for the output until the command completes. + +* Parameters: + * `command` – The bash command to execute + * `cwd` – Working directory (optional) + * `timeout` – Timeout in seconds +* Returns: + Result with stdout, stderr, exit_code, and other metadata +* Return type: + [CommandResult](#class-commandresult) + +#### file_download() + +Download a file from the remote system. + +Requests the file from the remote system via HTTP API and saves it locally. + +* Parameters: + * `source_path` – Path to the source file on remote system + * `destination_path` – Path where the file should be saved locally +* Returns: + Result with success status and metadata +* Return type: + [FileOperationResult](#class-fileoperationresult) + +#### file_upload() + +Upload a file to the remote system. + +Reads the local file and sends it to the remote system via HTTP API. + +* Parameters: + * `source_path` – Path to the local source file + * `destination_path` – Path where the file should be uploaded on remote system +* Returns: + Result with success status and metadata +* Return type: + [FileOperationResult](#class-fileoperationresult) + +#### git_changes() + +Get the git changes for the repository at the path given. + +* Parameters: + `path` – Path to the git repository +* Returns: + List of changes +* Return type: + list[GitChange] +* Raises: + `Exception` – If path is not a git repository or getting changes failed + +#### git_diff() + +Get the git diff for the file at the path given. + +* Parameters: + `path` – Path to the file +* Returns: + Git diff +* Return type: + GitDiff +* Raises: + `Exception` – If path is not a git repository or getting diff failed + +#### model_config = (configuration object) + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### model_post_init() + +Override this method to perform additional initialization after __init__ and model_construct. +This is useful if you want to do some validation that requires the entire model to be initialized. + +#### reset_client() + +Reset the HTTP client to force re-initialization. + +This is useful when connection parameters (host, api_key) have changed +and the client needs to be recreated with new values. + +### class Workspace + +### class Workspace + +Bases: `object` + +Factory entrypoint that returns a LocalWorkspace or RemoteWorkspace. + +Usage: +: - Workspace(working_dir=…) -> LocalWorkspace + - Workspace(working_dir=…, host=”http://…”) -> RemoteWorkspace + +### Agent +Source: https://docs.openhands.dev/sdk/arch/agent.md + +The **Agent** component implements the core reasoning-action loop that drives autonomous task execution. It orchestrates LLM queries, tool execution, and context management through a stateless, event-driven architecture. + +**Source:** [`openhands-sdk/openhands/sdk/agent/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/agent) + +## Core Responsibilities + +The Agent system has four primary responsibilities: + +1. **Reasoning-Action Loop** - Query LLM to generate next actions based on conversation history +2. **Tool Orchestration** - Select and execute tools, handle results and errors +3. **Context Management** - Apply [skills](/sdk/guides/skill), manage conversation history via [condensers](/sdk/guides/context-condenser) +4. **Security Validation** - Analyze proposed actions for safety before execution via [security analyzer](/sdk/guides/security) + +## Architecture + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 20, "rankSpacing": 50}} }%% +flowchart TB + subgraph Input[" "] + Events["Event History"] + Context["Agent Context
Skills + Prompts"] + end + + subgraph Core["Agent Core"] + Condense["Condenser
History compression"] + Reason["LLM Query
Generate actions"] + Security["Security Analyzer
Risk assessment"] + end + + subgraph Execution[" "] + Tools["Tool Executor
Action → Observation"] + Results["Observation Events"] + end + + Events --> Condense + Context -.->|Skills| Reason + Condense --> Reason + Reason --> Security + Security --> Tools + Tools --> Results + Results -.->|Feedback| Events + + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px + + class Reason primary + class Condense,Security secondary + class Tools tertiary +``` + +### Key Components + +| Component | Purpose | Design | +|-----------|---------|--------| +| **[`Agent`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/agent/agent.py)** | Main implementation | Stateless reasoning-action loop executor | +| **[`AgentBase`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/agent/base.py)** | Abstract base class | Defines agent interface and initialization | +| **[`AgentContext`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/agent_context.py)** | Context container | Manages skills, prompts, and metadata | +| **[`Condenser`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/)** | History compression | Reduces context when token limits approached | +| **[`SecurityAnalyzer`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/)** | Safety validation | Evaluates action risk before execution | + +## Reasoning-Action Loop + +The agent operates through a **single-step execution model** where each `step()` call processes one reasoning cycle: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 10, "rankSpacing": 10}} }%% +flowchart TB + Start["step() called"] + Pending{"Pending
actions?"} + ExecutePending["Execute pending actions"] + + HasCondenser{"Has
condenser?"} + Condense["Call condenser.condense()"] + CondenseResult{"Result
type?"} + EmitCondensation["Emit Condensation event"] + UseView["Use View events"] + UseRaw["Use raw events"] + + Query["Query LLM with messages"] + ContextExceeded{"Context
window
exceeded?"} + EmitRequest["Emit CondensationRequest"] + + Parse{"Response
type?"} + CreateActions["Create ActionEvents"] + CreateMessage["Create MessageEvent"] + + Confirmation{"Need
confirmation?"} + SetWaiting["Set WAITING_FOR_CONFIRMATION"] + + Execute["Execute actions"] + Observe["Create ObservationEvents"] + + Return["Return"] + + Start --> Pending + Pending -->|Yes| ExecutePending --> Return + Pending -->|No| HasCondenser + + HasCondenser -->|Yes| Condense + HasCondenser -->|No| UseRaw + Condense --> CondenseResult + CondenseResult -->|Condensation| EmitCondensation --> Return + CondenseResult -->|View| UseView --> Query + UseRaw --> Query + + Query --> ContextExceeded + ContextExceeded -->|Yes| EmitRequest --> Return + ContextExceeded -->|No| Parse + + Parse -->|Tool calls| CreateActions + Parse -->|Message| CreateMessage --> Return + + CreateActions --> Confirmation + Confirmation -->|Yes| SetWaiting --> Return + Confirmation -->|No| Execute + + Execute --> Observe + Observe --> Return + + style Query fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Condense fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Confirmation fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Step Execution Flow:** + +1. **Pending Actions:** If actions awaiting confirmation exist, execute them and return +2. **Condensation:** If condenser exists: + - Call `condenser.condense()` with current event view + - If returns `View`: use condensed events for LLM query (continue in same step) + - If returns `Condensation`: emit event and return (will be processed next step) +3. **LLM Query:** Query LLM with messages from event history + - If context window exceeded: emit `CondensationRequest` and return +4. **Response Parsing:** Parse LLM response into events + - Tool calls → create `ActionEvent`(s) + - Text message → create `MessageEvent` and return +5. **Confirmation Check:** If actions need user approval: + - Set conversation status to `WAITING_FOR_CONFIRMATION` and return +6. **Action Execution:** Execute tools and create `ObservationEvent`(s) + +**Key Characteristics:** +- **Stateless:** Agent holds no mutable state between steps +- **Event-Driven:** Reads from event history, writes new events +- **Interruptible:** Each step is atomic and can be paused/resumed + +## Agent Context + +The agent applies `AgentContext` which includes **skills** and **prompts** to shape LLM behavior: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Context["AgentContext"] + + subgraph Skills["Skills"] + Repo["repo
Always active"] + Knowledge["knowledge
Trigger-based"] + end + SystemAug["System prompt prefix/suffix
Per-conversation"] + System["Prompt template
Per-conversation"] + + subgraph Application["Applied to LLM"] + SysPrompt["System Prompt"] + UserMsg["User Messages"] + end + + Context --> Skills + Context --> SystemAug + Repo --> SysPrompt + Knowledge -.->|When triggered| UserMsg + System --> SysPrompt + SystemAug --> SysPrompt + + style Context fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Repo fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Knowledge fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +| Skill Type | Activation | Use Case | +|------------|------------|----------| +| **repo** | Always included | Project-specific context, conventions | +| **knowledge** | Trigger words/patterns | Domain knowledge, special behaviors | + +Review [this guide](/sdk/guides/skill) for details on creating and applying agent context and skills. + + +## Tool Execution + +Tools follow a **strict action-observation pattern**: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + LLM["LLM generates tool_call"] + Convert["Convert to ActionEvent"] + + Decision{"Confirmation
mode?"} + Defer["Store as pending"] + + Execute["Execute tool"] + Success{"Success?"} + + Obs["ObservationEvent
with result"] + Error["ObservationEvent
with error"] + + LLM --> Convert + Convert --> Decision + + Decision -->|Yes| Defer + Decision -->|No| Execute + + Execute --> Success + Success -->|Yes| Obs + Success -->|No| Error + + style Convert fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Execute fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Decision fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Execution Modes:** + +| Mode | Behavior | Use Case | +|------|----------|----------| +| **Direct** | Execute immediately | Development, trusted environments | +| **Confirmation** | Store as pending, wait for user approval | High-risk actions, production | + +**Security Integration:** + +Before execution, the security analyzer evaluates each action: +- **Low Risk:** Execute immediately +- **Medium Risk:** Log warning, execute with monitoring +- **High Risk:** Block execution, request user confirmation + +## Component Relationships + +### How Agent Interacts + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Agent["Agent"] + Conv["Conversation"] + LLM["LLM"] + Tools["Tools"] + Context["AgentContext"] + + Conv -->|.step calls| Agent + Agent -->|Reads events| Conv + Agent -->|Query| LLM + Agent -->|Execute| Tools + Context -.->|Skills and Context| Agent + Agent -.->|New events| Conv + + style Agent fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Conv fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style LLM fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Relationship Characteristics:** +- **Conversation → Agent**: Orchestrates step execution, provides event history +- **Agent → LLM**: Queries for next actions, receives tool calls or messages +- **Agent → Tools**: Executes actions, receives observations +- **AgentContext → Agent**: Injects skills and prompts into LLM queries + + +## See Also + +- **[Conversation Architecture](/sdk/arch/conversation)** - Agent orchestration and lifecycle +- **[Tool System](/sdk/arch/tool-system)** - Tool definition and execution patterns +- **[Events](/sdk/arch/events)** - Event types and structures +- **[Skills](/sdk/arch/skill)** - Prompt engineering and skill patterns +- **[LLM](/sdk/arch/llm)** - Language model abstraction + +### Agent Server Package +Source: https://docs.openhands.dev/sdk/arch/agent-server.md + +The Agent Server package (`openhands.agent_server`) provides an HTTP API server for remote agent execution. It enables building multi-user systems, SaaS products, and distributed agent platforms. + +**Source**: [`openhands/agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server/openhands/agent_server) + +## Purpose + +The Agent Server enables: +- **Remote execution**: Clients interact with agents via HTTP API +- **Multi-user isolation**: Each user gets isolated workspace +- **Container orchestration**: Manages Docker containers for workspaces +- **Centralized management**: Monitor and control all agents +- **Scalability**: Horizontal scaling with multiple servers + +## Architecture Overview + +```mermaid +graph TB + Client[Web/Mobile Client] -->|HTTPS| API[FastAPI Server] + + API --> Auth[Authentication] + API --> Router[API Router] + + Router --> WS[Workspace Manager] + Router --> Conv[Conversation Handler] + + WS --> Docker[Docker Manager] + Docker --> C1[Container 1
User A] + Docker --> C2[Container 2
User B] + Docker --> C3[Container 3
User C] + + Conv --> Agent[Software Agent SDK] + Agent --> C1 + Agent --> C2 + Agent --> C3 + + style Client fill:#e1f5fe + style API fill:#fff3e0 + style WS fill:#e8f5e8 + style Docker fill:#f3e5f5 + style Agent fill:#fce4ec +``` + +### Key Components + +**1. FastAPI Server** +- HTTP REST API endpoints +- Authentication and authorization +- Request validation +- WebSocket support for streaming + +**2. Workspace Manager** +- Creates and manages Docker containers +- Isolates workspaces per user +- Handles container lifecycle +- Manages resource limits + +**3. Conversation Handler** +- Routes requests to appropriate workspace +- Manages conversation state +- Handles concurrent requests +- Supports streaming responses + +**4. Docker Manager** +- Interfaces with Docker daemon +- Builds and pulls images +- Creates and destroys containers +- Monitors container health + +## Design Decisions + +### Why HTTP API? + +Alternative approaches considered: +- **gRPC**: More efficient but harder for web clients +- **WebSockets only**: Good for streaming but not RESTful +- **HTTP + WebSockets**: Best of both worlds + +**Decision**: HTTP REST for operations, WebSockets for streaming +- ✅ Works from any client (web, mobile, CLI) +- ✅ Easy to debug (curl, Postman) +- ✅ Standard authentication (API keys, OAuth) +- ✅ Streaming where needed + +### Why Container Per User? + +Alternative approaches: +- **Shared container**: Multiple users in one container +- **Container per session**: New container each conversation +- **Container per user**: One container per user (chosen) + +**Decision**: Container per user +- ✅ Strong isolation between users +- ✅ Persistent workspace across sessions +- ✅ Better resource management +- ⚠️ More containers, but worth it for isolation + +### Why FastAPI? + +Alternative frameworks: +- **Flask**: Simpler but less type-safe +- **Django**: Too heavyweight +- **FastAPI**: Modern, fast, type-safe (chosen) + +**Decision**: FastAPI +- ✅ Automatic API documentation (OpenAPI) +- ✅ Type validation with Pydantic +- ✅ Async support for performance +- ✅ WebSocket support built-in + +## API Design + +### Key Endpoints + +**Workspace Management** +``` +POST /workspaces Create new workspace +GET /workspaces/{id} Get workspace info +DELETE /workspaces/{id} Delete workspace +POST /workspaces/{id}/execute Execute command +``` + +**Conversation Management** +``` +POST /conversations Create conversation +GET /conversations/{id} Get conversation +POST /conversations/{id}/messages Send message +GET /conversations/{id}/stream Stream responses (WebSocket) +``` + +**Health & Monitoring** +``` +GET /health Server health check +GET /metrics Prometheus metrics +``` + +### Authentication + +**API Key Authentication** +```bash +curl -H "Authorization: Bearer YOUR_API_KEY" \ + https://agent-server.example.com/conversations +``` + +**Per-user workspace isolation** +- API key → user ID mapping +- Each user gets separate workspace +- Users can't access each other's workspaces + +### Streaming Responses + +**WebSocket for real-time updates** +```python +async with websocket_connect(url) as ws: + # Send message + await ws.send_json({"message": "Hello"}) + + # Receive events + async for event in ws: + if event["type"] == "message": + print(event["content"]) +``` + +**Why streaming?** +- Real-time feedback to users +- Show agent thinking process +- Better UX for long-running tasks + +## Deployment Models + +### 1. Local Development + +Run server locally for testing: +```bash +# Start server +openhands-agent-server --port 8000 + +# Or with Docker +docker run -p 8000:8000 \ + -v /var/run/docker.sock:/var/run/docker.sock \ + ghcr.io/all-hands-ai/agent-server:latest +``` + +**Use case**: Development and testing + +### 2. Single-Server Deployment + +Deploy on one server (VPS, EC2, etc.): +```bash +# Install +pip install openhands-agent-server + +# Run with systemd/supervisor +openhands-agent-server \ + --host 0.0.0.0 \ + --port 8000 \ + --workers 4 +``` + +**Use case**: Small deployments, prototypes, MVPs + +### 3. Multi-Server Deployment + +Scale horizontally with load balancer: +``` + Load Balancer + | + +-------------+-------------+ + | | | + Server 1 Server 2 Server 3 + (Agents) (Agents) (Agents) + | | | + +-------------+-------------+ + | + Shared State Store + (Database, Redis, etc.) +``` + +**Use case**: Production SaaS, high traffic, need redundancy + +### 4. Kubernetes Deployment + +Container orchestration with Kubernetes: +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: agent-server +spec: + replicas: 3 + template: + spec: + containers: + - name: agent-server + image: ghcr.io/all-hands-ai/agent-server:latest + ports: + - containerPort: 8000 +``` + +**Use case**: Enterprise deployments, auto-scaling, high availability + +## Resource Management + +### Container Limits + +Set per-workspace resource limits: +```python +# In server configuration +WORKSPACE_CONFIG = { + "resource_limits": { + "memory": "2g", # 2GB RAM + "cpus": "2", # 2 CPU cores + "disk": "10g" # 10GB disk + }, + "timeout": 300, # 5 min timeout +} +``` + +**Why limit resources?** +- Prevent one user from consuming all resources +- Fair usage across users +- Protect server from runaway processes +- Cost control + +### Cleanup & Garbage Collection + +**Container lifecycle**: +- Containers created on first use +- Kept alive between requests (warm) +- Cleaned up after inactivity timeout +- Force cleanup on server shutdown + +**Storage management**: +- Old workspaces deleted automatically +- Disk usage monitored +- Alerts when approaching limits + +## Security Considerations + +### Multi-Tenant Isolation + +**Container isolation**: +- Each user gets separate container +- Containers can't communicate +- Network isolation (optional) +- File system isolation + +**API isolation**: +- API keys mapped to users +- Users can only access their workspaces +- Server validates all permissions + +### Input Validation + +**Server validates**: +- API request schemas +- Command injection attempts +- Path traversal attempts +- File size limits + +**Defense in depth**: +- API validation +- Container validation +- Docker security features +- OS-level security + +### Network Security + +**Best practices**: +- HTTPS only (TLS certificates) +- Firewall rules (only port 443/8000) +- Rate limiting +- DDoS protection + +**Container networking**: +```python +# Disable network for workspace +WORKSPACE_CONFIG = { + "network_mode": "none" # No network access +} + +# Or allow specific hosts +WORKSPACE_CONFIG = { + "allowed_hosts": ["api.example.com"] +} +``` + +## Monitoring & Observability + +### Health Checks + +```bash +# Simple health check +curl https://agent-server.example.com/health + +# Response +{ + "status": "healthy", + "docker": "connected", + "workspaces": 15, + "uptime": 86400 +} +``` + +### Metrics + +**Prometheus metrics**: +- Request count and latency +- Active workspaces +- Container resource usage +- Error rates + +**Logging**: +- Structured JSON logs +- Per-request tracing +- Workspace events +- Error tracking + +### Alerting + +**Alert on**: +- Server down +- High error rate +- Resource exhaustion +- Container failures + +## Client SDK + +Python SDK for interacting with Agent Server: + +```python +from openhands.client import AgentServerClient + +client = AgentServerClient( + url="https://agent-server.example.com", + api_key="your-api-key" +) + +# Create conversation +conversation = client.create_conversation() + +# Send message +response = client.send_message( + conversation_id=conversation.id, + message="Hello, agent!" +) + +# Stream responses +for event in client.stream_conversation(conversation.id): + if event.type == "message": + print(event.content) +``` + +**Client handles**: +- Authentication +- Request/response serialization +- Error handling +- Streaming +- Retries + +## Cost Considerations + +### Server Costs + +**Compute**: CPU and memory for containers +- Each active workspace = 1 container +- Typically 1-2 GB RAM per workspace +- 0.5-1 CPU core per workspace + +**Storage**: Workspace files and conversation state +- ~1-10 GB per workspace (depends on usage) +- Conversation history in database + +**Network**: API requests and responses +- Minimal (mostly text) +- Streaming adds bandwidth + +### Cost Optimization + +**1. Idle timeout**: Shutdown containers after inactivity +```python +WORKSPACE_CONFIG = { + "idle_timeout": 3600 # 1 hour +} +``` + +**2. Resource limits**: Don't over-provision +```python +WORKSPACE_CONFIG = { + "resource_limits": { + "memory": "1g", # Smaller limit + "cpus": "0.5" # Fractional CPU + } +} +``` + +**3. Shared resources**: Use single server for multiple low-traffic apps + +**4. Auto-scaling**: Scale servers based on demand + +## When to Use Agent Server + +### Use Agent Server When: + +✅ **Multi-user system**: Web app with many users +✅ **Remote clients**: Mobile app, web frontend +✅ **Centralized management**: Need to monitor all agents +✅ **Workspace isolation**: Users shouldn't interfere +✅ **SaaS product**: Building agent-as-a-service +✅ **Scaling**: Need to handle concurrent users + +**Examples**: +- Chatbot platforms +- Code assistant web apps +- Agent marketplaces +- Enterprise agent deployments + +### Use Standalone SDK When: + +✅ **Single-user**: Personal tool or script +✅ **Local execution**: Running on your machine +✅ **Full control**: Need programmatic access +✅ **Simpler deployment**: No server management +✅ **Lower latency**: No network overhead + +**Examples**: +- CLI tools +- Automation scripts +- Local development +- Desktop applications + +### Hybrid Approach + +Use SDK locally but RemoteAPIWorkspace for execution: +- Agent logic in your Python code +- Execution happens on remote server +- Best of both worlds + +## Building Custom Agent Server + +The server is extensible for custom needs: + +**Custom authentication**: +```python +from openhands.agent_server import AgentServer + +class CustomAgentServer(AgentServer): + async def authenticate(self, request): + # Custom auth logic + return await oauth_verify(request) +``` + +**Custom workspace configuration**: +```python +server = AgentServer( + workspace_factory=lambda user: DockerWorkspace( + image=f"custom-image-{user.tier}", + resource_limits=user.resource_limits + ) +) +``` + +**Custom middleware**: +```python +@server.middleware +async def logging_middleware(request, call_next): + # Custom logging + response = await call_next(request) + return response +``` + +## Next Steps + +### For Usage Examples + +- [Local Agent Server](/sdk/guides/agent-server/local-server) - Run locally +- [Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox) - Docker setup +- [API Sandboxed Server](/sdk/guides/agent-server/api-sandbox) - Remote API +- [Remote Agent Server Overview](/sdk/guides/agent-server/overview) - All options + +### For Related Architecture + +- [Workspace Architecture](/sdk/arch/workspace) - RemoteAPIWorkspace details +- [SDK Architecture](/sdk/arch/sdk) - Core framework +- [Architecture Overview](/sdk/arch/overview) - System design + +### For Implementation Details + +- [`openhands/agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server/openhands/agent_server) - Server source +- [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples) - Working examples + +### Condenser +Source: https://docs.openhands.dev/sdk/arch/condenser.md + +The **Condenser** system manages conversation history compression to keep agent context within LLM token limits. It reduces long event histories into condensed summaries while preserving critical information for reasoning. For more details, read the [blog here](https://openhands.dev/blog/openhands-context-condensensation-for-more-efficient-ai-agents). + +**Source:** [`openhands-sdk/openhands/sdk/context/condenser/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/context/condenser) + +## Core Responsibilities + +The Condenser system has four primary responsibilities: + +1. **History Compression** - Reduce event lists to fit within context windows +2. **Threshold Detection** - Determine when condensation should trigger +3. **Summary Generation** - Create meaningful summaries via LLM or heuristics +4. **View Management** - Transform event history into LLM-ready views + +## Architecture + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 25, "rankSpacing": 50}} }%% +flowchart TB + subgraph Interface["Abstract Interface"] + Base["CondenserBase
Abstract base"] + end + + subgraph Implementations["Concrete Implementations"] + NoOp["NoOpCondenser
No compression"] + LLM["LLMSummarizingCondenser
LLM-based"] + Pipeline["PipelineCondenser
Multi-stage"] + end + + subgraph Process["Condensation Process"] + View["View
Event history"] + Check["should_condense()?"] + Condense["get_condensation()"] + Result["View | Condensation"] + end + + subgraph Output["Condensation Output"] + CondEvent["Condensation Event
Summary metadata"] + NewView["Condensed View
Reduced tokens"] + end + + Base --> NoOp + Base --> LLM + Base --> Pipeline + + View --> Check + Check -->|Yes| Condense + Check -->|No| Result + Condense --> CondEvent + CondEvent --> NewView + NewView --> Result + + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px + + class Base primary + class LLM,Pipeline secondary + class Check,Condense tertiary +``` + +### Key Components + +| Component | Purpose | Design | +|-----------|---------|--------| +| **[`CondenserBase`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/base.py)** | Abstract interface | Defines `condense()` contract | +| **[`RollingCondenser`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/base.py)** | Rolling window base | Implements threshold-based triggering | +| **[`LLMSummarizingCondenser`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/llm_summarizing_condenser.py)** | LLM summarization | Uses LLM to generate summaries | +| **[`NoOpCondenser`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/no_op_condenser.py)** | No-op implementation | Returns view unchanged | +| **[`PipelineCondenser`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/pipeline_condenser.py)** | Multi-stage pipeline | Chains multiple condensers | +| **[`View`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/view.py)** | Event view | Represents history for LLM | +| **[`Condensation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Condensation event | Metadata about compression | + +## Condenser Types + +### NoOpCondenser + +Pass-through condenser that performs no compression: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + View["View"] + NoOp["NoOpCondenser"] + Same["Same View"] + + View --> NoOp --> Same + + style NoOp fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px +``` + +### LLMSummarizingCondenser + +Uses an LLM to generate summaries of conversation history: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart LR + View["Long View
120+ events"] + Check["Threshold
exceeded?"] + Summarize["LLM Summarization"] + Summary["Summary Text"] + Metadata["Condensation Event"] + AddToHistory["Add to History"] + NextStep["Next Step: View.from_events()"] + NewView["Condensed View"] + + View --> Check + Check -->|Yes| Summarize + Summarize --> Summary + Summary --> Metadata + Metadata --> AddToHistory + AddToHistory --> NextStep + NextStep --> NewView + + style Check fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Summarize fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style NewView fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Process:** +1. **Check Threshold:** Compare view size to configured limit (e.g., event count > `max_size`) +2. **Select Events:** Identify events to keep (first N + last M) and events to summarize (middle) +3. **LLM Call:** Generate summary of middle events using dedicated LLM +4. **Create Event:** Wrap summary in `Condensation` event with `forgotten_event_ids` +5. **Add to History:** Agent adds `Condensation` to event log and returns early +6. **Next Step:** `View.from_events()` filters forgotten events and inserts summary + +**Configuration:** +- **`max_size`:** Event count threshold before condensation triggers (default: 120) +- **`keep_first`:** Number of initial events to preserve verbatim (default: 4) +- **`llm`:** LLM instance for summarization (often cheaper model than reasoning LLM) + +### PipelineCondenser + +Chains multiple condensers in sequence: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + View["Original View"] + C1["Condenser 1"] + C2["Condenser 2"] + C3["Condenser 3"] + Final["Final View"] + + View --> C1 --> C2 --> C3 --> Final + + style C1 fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style C2 fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style C3 fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Use Case:** Multi-stage compression (e.g., remove old events, then summarize, then truncate) + +## Condensation Flow + +### Trigger Mechanisms + +Condensers can be triggered in two ways: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + subgraph Automatic["Automatic Trigger"] + Agent1["Agent Step"] + Build1["View.from_events()"] + Check1["condenser.condense(view)"] + Trigger1["should_condense()?"] + end + + Agent1 --> Build1 --> Check1 --> Trigger1 + + style Check1 fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px +``` + +**Automatic Trigger:** +- **When:** Threshold exceeded (e.g., event count > `max_size`) +- **Who:** Agent calls `condenser.condense()` each step +- **Purpose:** Proactively keep context within limits + + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + subgraph Manual["Manual Trigger"] + Error["LLM Context Error"] + Request["CondensationRequest Event"] + NextStep["Next Agent Step"] + Trigger2["condense() detects request"] + end + + Error --> Request --> NextStep --> Trigger2 + + style Request fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` +**Manual Trigger:** +- **When:** `CondensationRequest` event added to history (via `view.unhandled_condensation_request`) +- **Who:** Agent (on LLM context window error) or application code +- **Purpose:** Force compression when context limit exceeded + +### Condensation Workflow + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + Start["Agent calls condense(view)"] + + Decision{"should_condense?"} + + ReturnView["Return View
Agent proceeds"] + + Extract["Select Events to Keep/Forget"] + Generate["LLM Generates Summary"] + Create["Create Condensation Event"] + ReturnCond["Return Condensation"] + AddHistory["Agent adds to history"] + NextStep["Next Step: View.from_events()"] + FilterEvents["Filter forgotten events"] + InsertSummary["Insert summary at offset"] + NewView["New condensed view"] + + Start --> Decision + Decision -->|No| ReturnView + Decision -->|Yes| Extract + Extract --> Generate + Generate --> Create + Create --> ReturnCond + ReturnCond --> AddHistory + AddHistory --> NextStep + NextStep --> FilterEvents + FilterEvents --> InsertSummary + InsertSummary --> NewView + + style Decision fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Generate fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Create fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Key Steps:** + +1. **Threshold Check:** `should_condense()` determines if condensation needed +2. **Event Selection:** Identify events to keep (head + tail) vs forget (middle) +3. **Summary Generation:** LLM creates compressed representation of forgotten events +4. **Condensation Creation:** Create `Condensation` event with `forgotten_event_ids` and summary +5. **Return to Agent:** Condenser returns `Condensation` (not `View`) +6. **History Update:** Agent adds `Condensation` to event log and exits step +7. **Next Step:** `View.from_events()` ([source](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/view.py)) processes Condensation to filter events and insert summary + +## View and Condensation + +### View Structure + +A `View` represents the conversation history as it will be sent to the LLM: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Events["Full Event List
+ Condensation events"] + FromEvents["View.from_events()"] + Filter["Filter forgotten events"] + Insert["Insert summary"] + View["View
LLMConvertibleEvents"] + Convert["events_to_messages()"] + LLM["LLM Input"] + + Events --> FromEvents + FromEvents --> Filter + Filter --> Insert + Insert --> View + View --> Convert + Convert --> LLM + + style View fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style FromEvents fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**View Components:** +- **`events`:** List of `LLMConvertibleEvent` objects (filtered by Condensation) +- **`unhandled_condensation_request`:** Flag for pending manual condensation +- **`condensations`:** List of all Condensation events processed +- **Methods:** `from_events()` creates view from raw events, handling Condensation semantics + +### Condensation Event + +When condensation occurs, a `Condensation` event is created: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Old["Middle Events
~60 events"] + Summary["Summary Text
LLM-generated"] + Event["Condensation Event
forgotten_event_ids"] + Applied["View.from_events()"] + New["New View
~60 events + summary"] + + Old -.->|Summarized| Summary + Summary --> Event + Event --> Applied + Applied --> New + + style Event fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Summary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Condensation Fields:** +- **`forgotten_event_ids`:** List of event IDs to filter out +- **`summary`:** Compressed text representation of forgotten events +- **`summary_offset`:** Index where summary event should be inserted +- Inherits from `Event`: `id`, `timestamp`, `source` + +## Rolling Window Pattern + +`RollingCondenser` implements a common pattern for threshold-based condensation: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + View["Current View
120+ events"] + Check["Count Events"] + + Compare{"Count >
max_size?"} + + Keep["Keep All Events"] + + Split["Split Events"] + Head["Head
First 4 events"] + Middle["Middle
~56 events"] + Tail["Tail
~56 events"] + Summarize["LLM Summarizes Middle"] + Result["Head + Summary + Tail
~60 events total"] + + View --> Check + Check --> Compare + + Compare -->|Under| Keep + Compare -->|Over| Split + + Split --> Head + Split --> Middle + Split --> Tail + + Middle --> Summarize + Head --> Result + Summarize --> Result + Tail --> Result + + style Compare fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Split fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Summarize fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Rolling Window Strategy:** +1. **Keep Head:** Preserve first `keep_first` events (default: 4) - usually system prompts +2. **Keep Tail:** Preserve last `target_size - keep_first - 1` events - recent context +3. **Summarize Middle:** Compress events between head and tail into summary +4. **Target Size:** After condensation, view has `max_size // 2` events (default: 60) + +## Component Relationships + +### How Condenser Integrates + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Agent["Agent"] + Condenser["Condenser"] + State["Conversation State"] + Events["Event Log"] + + Agent -->|"View.from_events()"| State + State -->|View| Agent + Agent -->|"condense(view)"| Condenser + Condenser -->|"View | Condensation"| Agent + Agent -->|Adds Condensation| Events + + style Condenser fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Agent fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Events fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Relationship Characteristics:** +- **Agent → State**: Calls `View.from_events()` to get current view +- **Agent → Condenser**: Calls `condense(view)` each step if condenser registered +- **Condenser → Agent**: Returns `View` (proceed) or `Condensation` (defer) +- **Agent → Events**: Adds `Condensation` event to log when returned + +## See Also + +- **[Agent Architecture](/sdk/arch/agent)** - How agents use condensers during reasoning +- **[Conversation Architecture](/sdk/arch/conversation)** - View generation and event management +- **[Events](/sdk/arch/events)** - Condensation event type and append-only log +- **[Context Condenser Guide](/sdk/guides/context-condenser)** - Configuring and using condensers + +### Conversation +Source: https://docs.openhands.dev/sdk/arch/conversation.md + +The **Conversation** component orchestrates agent execution through structured message flows and state management. It serves as the primary interface for interacting with agents, managing their lifecycle from initialization to completion. + +**Source:** [`openhands-sdk/openhands/sdk/conversation/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/conversation) + +## Core Responsibilities + +The Conversation system has four primary responsibilities: + +1. **Agent Lifecycle Management** - Initialize, run, pause, and terminate agents +2. **State Orchestration** - Maintain conversation history, events, and execution status +3. **Workspace Coordination** - Bridge agent operations with execution environments +4. **Runtime Services** - Provide persistence, monitoring, security, and visualization + +## Architecture + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 25, "rankSpacing": 35}} }%% +flowchart LR + User["User Code"] + + subgraph Factory[" "] + Entry["Conversation()"] + end + + subgraph Implementations[" "] + Local["LocalConversation
Direct execution"] + Remote["RemoteConversation
Via agent-server API"] + end + + subgraph Core[" "] + State["ConversationState
• agent
workspace • stats • ..."] + EventLog["ConversationState.events
Event storage"] + end + + User --> Entry + Entry -.->|LocalWorkspace| Local + Entry -.->|RemoteWorkspace| Remote + + Local --> State + Remote --> State + + State --> EventLog + + classDef factory fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef impl fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef core fill:#fff4df,stroke:#b7791f,stroke-width:2px + classDef service fill:#e9f9ef,stroke:#2f855a,stroke-width:1.5px + + class Entry factory + class Local,Remote impl + class State,EventLog core + class Persist,Stuck,Viz,Secrets service +``` + +### Key Components + +| Component | Purpose | Design | +|-----------|---------|--------| +| **[`Conversation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/conversation.py)** | Unified entrypoint | Returns correct implementation based on workspace type | +| **[`LocalConversation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py)** | Local execution | Runs agent directly in process | +| **[`RemoteConversation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py)** | Remote execution | Delegates to agent-server via HTTP/WebSocket | +| **[`ConversationState`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/state.py)** | State container | Pydantic model with validation and serialization | +| **[`EventLog`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/event_store.py)** | Event storage | Immutable append-only store with efficient queries | + +## Factory Pattern + +The [`Conversation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/conversation.py) class automatically selects the correct implementation based on workspace type: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Input["Conversation(agent, workspace)"] + Check{Workspace Type?} + Local["LocalConversation
Agent runs in-process"] + Remote["RemoteConversation
Agent runs via API"] + + Input --> Check + Check -->|str or LocalWorkspace| Local + Check -->|RemoteWorkspace| Remote + + style Input fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Local fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Remote fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Dispatch Logic:** +- **Local:** String paths or `LocalWorkspace` → in-process execution +- **Remote:** `RemoteWorkspace` → agent-server via HTTP/WebSocket + +This abstraction enables switching deployment modes without code changes—just swap the workspace type. + +## State Management + +State updates follow a **two-path pattern** depending on the type of change: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + Start["State Update Request"] + Lock["Acquire FIFO Lock"] + Decision{New Event?} + + StateOnly["Update State Fields
stats, status, metadata"] + EventPath["Append to Event Log
messages, actions, observations"] + + Callback["Trigger Callbacks"] + Release["Release Lock"] + + Start --> Lock + Lock --> Decision + Decision -->|No| StateOnly + Decision -->|Yes| EventPath + StateOnly --> Callback + EventPath --> Callback + Callback --> Release + + style Decision fill:#fff4df,stroke:#b7791f,stroke-width:2px + style EventPath fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style StateOnly fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px +``` + +**Two Update Patterns:** + +1. **State-Only Updates** - Modify fields without appending events (e.g., status changes, stat increments) +2. **Event-Based Updates** - Append to event log when new messages, actions, or observations occur + +**Thread Safety:** +- FIFO Lock ensures ordered, atomic updates +- Callbacks fire after successful commit +- Read operations never block writes + +## Execution Models + +The conversation system supports two execution models with identical APIs: + +### Local vs Remote Execution + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + subgraph Local["LocalConversation"] + L1["User sends message"] + L2["Agent executes in-process"] + L3["Direct tool calls"] + L4["Events via callbacks"] + L1 --> L2 --> L3 --> L4 + end + style Local fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + subgraph Remote["RemoteConversation"] + R1["User sends message"] + R2["HTTP → Agent Server"] + R3["Isolated container execution"] + R4["WebSocket event stream"] + R1 --> R2 --> R3 --> R4 + end + style Remote fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +| Aspect | LocalConversation | RemoteConversation | +|--------|-------------------|-------------------| +| **Execution** | In-process | Remote container/server | +| **Communication** | Direct function calls | HTTP + WebSocket | +| **State Sync** | Immediate | Network serialized | +| **Use Case** | Development, CLI tools | Production, web apps | +| **Isolation** | Process-level | Container-level | + +**Key Insight:** Same API surface means switching between local and remote requires only changing workspace type—no code changes. + +## Auxiliary Services + +The conversation system provides pluggable services that operate independently on the event stream: + +| Service | Purpose | Architecture Pattern | +|---------|---------|---------------------| +| **[Event Log](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/event_store.py)** | Append-only immutable storage | Event sourcing with indexing | +| **[Persistence](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/state.py)** | Auto-save & resume | Debounced writes, incremental events | +| **[Stuck Detection](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/stuck_detector.py)** | Loop prevention | Sliding window pattern matching | +| **[Visualization](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/visualizer/)** | Execution diagrams | Event stream → visual representation | +| **[Secret Registry](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/secret_registry.py)** | Secure value storage | Memory-only with masked logging | + +**Design Principle:** Services read from the event log but never mutate state directly. This enables: +- Services can be enabled/disabled independently +- Easy to add new services without changing core orchestration +- Event stream acts as the integration point + +## Component Relationships + +### How Conversation Interacts + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Conv["Conversation"] + Agent["Agent"] + WS["Workspace"] + Tools["Tools"] + LLM["LLM"] + + Conv -->|Delegates to| Agent + Conv -->|Configures| WS + Agent -.->|Updates| Conv + Agent -->|Uses| Tools + Agent -->|Queries| LLM + + style Conv fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Agent fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style WS fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Relationship Characteristics:** +- **Conversation → Agent**: One-way orchestration, agent reports back via state updates +- **Conversation → Workspace**: Configuration only, workspace doesn't know about conversation +- **Agent → Conversation**: Indirect via state events + +## See Also + +- **[Agent Architecture](/sdk/arch/agent)** - Agent reasoning loop design +- **[Workspace Architecture](/sdk/arch/workspace)** - Execution environment design +- **[Event System](/sdk/arch/events)** - Event types and flow +- **[Conversation Usage Guide](/sdk/guides/convo-persistence)** - Practical examples + +### Design Principles +Source: https://docs.openhands.dev/sdk/arch/design.md + +The **OpenHands Software Agent SDK** is part of the [OpenHands V1](https://openhands.dev/blog/the-path-to-openhands-v1) effort — a complete architectural rework based on lessons from **OpenHands V0**, one of the most widely adopted open-source coding agents. + +[Over the last eighteen months](https://openhands.dev/blog/one-year-of-openhands-a-journey-of-open-source-ai-development), OpenHands V0 evolved from a scrappy prototype into a widely used open-source coding agent. The project grew to tens of thousands of GitHub stars, hundreds of contributors, and multiple production deployments. That growth exposed architectural tensions — tight coupling between research and production, mandatory sandboxing, mutable state, and configuration sprawl — which informed the design principles of agent-sdk in V1. + +## Optional Isolation over Mandatory Sandboxing + +
Base class"] + LLMBase["LLMConvertibleEvent
Abstract base"] + + subgraph LLMTypes["LLM-Convertible Events
Visible to the LLM"] + Message["MessageEvent
User/assistant text"] + Action["ActionEvent
Tool calls"] + System["SystemPromptEvent
Initial system prompt"] + CondSummary["CondensationSummaryEvent
Condenser summary"] + + ObsBase["ObservationBaseEvent
Base for tool responses"] + Observation["ObservationEvent
Tool results"] + UserReject["UserRejectObservation
User rejected action"] + AgentError["AgentErrorEvent
Agent error"] + end + + subgraph Internals["Internal Events
NOT visible to the LLM"] + ConvState["ConversationStateUpdateEvent
State updates"] + CondReq["CondensationRequest
Request compression"] + Cond["Condensation
Compression result"] + Pause["PauseEvent
User pause"] + end + + Base --> LLMBase + Base --> Internals + LLMBase --> LLMTypes + ObsBase --> Observation + ObsBase --> UserReject + ObsBase --> AgentError + + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px + + class Base,LLMBase,Message,Action,SystemPromptEvent primary + class ObsBase,Observation,UserReject,AgentError secondary + class ConvState,CondReq,Cond,Pause tertiary +``` + +### Key Components + +| Component | Purpose | Design | +|-----------|---------|--------| +| **[`Event`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/base.py)** | Base event class | Immutable Pydantic model with ID, timestamp, source | +| **[`LLMConvertibleEvent`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/base.py)** | LLM-compatible events | Abstract class with `to_llm_message()` method | +| **[`MessageEvent`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/message.py)** | Text messages | User or assistant conversational messages with skills | +| **[`ActionEvent`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/action.py)** | Tool calls | Agent tool invocations with thought, reasoning, security risk | +| **[`ObservationBaseEvent`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | Tool response base | Base for all tool call responses | +| **[`ObservationEvent`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | Tool results | Successful tool execution outcomes | +| **[`UserRejectObservation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | User rejection | User rejected action in confirmation mode | +| **[`AgentErrorEvent`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | Agent errors | Errors from agent/scaffold (not model output) | +| **[`SystemPromptEvent`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/system.py)** | System context | System prompt with tool schemas | +| **[`CondensationSummaryEvent`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Condenser summary | LLM-convertible summary of forgotten events | +| **[`ConversationStateUpdateEvent`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/conversation_state.py)** | State updates | Key-value conversation state changes | +| **[`Condensation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Condensation result | Events being forgotten with optional summary | +| **[`CondensationRequest`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Request compression | Trigger for conversation history compression | +| **[`PauseEvent`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/user_action.py)** | User pause | User requested pause of agent execution | + +## Event Types + +### LLM-Convertible Events + +Events that participate in agent reasoning and can be converted to LLM messages: + + +| Event Type | Source | Content | LLM Role | +|------------|--------|---------|----------| +| **MessageEvent (user)** | user | Text, images | `user` | +| **MessageEvent (agent)** | agent | Text reasoning, skills | `assistant` | +| **ActionEvent** | agent | Tool call with thought, reasoning, security risk | `assistant` with `tool_calls` | +| **ObservationEvent** | environment | Tool execution result | `tool` | +| **UserRejectObservation** | environment | Rejection reason | `tool` | +| **AgentErrorEvent** | agent | Error details | `tool` | +| **SystemPromptEvent** | agent | System prompt with tool schemas | `system` | +| **CondensationSummaryEvent** | environment | Summary of forgotten events | `user` | + +The event system bridges agent events to LLM messages: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Events["Event List"] + Filter["Filter LLMConvertibleEvent"] + Group["Group ActionEvents
by llm_response_id"] + Convert["Convert to Messages"] + LLM["LLM Input"] + + Events --> Filter + Filter --> Group + Group --> Convert + Convert --> LLM + + style Filter fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Group fill:#fff4df,stroke:#b7791f,stroke-width:2px + style Convert fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Special Handling - Parallel Function Calling:** + +When multiple `ActionEvent`s share the same `llm_response_id` (parallel function calling): +1. Group all ActionEvents by `llm_response_id` +2. Combine into single Message with multiple `tool_calls` +3. Only first event's `thought`, `reasoning_content`, and `thinking_blocks` are included +4. All subsequent events in the batch have empty thought fields + +**Example:** +``` +ActionEvent(llm_response_id="abc123", thought="Let me check...", tool_call=tool1) +ActionEvent(llm_response_id="abc123", thought=[], tool_call=tool2) +→ Combined into single Message(role="assistant", content="Let me check...", tool_calls=[tool1, tool2]) +``` + + +### Internal Events + +Events for metadata, control flow, and user actions (not sent to LLM): + +| Event Type | Source | Purpose | Key Fields | +|------------|--------|---------|------------| +| **ConversationStateUpdateEvent** | environment | State synchronization | `key` (field name), `value` (serialized data) | +| **CondensationRequest** | environment | Trigger history compression | Signal to condenser when context window exceeded | +| **Condensation** | environment | Compression result | `forgotten_event_ids`, `summary`, `summary_offset` | +| **PauseEvent** | user | User pause action | Indicates agent execution was paused by user | + +**Source Types:** +- **user**: Event originated from user input +- **agent**: Event generated by agent logic +- **environment**: Event from system/framework/tools + +## Component Relationships + +### How Events Integrate + +## `source` vs LLM `role` + +Events often carry **two different concepts** that are easy to confuse: + +- **`Event.source`**: where the event *originated* (`user`, `agent`, or `environment`). This is about attribution. +- **LLM `role`** (e.g. `Message.role` / `MessageEvent.llm_message.role`): how the event should be represented to the LLM (`system`, `user`, `assistant`, `tool`). This is about LLM formatting. + +These fields are **intentionally independent**. + +Common examples include: + +- **Observations**: tool results are typically `source="environment"` and represented to the LLM with `role="tool"`. +- **Synthetic framework messages**: the SDK may inject feedback or control messages (e.g. from hooks) as `source="environment"` while still using an LLM `role="user"` so the agent reads it as a user-facing instruction. + +**Do not infer event origin from LLM role.** If you need to distinguish real user input from synthetic/framework messages, rely on `Event.source` (and any explicit metadata fields on the event), not the LLM role. + + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Events["Event System"] + Agent["Agent"] + Conversation["Conversation"] + Tools["Tools"] + Services["Auxiliary Services"] + + Agent -->|Reads| Events + Agent -->|Writes| Events + Conversation -->|Manages| Events + Tools -->|Creates| Events + Events -.->|Stream| Services + + style Events fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Agent fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Conversation fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Relationship Characteristics:** +- **Agent → Events**: Reads history for context, writes actions/messages +- **Conversation → Events**: Owns and persists event log +- **Tools → Events**: Create ObservationEvents after execution +- **Services → Events**: Read-only observers for monitoring, visualization + +## Error Events: Agent vs Conversation + +Two distinct error events exist in the SDK, with different purpose and visibility: + +- AgentErrorEvent + - Type: ObservationBaseEvent (LLM-convertible) + - Scope: Error for a specific tool call (has tool_name and tool_call_id) + - Source: "agent" + - LLM visibility: Sent as a tool message so the model can react/recover + - Effect: Conversation continues; not a terminal state + - Code: https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py + +- ConversationErrorEvent + - Type: Event (not LLM-convertible) + - Scope: Conversation-level runtime failure (no tool_name/tool_call_id) + - Source: typically "environment" + - LLM visibility: Not sent to the model + - Effect: Run loop transitions to ERROR and run() raises ConversationRunError; surface top-level error to client applications + - Code: https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/conversation_error.py + +## See Also + +- **[Agent Architecture](/sdk/arch/agent)** - How agents read and write events +- **[Conversation Architecture](/sdk/arch/conversation)** - Event log management +- **[Tool System](/sdk/arch/tool-system)** - ActionEvent and ObservationEvent generation +- **[Condenser](/sdk/arch/condenser)** - Event history compression + +### LLM +Source: https://docs.openhands.dev/sdk/arch/llm.md + +The **LLM** system provides a unified interface to language model providers through LiteLLM. It handles model configuration, request orchestration, retry logic, telemetry, and cost tracking across all providers. + +**Source:** [`openhands-sdk/openhands/sdk/llm/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/llm) + +## Core Responsibilities + +The LLM system has five primary responsibilities: + +1. **Provider Abstraction** - Uniform interface to OpenAI, Anthropic, Google, and 100+ providers +2. **Request Pipeline** - Dual API support: Chat Completions (`completion()`) and Responses API (`responses()`) +3. **Configuration Management** - Load from environment, JSON, or programmatic configuration +4. **Telemetry & Cost** - Track usage, latency, and costs across providers +5. **Enhanced Reasoning** - Support for OpenAI Responses API with encrypted thinking and reasoning summaries + +## Architecture + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 25, "rankSpacing": 70}} }%% +flowchart TB + subgraph Configuration["Configuration Sources"] + Env["Environment Variables
LLM_MODEL, LLM_API_KEY"] + JSON["JSON Files
config/llm.json"] + Code["Programmatic
LLM(...)"] + end + + subgraph Core["Core LLM"] + Model["LLM Model
Pydantic configuration"] + Pipeline["Request Pipeline
Retry, timeout, telemetry"] + end + + subgraph Backend["LiteLLM Backend"] + Providers["100+ Providers
OpenAI, Anthropic, etc."] + end + + subgraph Output["Telemetry"] + Usage["Token Usage"] + Cost["Cost Tracking"] + Latency["Latency Metrics"] + end + + Env --> Model + JSON --> Model + Code --> Model + + Model --> Pipeline + Pipeline --> Providers + + Pipeline --> Usage + Pipeline --> Cost + Pipeline --> Latency + + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px + + class Model primary + class Pipeline secondary + class LiteLLM tertiary +``` + +### Key Components + +| Component | Purpose | Design | +|-----------|---------|--------| +| **[`LLM`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/llm/llm.py)** | Configuration model | Pydantic model with provider settings | +| **[`completion()`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/llm/llm.py)** | Chat Completions API | Handles retries, timeouts, streaming | +| **[`responses()`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/llm/llm.py)** | Responses API | Enhanced reasoning with encrypted thinking | +| **[`LiteLLM`](https://github.com/BerriAI/litellm)** | Provider adapter | Unified API for 100+ providers | +| **Configuration Loaders** | Config hydration | `load_from_env()`, `load_from_json()` | +| **Telemetry** | Usage tracking | Token counts, costs, latency | + +## Configuration + +See [`LLM` source](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/llm/llm.py) for complete list of supported fields. + +### Programmatic Configuration + +Create LLM instances directly in code: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Code["Python Code"] + LLM["LLM(model=...)"] + Agent["Agent"] + + Code --> LLM + LLM --> Agent + + style LLM fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px +``` + +**Example:** +```python +from pydantic import SecretStr +from openhands.sdk import LLM + +llm = LLM( + model="anthropic/claude-sonnet-4.1", + api_key=SecretStr("sk-ant-123"), + temperature=0.1, + timeout=120, +) +``` + +### Environment Variable Configuration + +Load from environment using naming convention: + +**Environment Variable Pattern:** +- **Prefix:** All variables start with `LLM_` +- **Mapping:** `LLM_FIELD` → `field` (lowercased) +- **Types:** Auto-cast to int, float, bool, JSON, or SecretStr + +**Common Variables:** +```bash +export LLM_MODEL="anthropic/claude-sonnet-4.1" +export LLM_API_KEY="sk-ant-123" +export LLM_USAGE_ID="primary" +export LLM_TIMEOUT="120" +export LLM_NUM_RETRIES="5" +``` + +### JSON Configuration + +Serialize and load from JSON files: + +**Example:** +```python +# Save +llm.model_dump_json(exclude_none=True, indent=2) + +# Load +llm = LLM.load_from_json("config/llm.json") +``` + +**Security:** Secrets are redacted in serialized JSON (combine with environment variables for sensitive data). +If you need to include secrets in JSON, use `llm.model_dump_json(exclude_none=True, context={"expose_secrets": True})`. + + +## Request Pipeline + +### Completion Flow + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 20}} }%% +flowchart TB + Request["completion() or responses() call"] + Validate["Validate Config"] + + Attempt["LiteLLM Request"] + Success{"Success?"} + + Retry{"Retries
remaining?"} + Wait["Exponential Backoff"] + + Telemetry["Record Telemetry"] + Response["Return Response"] + Error["Raise Error"] + + Request --> Validate + Validate --> Attempt + Attempt --> Success + + Success -->|Yes| Telemetry + Success -->|No| Retry + + Retry -->|Yes| Wait + Retry -->|No| Error + + Wait --> Attempt + Telemetry --> Response + + style Attempt fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Retry fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Telemetry fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Pipeline Stages:** + +1. **Validation:** Check required fields (model, messages) +2. **Request:** Call LiteLLM with provider-specific formatting +3. **Retry Logic:** Exponential backoff on failures (configurable) +4. **Telemetry:** Record tokens, cost, latency +5. **Response:** Return completion or raise error + +### Responses API Support + +In addition to the standard chat completion API, the LLM system supports [OpenAI's Responses API](https://platform.openai.com/docs/api-reference/responses) as an alternative invocation path for models that benefit from this newer interface (e.g., GPT-5-Codex only supports Responses API). The Responses API provides enhanced reasoning capabilities with encrypted thinking and detailed reasoning summaries. + +#### Architecture + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + Check{"Model supports
Responses API?"} + + subgraph Standard["Standard Path"] + ChatFormat["Format as
Chat Messages"] + ChatCall["litellm.completion()"] + end + + subgraph ResponsesPath["Responses Path"] + RespFormat["Format as
instructions + input[]"] + RespCall["litellm.responses()"] + end + + ChatResponse["ModelResponse"] + RespResponse["ResponsesAPIResponse"] + + Parse["Parse to Message"] + Return["LLMResponse"] + + Check -->|No| ChatFormat + Check -->|Yes| RespFormat + + ChatFormat --> ChatCall + RespFormat --> RespCall + + ChatCall --> ChatResponse + RespCall --> RespResponse + + ChatResponse --> Parse + RespResponse --> Parse + + Parse --> Return + + style RespFormat fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style RespCall fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +#### Supported Models + +Models that automatically use the Responses API path: + +| Pattern | Examples | Documentation | +|---------|----------|---------------| +| **gpt-5*** | `gpt-5`, `gpt-5-mini`, `gpt-5-codex` | OpenAI GPT-5 family | + +**Detection:** The SDK automatically detects if a model supports the Responses API using pattern matching in [`model_features.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/llm/utils/model_features.py). + + +## Provider Integration + +### LiteLLM Abstraction + +Software Agent SDK uses LiteLLM for provider abstraction: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart TB + SDK["Software Agent SDK"] + LiteLLM["LiteLLM"] + + subgraph Providers["100+ Providers"] + OpenAI["OpenAI"] + Anthropic["Anthropic"] + Google["Google"] + Azure["Azure"] + Others["..."] + end + + SDK --> LiteLLM + LiteLLM --> OpenAI + LiteLLM --> Anthropic + LiteLLM --> Google + LiteLLM --> Azure + LiteLLM --> Others + + style LiteLLM fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style SDK fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Benefits:** +- **100+ Providers:** OpenAI, Anthropic, Google, Azure, AWS Bedrock, local models, etc. +- **Unified API:** Same interface regardless of provider +- **Format Translation:** Provider-specific request/response formatting +- **Error Handling:** Normalized error codes and messages + +### LLM Providers + +Provider integrations remain shared between the Software Agent SDK and the OpenHands Application. +The pages linked below live under the OpenHands app section but apply +verbatim to SDK applications because both layers wrap the same +`openhands.sdk.llm.LLM` interface. + +| Provider / scenario | Documentation | +| --- | --- | +| OpenHands hosted models | [/openhands/usage/llms/openhands-llms](/openhands/usage/llms/openhands-llms) | +| OpenAI | [/openhands/usage/llms/openai-llms](/openhands/usage/llms/openai-llms) | +| Azure OpenAI | [/openhands/usage/llms/azure-llms](/openhands/usage/llms/azure-llms) | +| Google Gemini / Vertex | [/openhands/usage/llms/google-llms](/openhands/usage/llms/google-llms) | +| Groq | [/openhands/usage/llms/groq](/openhands/usage/llms/groq) | +| OpenRouter | [/openhands/usage/llms/openrouter](/openhands/usage/llms/openrouter) | +| 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) | + +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, +or custom headers) and pass it into your agent or registry. The OpenHands UI +surfacing is simply a convenience layer on top of the same configuration model. + + +## Telemetry and Cost Tracking + +### Telemetry Collection + +LLM requests automatically collect metrics: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Request["LLM Request"] + + subgraph Metrics + Tokens["Token Counts
Input/Output"] + Cost["Cost
USD"] + Latency["Latency
ms"] + end + + Events["Event Log"] + + Request --> Tokens + Request --> Cost + Request --> Latency + + Tokens --> Events + Cost --> Events + Latency --> Events + + style Metrics fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Events fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Tracked Metrics:** +- **Token Usage:** Input tokens, output tokens, total +- **Cost:** Per-request cost using configured rates +- **Latency:** Request duration in milliseconds +- **Errors:** Failure types and retry counts + +### Cost Configuration + +Configure per-token costs for custom models: + +```python +llm = LLM( + model="custom/my-model", + input_cost_per_token=0.00001, # $0.01 per 1K tokens + output_cost_per_token=0.00003, # $0.03 per 1K tokens +) +``` + +**Built-in Costs:** LiteLLM includes costs for major providers (updated regularly, [link](https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json)) + +**Custom Costs:** Override for: +- Internal models +- Custom pricing agreements +- Cost estimation for budgeting + +## Component Relationships + +### How LLM Integrates + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + LLM["LLM"] + Agent["Agent"] + Conversation["Conversation"] + Events["Events"] + Security["Security Analyzer"] + Condenser["Context Condenser"] + + Agent -->|Uses| LLM + LLM -->|Records| Events + Security -.->|Optional| LLM + Condenser -.->|Optional| LLM + Conversation -->|Provides context| Agent + + style LLM fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Agent fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Events fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Relationship Characteristics:** +- **Agent → LLM**: Agent uses LLM for reasoning and tool calls +- **LLM → Events**: LLM requests/responses recorded as events +- **Security → LLM**: Optional security analyzer can use separate LLM +- **Condenser → LLM**: Optional context condenser can use separate LLM +- **Configuration**: LLM configured independently, passed to agent +- **Telemetry**: LLM metrics flow through event system to UI/logging + +## See Also + +- **[Agent Architecture](/sdk/arch/agent)** - How agents use LLMs for reasoning and perform actions +- **[Events](/sdk/arch/events)** - LLM request/response event types +- **[Security](/sdk/arch/security)** - Optional LLM-based security analysis +- **[Provider Setup Guides](/openhands/usage/llms/openai-llms)** - Provider-specific configuration + +### MCP Integration +Source: https://docs.openhands.dev/sdk/arch/mcp.md + +The **MCP Integration** system enables agents to use external tools via the Model Context Protocol (MCP). It provides a bridge between MCP servers and the Software Agent SDK's tool system, supporting both synchronous and asynchronous execution. + +**Source:** [`openhands/sdk/mcp/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/mcp) + +## Core Responsibilities + +The MCP Integration system has four primary responsibilities: + +1. **MCP Client Management** - Connect to and communicate with MCP servers +2. **Tool Discovery** - Enumerate available tools from MCP servers +3. **Schema Adaptation** - Convert MCP tool schemas to SDK tool definitions +4. **Execution Bridge** - Execute MCP tool calls from agent actions + +## Architecture + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 25, "rankSpacing": 35}} }%% +flowchart TB + subgraph Client["MCP Client"] + Sync["MCPClient
Sync/Async bridge"] + Async["AsyncMCPClient
FastMCP base"] + end + + subgraph Bridge["Tool Bridge"] + Def["MCPToolDefinition
Schema conversion"] + Exec["MCPToolExecutor
Execution handler"] + end + + subgraph Integration["Agent Integration"] + Action["MCPToolAction
Dynamic model"] + Obs["MCPToolObservation
Result wrapper"] + end + + subgraph External["External"] + Server["MCP Server
stdio/HTTP"] + Tools["External Tools"] + end + + Sync --> Async + Async --> Server + + Server --> Def + Def --> Exec + + Exec --> Action + Action --> Server + Server --> Obs + + Server -.->|Spawns| Tools + + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px + + class Sync,Async primary + class Def,Exec secondary + class Action,Obs tertiary +``` + +### Key Components + +| Component | Purpose | Design | +|-----------|---------|--------| +| **[`MCPClient`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/client.py)** | Client wrapper | Extends FastMCP with sync/async bridge | +| **[`MCPToolDefinition`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/definition.py)** | Tool metadata | Converts MCP schemas to SDK format | +| **[`MCPToolExecutor`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/tool.py)** | Execution handler | Bridges agent actions to MCP calls | +| **[`MCPToolAction`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/definition.py)** | Dynamic action model | Runtime-generated Pydantic model | +| **[`MCPToolObservation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/definition.py)** | Result wrapper | Wraps MCP tool results | + +## MCP Client + +### Sync/Async Bridge + +The SDK's `MCPClient` extends FastMCP's async client with synchronous wrappers: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + Sync["Sync Code
Agent execution"] + Bridge["call_async_from_sync()"] + Executor["AsyncExecutor
Background loop"] + Async["Async MCP Call"] + Server["MCP Server"] + Result["Result"] + + Sync --> Bridge + Bridge --> Executor + Executor --> Async + Async --> Server + Server --> Result + Result --> Sync + + style Bridge fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Executor fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Async fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Bridge Pattern:** +- **Problem:** MCP protocol is async, but agent tools run synchronously +- **Solution:** Background event loop that executes async code from sync contexts +- **Benefit:** Agents use MCP tools without async/await in tool definitions + +**Client Features:** +- **Lifecycle Management:** `__enter__`/`__exit__` for context manager +- **Timeout Support:** Configurable timeouts for MCP operations +- **Error Handling:** Wraps MCP errors in observations +- **Connection Pooling:** Reuses connections across tool calls + +### MCP Server Configuration + +MCP servers are configured using the FastMCP format: + +```python +mcp_config = { + "mcpServers": { + "fetch": { + "command": "uvx", + "args": ["mcp-server-fetch"] + }, + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] + } + } +} +``` + +**Configuration Fields:** +- **command:** Executable to spawn (e.g., `uvx`, `npx`, `node`) +- **args:** Arguments to pass to command +- **env:** Environment variables (optional) + +## Tool Discovery and Conversion + +### Discovery Flow + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + Config["MCP Config"] + Spawn["Spawn Server"] + List["List Tools"] + + subgraph Convert["Convert Each Tool"] + Schema["MCP Schema"] + Action["Generate Action Model"] + Def["Create ToolDefinition"] + end + + Register["Register in ToolRegistry"] + + Config --> Spawn + Spawn --> List + List --> Schema + + Schema --> Action + Action --> Def + Def --> Register + + style Spawn fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Action fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Register fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Discovery Steps:** + +1. **Spawn Server:** Launch MCP server via stdio +2. **List Tools:** Call `tools/list` MCP endpoint +3. **Parse Schemas:** Extract tool names, descriptions, parameters +4. **Generate Models:** Dynamically create Pydantic models for actions +5. **Create Definitions:** Wrap in `ToolDefinition` objects +6. **Register:** Add to agent's tool registry + +### Schema Conversion + +MCP tool schemas are converted to SDK tool definitions: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + MCP["MCP Tool Schema
JSON Schema"] + Parse["Parse Parameters"] + Model["Dynamic Pydantic Model
MCPToolAction"] + Def["ToolDefinition
SDK format"] + + MCP --> Parse + Parse --> Model + Model --> Def + + style Parse fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Model fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Conversion Rules:** + +| MCP Schema | SDK Action Model | +|------------|------------------| +| **name** | Class name (camelCase) | +| **description** | Docstring | +| **inputSchema** | Pydantic fields | +| **required** | Field(required=True) | +| **type** | Python type hints | + +**Example:** + +```python +# MCP Schema +{ + "name": "fetch_url", + "description": "Fetch content from URL", + "inputSchema": { + "type": "object", + "properties": { + "url": {"type": "string"}, + "timeout": {"type": "number"} + }, + "required": ["url"] + } +} + +# Generated Action Model +class FetchUrl(MCPToolAction): + """Fetch content from URL""" + url: str + timeout: float | None = None +``` + +## Tool Execution + +### Execution Flow + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + Agent["Agent generates action"] + Action["MCPToolAction"] + Executor["MCPToolExecutor"] + + Convert["Convert to MCP format"] + Call["MCP call_tool"] + Server["MCP Server"] + + Result["MCP Result"] + Obs["MCPToolObservation"] + Return["Return to Agent"] + + Agent --> Action + Action --> Executor + Executor --> Convert + Convert --> Call + Call --> Server + Server --> Result + Result --> Obs + Obs --> Return + + style Executor fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Call fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Obs fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Execution Steps:** + +1. **Action Creation:** LLM generates tool call, parsed into `MCPToolAction` +2. **Executor Lookup:** Find `MCPToolExecutor` for tool name +3. **Format Conversion:** Convert action fields to MCP arguments +4. **MCP Call:** Execute `call_tool` via MCP client +5. **Result Parsing:** Parse MCP result (text, images, resources) +6. **Observation Creation:** Wrap in `MCPToolObservation` +7. **Error Handling:** Catch exceptions, return error observations + +### MCPToolExecutor + +Executors bridge SDK actions to MCP calls: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Executor["MCPToolExecutor"] + Client["MCP Client"] + Name["tool_name"] + + Executor -->|Uses| Client + Executor -->|Knows| Name + + style Executor fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Client fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Executor Responsibilities:** +- **Client Management:** Hold reference to MCP client +- **Tool Identification:** Know which MCP tool to call +- **Argument Conversion:** Transform action fields to MCP format +- **Result Handling:** Parse MCP responses +- **Error Recovery:** Handle connection errors, timeouts, server failures + +## MCP Tool Lifecycle + +### From Configuration to Execution + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + Load["Load MCP Config"] + Start["Start Conversation"] + Spawn["Spawn MCP Servers"] + Discover["Discover Tools"] + Register["Register Tools"] + + Ready["Agent Ready"] + + Step["Agent Step"] + LLM["LLM Tool Call"] + Execute["Execute MCP Tool"] + Result["Return Observation"] + + End["End Conversation"] + Cleanup["Close MCP Clients"] + + Load --> Start + Start --> Spawn + Spawn --> Discover + Discover --> Register + Register --> Ready + + Ready --> Step + Step --> LLM + LLM --> Execute + Execute --> Result + Result --> Step + + Step --> End + End --> Cleanup + + style Spawn fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Execute fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Cleanup fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Lifecycle Phases:** + +| Phase | Operations | Components | +|-------|-----------|------------| +| **Initialization** | Spawn servers, discover tools | MCPClient, ToolRegistry | +| **Registration** | Create definitions, executors | MCPToolDefinition, MCPToolExecutor | +| **Execution** | Handle tool calls | Agent, MCPToolAction | +| **Cleanup** | Close connections, shutdown servers | MCPClient.sync_close() | + +## MCP Annotations + +MCP tools can include metadata hints for agents: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Tool["MCP Tool"] + + subgraph Annotations + ReadOnly["readOnlyHint"] + Destructive["destructiveHint"] + Progress["progressEnabled"] + end + + Security["Security Analysis"] + + Tool --> ReadOnly + Tool --> Destructive + Tool --> Progress + + ReadOnly --> Security + Destructive --> Security + + style Destructive fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Security fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Annotation Types:** + +| Annotation | Meaning | Use Case | +|------------|---------|----------| +| **readOnlyHint** | Tool doesn't modify state | Lower security risk | +| **destructiveHint** | Tool modifies/deletes data | Require confirmation | +| **progressEnabled** | Tool reports progress | Show progress UI | + +These annotations feed into the security analyzer for risk assessment. + +## Component Relationships + +### How MCP Integrates + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + MCP["MCP System"] + Skills["Skills"] + Tools["Tool Registry"] + Agent["Agent"] + Security["Security"] + + Skills -->|Configures| MCP + MCP -->|Registers| Tools + Agent -->|Uses| Tools + MCP -->|Provides hints| Security + + style MCP fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Skills fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Agent fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Relationship Characteristics:** +- **Skills → MCP**: Repository skills can embed MCP configurations +- **MCP → Tools**: MCP tools registered alongside native tools +- **Agent → Tools**: Agents use MCP tools like any other tool +- **MCP → Security**: Annotations inform security risk assessment +- **Transparent Integration**: Agent doesn't distinguish MCP from native tools + +## Design Rationale + +**Async Bridge Pattern:** MCP protocol requires async, but synchronous tool execution simplifies agent implementation. Background event loop bridges the gap without exposing async complexity to tool users. + +**Dynamic Model Generation:** Creating Pydantic models at runtime from MCP schemas enables type-safe tool calls without manual model definitions. This supports arbitrary MCP servers without SDK code changes. + +**Unified Tool Interface:** Wrapping MCP tools in `ToolDefinition` makes them indistinguishable from native tools. Agents use the same interface regardless of tool source. + +**FastMCP Foundation:** Building on FastMCP (MCP SDK for Python) provides battle-tested client implementation, protocol compliance, and ongoing updates as MCP evolves. + +**Annotation Support:** Exposing MCP hints (readOnly, destructive) enables intelligent security analysis and user confirmation flows based on tool characteristics. + +**Lifecycle Management:** Automatic spawn/cleanup of MCP servers in conversation lifecycle ensures resources are properly managed without manual bookkeeping. + +## See Also + +- **[Tool System](/sdk/arch/tool-system)** - How MCP tools integrate with tool framework +- **[Skill Architecture](/sdk/arch/skill)** - Embedding MCP configs in repository skills +- **[Security](/sdk/arch/security)** - How MCP annotations inform risk assessment +- **[MCP Guide](/sdk/guides/mcp)** - Using MCP tools in applications +- **[FastMCP Documentation](https://gofastmcp.com/)** - Underlying MCP client library + +### Overview +Source: https://docs.openhands.dev/sdk/arch/overview.md + +The **OpenHands Software Agent SDK** provides a unified, type-safe framework for building and deploying AI agents—from local experiments to full production systems, focused on **statelessness**, **composability**, and **clear boundaries** between research and deployment. + +Check [this document](/sdk/arch/design) for the core design principles that guided its architecture. + +## Relationship with OpenHands Applications + +The Software Agent SDK serves as the **source of truth for agents** in OpenHands. The [OpenHands repository](https://github.com/OpenHands/OpenHands) provides interfaces—web app, CLI, and cloud—that consume the SDK APIs. This architecture ensures consistency and enables flexible integration patterns. +- **Software Agent SDK = foundation.** The SDK defines all core components: agents, LLMs, conversations, tools, workspaces, events, and security policies. +- **Interfaces reuse SDK objects.** The OpenHands GUI or CLI hydrate SDK components from persisted settings and orchestrate execution through SDK APIs. +- **Consistent configuration.** Whether you launch an agent programmatically or via the OpenHands GUI, the supported parameters and defaults come from the SDK. + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 50}} }%% +graph TB + subgraph Interfaces["OpenHands Interfaces"] + UI[OpenHands GUI
React frontend] + CLI[OpenHands CLI
Command-line interface] + Custom[Your Custom Client
Automations & workflows] + end + + SDK[Software Agent SDK
openhands.sdk + tools + workspace] + + subgraph External["External Services"] + LLM[LLM Providers
OpenAI, Anthropic, etc.] + Runtime[Runtime Services
Docker, Remote API, etc.] + end + + UI --> SDK + CLI --> SDK + Custom --> SDK + + SDK --> LLM + SDK --> Runtime + + classDef interface fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef sdk fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef external fill:#fff4df,stroke:#b7791f,stroke-width:2px + + class UI,CLI,Custom interface + class SDK sdk + class LLM,Runtime external +``` + + +## Four-Package Architecture + +The agent-sdk is organized into four distinct Python packages: + +| Package | What It Does | When You Need It | +|---------|-------------|------------------| +| **openhands.sdk** | Core agent framework + base workspace classes | Always (required) | +| **openhands.tools** | Pre-built tools (bash, file editing, etc.) | Optional - provides common tools | +| **openhands.workspace** | Extended workspace implementations (Docker, remote) | Optional - extends SDK's base classes | +| **openhands.agent_server** | Multi-user API server | Optional - used by workspace implementations | + +### Two Deployment Modes + +The SDK supports two deployment architectures depending on your needs: + +#### Mode 1: Local Development + +**Installation:** Just install `openhands-sdk` + `openhands-tools` + +```bash +pip install openhands-sdk openhands-tools +``` + +**Architecture:** + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart LR + SDK["openhands.sdk
Agent · LLM · Conversation
+ LocalWorkspace"]:::sdk + Tools["openhands.tools
BashTool · FileEditor · GrepTool · …"]:::tools + + SDK -->|uses| Tools + + classDef sdk fill:#e8f3ff,stroke:#2b6cb0,color:#0f2a45,stroke-width:2px,rx:8,ry:8 + classDef tools fill:#e9f9ef,stroke:#2f855a,color:#14532d,stroke-width:2px,rx:8,ry:8 +``` + +- `LocalWorkspace` included in SDK (no extra install) +- Everything runs in one process +- Perfect for prototyping and simple use cases +- Quick setup, no Docker required + +#### Mode 2: Production / Sandboxed + +**Installation:** Install all 4 packages + +```bash +pip install openhands-sdk openhands-tools openhands-workspace openhands-agent-server +``` + +**Architecture:** + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 20, "rankSpacing": 30}} }%% +flowchart LR + + WSBase["openhands.sdk
Base Classes:
Workspace · Local · Remote"]:::sdk + + subgraph WS[" "] + direction LR + Docker["openhands.workspace DockerWorkspace
extends RemoteWorkspace"]:::ws + Remote["openhands.workspace RemoteAPIWorkspace
extends RemoteWorkspace"]:::ws + end + + Server["openhands.agent_server
FastAPI + WebSocket"]:::server + Agent["openhands.sdk
Agent · LLM · Conversation"]:::sdk + Tools["openhands.tools
BashTool · FileEditor · …"]:::tools + + WSBase -.->|extended by| Docker + WSBase -.->|extended by| Remote + Docker -->|spawns container with| Server + Remote -->|connects via HTTP to| Server + Server -->|runs| Agent + Agent -->|uses| Tools + + classDef sdk fill:#e8f3ff,stroke:#2b6cb0,color:#0f2a45,stroke-width:1.1px,rx:8,ry:8 + classDef ws fill:#fff4df,stroke:#b7791f,color:#5b3410,stroke-width:1.1px,rx:8,ry:8 + classDef server fill:#f3e8ff,stroke:#7c3aed,color:#3b2370,stroke-width:1.1px,rx:8,ry:8 + classDef tools fill:#e9f9ef,stroke:#2f855a,color:#14532d,stroke-width:1.1px,rx:8,ry:8 + + style WS stroke:#b7791f,stroke-width:1.5px,stroke-dasharray: 4 3,rx:8,ry:8,fill:none +``` + +- `RemoteWorkspace` auto-spawns agent-server in containers +- Sandboxed execution for security +- Multi-user deployments +- Distributed systems (e.g., Kubernetes) support + +
as Agent (local/container/remote) + Tool-->>Agent: Observation + Agent->>LLM: Got result, continue? + LLM-->>Agent: Done + Agent-->>Conversation: Update state + Conversation-->>You: "File created!" +``` + +**Key takeaway:** The agent orchestrates the reasoning-action loop—calling the LLM for decisions and executing tools to perform actions. + +### Deployment Flexibility + +The same agent code runs in different environments by swapping workspace configuration: + +```mermaid +graph TB + subgraph "Your Code (Unchanged)" + Code["Agent + Tools + LLM"] + end + + subgraph "Deployment Options" + Local["Local
Direct execution"] + Docker["Docker
Containerized"] + Remote["Remote
Multi-user server"] + end + + Code -->|LocalWorkspace| Local + Code -->|DockerWorkspace| Docker + Code -->|RemoteAPIWorkspace| Remote + + style Code fill:#e1f5fe + style Local fill:#e8f5e8 + style Docker fill:#e8f5e8 + style Remote fill:#e8f5e8 +``` + +## Next Steps + +### Get Started +- [Getting Started](/sdk/getting-started) – Build your first agent +- [Hello World](/sdk/guides/hello-world) – Minimal example + +### Explore Components + +**SDK Package:** +- [Agent](/sdk/arch/agent) – Core reasoning-action loop +- [Conversation](/sdk/arch/conversation) – State management and lifecycle +- [LLM](/sdk/arch/llm) – Language model integration +- [Tool System](/sdk/arch/tool-system) – Action/Observation/Executor pattern +- [Events](/sdk/arch/events) – Typed event framework +- [Workspace](/sdk/arch/workspace) – Base workspace architecture + +**Tools Package:** +- See [`openhands-tools/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-tools) source code for implementation details + +**Workspace Package:** +- See [`openhands-workspace/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace) source code for implementation details + +**Agent Server:** +- See [`openhands-agent-server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server) source code for implementation details + +### Deploy +- [Remote Server](/sdk/guides/agent-server/overview) – Deploy remotely +- [Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox) – Container setup +- [API Sandboxed Server](/sdk/guides/agent-server/api-sandbox) – Hosted runtime service +- [Local Agent Server](/sdk/guides/agent-server/local-server) – In-process server + +### Source Code +- [`openhands/sdk/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk) – Core framework +- [`openhands/tools/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-tools/openhands/tools) – Pre-built tools +- [`openhands/workspace/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace/openhands/workspace) – Workspaces +- [`openhands/agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server/openhands/agent_server) – HTTP server +- [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples) – Working examples + +### SDK Package +Source: https://docs.openhands.dev/sdk/arch/sdk.md + +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 + +### Security +Source: https://docs.openhands.dev/sdk/arch/security.md + +The **Security** system evaluates agent actions for potential risks before execution. It provides pluggable security analyzers that assess action risk levels and enforce confirmation policies based on security characteristics. + +**Source:** [`openhands-sdk/penhands/sdk/security/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/security) + +## Core Responsibilities + +The Security system has four primary responsibilities: + +1. **Risk Assessment** - Capture and validate LLM-provided risk levels for actions +2. **Confirmation Policy** - Determine when user approval is required based on risk +3. **Action Validation** - Enforce security policies before execution +4. **Audit Trail** - Record security decisions in event history + +## Architecture + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 25, "rankSpacing": 50}} }%% +flowchart TB + subgraph Interface["Abstract Interface"] + Base["SecurityAnalyzerBase
Abstract analyzer"] + end + + subgraph Implementations["Concrete Analyzers"] + LLM["LLMSecurityAnalyzer
Inline risk prediction"] + NoOp["NoOpSecurityAnalyzer
No analysis"] + end + + subgraph Risk["Risk Levels"] + Low["LOW
Safe operations"] + Medium["MEDIUM
Moderate risk"] + High["HIGH
Dangerous ops"] + Unknown["UNKNOWN
Unanalyzed"] + end + + subgraph Policy["Confirmation Policy"] + Check["should_require_confirmation()"] + Mode["Confirmation Mode"] + Decision["Require / Allow"] + end + + Base --> LLM + Base --> NoOp + + Implementations --> Low + Implementations --> Medium + Implementations --> High + Implementations --> Unknown + + Low --> Check + Medium --> Check + High --> Check + Unknown --> Check + + Check --> Mode + Mode --> Decision + + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px + classDef danger fill:#ffe8e8,stroke:#dc2626,stroke-width:2px + + class Base primary + class LLM secondary + class High danger + class Check tertiary +``` + +### Key Components + +| Component | Purpose | Design | +|-----------|---------|--------| +| **[`SecurityAnalyzerBase`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/analyzer.py)** | Abstract interface | Defines `security_risk()` contract | +| **[`LLMSecurityAnalyzer`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/llm_analyzer.py)** | Inline risk assessment | Returns LLM-provided risk from action arguments | +| **[`NoOpSecurityAnalyzer`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/analyzer.py)** | Passthrough analyzer | Always returns UNKNOWN | +| **[`SecurityRisk`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/risk.py)** | Risk enum | LOW, MEDIUM, HIGH, UNKNOWN | +| **[`ConfirmationPolicy`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/confirmation_policy.py)** | Decision logic | Maps risk levels to confirmation requirements | + +## Risk Levels + +Security analyzers return one of four risk levels: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart TB + Action["ActionEvent"] + Analyze["Security Analyzer"] + + subgraph Levels["Risk Levels"] + Low["LOW
Read-only, safe"] + Medium["MEDIUM
Modify files"] + High["HIGH
Delete, execute"] + Unknown["UNKNOWN
Not analyzed"] + end + + Action --> Analyze + Analyze --> Low + Analyze --> Medium + Analyze --> High + Analyze --> Unknown + + style Low fill:#d1fae5,stroke:#10b981,stroke-width:2px + style Medium fill:#fef3c7,stroke:#f59e0b,stroke-width:2px + style High fill:#ffe8e8,stroke:#dc2626,stroke-width:2px + style Unknown fill:#f3f4f6,stroke:#6b7280,stroke-width:2px +``` + +### Risk Level Definitions + +| Level | Characteristics | Examples | +|-------|----------------|----------| +| **LOW** | Read-only, no state changes | File reading, directory listing, search | +| **MEDIUM** | Modifies user data | File editing, creating files, API calls | +| **HIGH** | Dangerous operations | File deletion, system commands, privilege escalation | +| **UNKNOWN** | Not analyzed or indeterminate | Complex commands, ambiguous operations | + +## Security Analyzers + +### LLMSecurityAnalyzer + +Leverages the LLM's inline risk assessment during action generation: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + Schema["Tool Schema
+ security_risk param"] + LLM["LLM generates action
with security_risk"] + ToolCall["Tool Call Arguments
{command: 'rm -rf', security_risk: 'HIGH'}"] + Extract["Extract security_risk
from arguments"] + ActionEvent["ActionEvent
with security_risk set"] + Analyzer["LLMSecurityAnalyzer
returns security_risk"] + + Schema --> LLM + LLM --> ToolCall + ToolCall --> Extract + Extract --> ActionEvent + ActionEvent --> Analyzer + + style Schema fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Extract fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Analyzer fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Analysis Process:** + +1. **Schema Enhancement:** A required `security_risk` parameter is added to each tool's schema +2. **LLM Generation:** The LLM generates tool calls with `security_risk` as part of the arguments +3. **Risk Extraction:** The agent extracts the `security_risk` value from the tool call arguments +4. **ActionEvent Creation:** The security risk is stored on the `ActionEvent` +5. **Analyzer Query:** `LLMSecurityAnalyzer.security_risk()` returns the pre-assigned risk level +6. **No Additional LLM Calls:** Risk assessment happens inline—no separate analysis step + +**Example Tool Call:** +```json +{ + "name": "execute_bash", + "arguments": { + "command": "rm -rf /tmp/cache", + "security_risk": "HIGH" + } +} +``` + +The LLM reasons about risk in context when generating the action, eliminating the need for a separate security analysis call. + +**Configuration:** +- **Enabled When:** A `LLMSecurityAnalyzer` is configured for the agent +- **Schema Modification:** Automatically adds `security_risk` field to non-read-only tools +- **Zero Overhead:** No additional LLM calls or latency beyond normal action generation + +### NoOpSecurityAnalyzer + +Passthrough analyzer that skips analysis: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Action["ActionEvent"] + NoOp["NoOpSecurityAnalyzer"] + Unknown["SecurityRisk.UNKNOWN"] + + Action --> NoOp --> Unknown + + style NoOp fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px +``` + +**Use Case:** Development, trusted environments, or when confirmation mode handles all actions + +## Confirmation Policy + +The confirmation policy determines when user approval is required. There are three policy implementations: + +**Source:** [`confirmation_policy.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/confirmation_policy.py) + +### Policy Types + +| Policy | Behavior | Use Case | +|--------|----------|----------| +| **[`AlwaysConfirm`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/confirmation_policy.py#L27-L32)** | Requires confirmation for **all** actions | Maximum safety, interactive workflows | +| **[`NeverConfirm`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/confirmation_policy.py#L35-L40)** | Never requires confirmation | Fully autonomous agents, trusted environments | +| **[`ConfirmRisky`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/confirmation_policy.py#L43-L62)** | Configurable risk-based policy | Balanced approach, production use | + +### ConfirmRisky (Default Policy) + +The most flexible policy with configurable thresholds: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + Risk["SecurityRisk"] + CheckUnknown{"Risk ==
UNKNOWN?"} + UseConfirmUnknown{"confirm_unknown
setting?"} + CheckThreshold{"risk.is_riskier
(threshold)?"} + + Confirm["Require Confirmation"] + Allow["Allow Execution"] + + Risk --> CheckUnknown + CheckUnknown -->|Yes| UseConfirmUnknown + CheckUnknown -->|No| CheckThreshold + + UseConfirmUnknown -->|True| Confirm + UseConfirmUnknown -->|False| Allow + + CheckThreshold -->|Yes| Confirm + CheckThreshold -->|No| Allow + + style CheckUnknown fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Confirm fill:#ffe8e8,stroke:#dc2626,stroke-width:2px + style Allow fill:#d1fae5,stroke:#10b981,stroke-width:2px +``` + +**Configuration:** +- **`threshold`** (default: `HIGH`) - Risk level at or above which confirmation is required + - Cannot be set to `UNKNOWN` + - Uses reflexive comparison: `risk.is_riskier(threshold)` returns `True` if `risk >= threshold` +- **`confirm_unknown`** (default: `True`) - Whether `UNKNOWN` risk requires confirmation + +### Confirmation Rules by Policy + +#### ConfirmRisky with threshold=HIGH (Default) + +| Risk Level | `confirm_unknown=True` (default) | `confirm_unknown=False` | +|------------|----------------------------------|-------------------------| +| **LOW** | ✅ Allow | ✅ Allow | +| **MEDIUM** | ✅ Allow | ✅ Allow | +| **HIGH** | 🔒 Require confirmation | 🔒 Require confirmation | +| **UNKNOWN** | 🔒 Require confirmation | ✅ Allow | + +#### ConfirmRisky with threshold=MEDIUM + +| Risk Level | `confirm_unknown=True` | `confirm_unknown=False` | +|------------|------------------------|-------------------------| +| **LOW** | ✅ Allow | ✅ Allow | +| **MEDIUM** | 🔒 Require confirmation | 🔒 Require confirmation | +| **HIGH** | 🔒 Require confirmation | 🔒 Require confirmation | +| **UNKNOWN** | 🔒 Require confirmation | ✅ Allow | + +#### ConfirmRisky with threshold=LOW + +| Risk Level | `confirm_unknown=True` | `confirm_unknown=False` | +|------------|------------------------|-------------------------| +| **LOW** | 🔒 Require confirmation | 🔒 Require confirmation | +| **MEDIUM** | 🔒 Require confirmation | 🔒 Require confirmation | +| **HIGH** | 🔒 Require confirmation | 🔒 Require confirmation | +| **UNKNOWN** | 🔒 Require confirmation | ✅ Allow | + +**Key Rules:** +- **Risk comparison** is **reflexive**: `HIGH.is_riskier(HIGH)` returns `True` +- **UNKNOWN handling** is configurable via `confirm_unknown` flag +- **Threshold cannot be UNKNOWN** - validated at policy creation time + + +## Component Relationships + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Security["Security Analyzer"] + Agent["Agent"] + Conversation["Conversation"] + Tools["Tools"] + MCP["MCP Tools"] + + Agent -->|Validates actions| Security + Security -->|Checks| Tools + Security -->|Uses hints| MCP + Conversation -->|Pauses for confirmation| Agent + + style Security fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Agent fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Conversation fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Relationship Characteristics:** +- **Agent → Security**: Validates actions before execution +- **Security → Tools**: Examines tool characteristics (annotations) +- **Security → MCP**: Uses MCP hints for risk assessment +- **Conversation → Agent**: Pauses for user confirmation when required +- **Optional Component**: Security analyzer can be disabled for trusted environments + +## See Also + +- **[Agent Architecture](/sdk/arch/agent)** - How agents use security analyzers +- **[Tool System](/sdk/arch/tool-system)** - Tool annotations and metadata; includes MCP tool hints +- **[Security Guide](/sdk/guides/security)** - Configuring security policies + +### Skill +Source: https://docs.openhands.dev/sdk/arch/skill.md + +The **Skill** system provides a mechanism for injecting reusable, specialized knowledge into agent context. Skills use trigger-based activation to determine when they should be included in the agent's prompt. + +**Source:** [`openhands/sdk/context/skills/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/context/skills) + +## Core Responsibilities + +The Skill system has four primary responsibilities: + +1. **Context Injection** - Add specialized prompts to agent context based on triggers +2. **Trigger Evaluation** - Determine when skills should activate (always, keyword, task) +3. **MCP Integration** - Load MCP tools associated with repository skills +4. **Third-Party Support** - Parse `.cursorrules`, `agents.md`, and other skill formats + +## Architecture + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 25, "rankSpacing": 35}} }%% +flowchart TB + subgraph Types["Skill Types"] + Repo["Repository Skill
trigger: None"] + Knowledge["Knowledge Skill
trigger: KeywordTrigger"] + Task["Task Skill
trigger: TaskTrigger"] + end + + subgraph Triggers["Trigger Evaluation"] + Always["Always Active
Repository guidelines"] + Keyword["Keyword Match
String matching on user messages"] + TaskMatch["Keyword Match + Inputs
Same as KeywordTrigger + user inputs"] + end + + subgraph Content["Skill Content"] + Markdown["Markdown with Frontmatter"] + MCPTools["MCP Tools Config
Repo skills only"] + Inputs["Input Metadata
Task skills only"] + end + + subgraph Integration["Agent Integration"] + Context["Agent Context"] + Prompt["System Prompt"] + end + + Repo --> Always + Knowledge --> Keyword + Task --> TaskMatch + + Always --> Markdown + Keyword --> Markdown + TaskMatch --> Markdown + + Repo -.->|Optional| MCPTools + Task -.->|Requires| Inputs + + Markdown --> Context + MCPTools --> Context + Context --> Prompt + + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px + + class Repo,Knowledge,Task primary + class Always,Keyword,TaskMatch secondary + class Context tertiary +``` + +### Key Components + +| Component | Purpose | Design | +|-----------|---------|--------| +| **[`Skill`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/skill.py)** | Core skill model | Pydantic model with name, content, trigger | +| **[`KeywordTrigger`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/trigger.py)** | Keyword-based activation | String matching on user messages | +| **[`TaskTrigger`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/trigger.py)** | Task-based activation | Special type of KeywordTrigger for skills with user inputs | +| **[`InputMetadata`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/types.py)** | Task input parameters | Defines user inputs for task skills | +| **Skill Loader** | File parsing | Reads markdown with frontmatter, validates schema | + +## Skill Types + +### Repository Skills + +Always-active, repository-specific guidelines. + +**Recommended:** put these permanent instructions in `AGENTS.md` (and optionally `GEMINI.md` / `CLAUDE.md`) at the repo root. + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart LR + File["AGENTS.md"] + Parse["Parse Frontmatter"] + Skill["Skill(trigger=None)"] + Context["Always in Context"] + + File --> Parse + Parse --> Skill + Skill --> Context + + style Skill fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Context fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Characteristics:** +- **Trigger:** `None` (always active) +- **Purpose:** Project conventions, coding standards, architecture rules +- **MCP Tools:** Can include MCP tool configuration +- **Location:** `AGENTS.md` (recommended) and/or `.agents/skills/*.md` (supported) + +**Example Files (permanent context):** +- `AGENTS.md` - General agent instructions +- `GEMINI.md` - Gemini-specific instructions +- `CLAUDE.md` - Claude-specific instructions + +**Other supported formats:** +- `.cursorrules` - Cursor IDE guidelines +- `agents.md` / `agent.md` - General agent instructions + +### Knowledge Skills + +Keyword-triggered skills for specialized domains: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + User["User Message"] + Check["Check Keywords"] + Match{"Match?"} + Activate["Activate Skill"] + Skip["Skip Skill"] + Context["Add to Context"] + + User --> Check + Check --> Match + Match -->|Yes| Activate + Match -->|No| Skip + Activate --> Context + + style Check fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Activate fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Characteristics:** +- **Trigger:** `KeywordTrigger` with regex patterns +- **Purpose:** Domain-specific knowledge (e.g., "kubernetes", "machine learning") +- **Activation:** Keywords detected in user messages +- **Location:** System or user-defined knowledge base + +**Trigger Example:** +```yaml +--- +name: kubernetes +trigger: + type: keyword + keywords: ["kubernetes", "k8s", "kubectl"] +--- +``` + +### Task Skills + +Keyword-triggered skills with structured inputs for guided workflows: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + User["User Message"] + Match{"Keyword
Match?"} + Inputs["Collect User Inputs"] + Template["Apply Template"] + Context["Add to Context"] + Skip["Skip Skill"] + + User --> Match + Match -->|Yes| Inputs + Match -->|No| Skip + Inputs --> Template + Template --> Context + + style Match fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Template fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Characteristics:** +- **Trigger:** `TaskTrigger` (a special type of KeywordTrigger for skills with user inputs) +- **Activation:** Keywords/triggers detected in user messages (same matching logic as KeywordTrigger) +- **Purpose:** Guided workflows (e.g., bug fixing, feature implementation) +- **Inputs:** User-provided parameters (e.g., bug description, acceptance criteria) +- **Location:** System-defined or custom task templates + +**Trigger Example:** +```yaml +--- +name: bug_fix +triggers: ["/bug_fix", "fix bug", "bug report"] +inputs: + - name: bug_description + description: "Describe the bug" + required: true +--- +``` + +**Note:** TaskTrigger uses the same keyword matching mechanism as KeywordTrigger. The distinction is semantic - TaskTrigger is used for skills that require structured user inputs, while KeywordTrigger is for knowledge-based skills. + +## Trigger Evaluation + +Skills are evaluated at different points in the agent lifecycle: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + Start["Agent Step Start"] + + Repo["Check Repository Skills
trigger: None"] + AddRepo["Always Add to Context"] + + Message["Check User Message"] + Keyword["Match Keyword Triggers"] + AddKeyword["Add Matched Skills"] + + TaskType["Check Task Type"] + TaskMatch["Match Task Triggers"] + AddTask["Add Task Skill"] + + Build["Build Agent Context"] + + Start --> Repo + Repo --> AddRepo + + Start --> Message + Message --> Keyword + Keyword --> AddKeyword + + Start --> TaskType + TaskType --> TaskMatch + TaskMatch --> AddTask + + AddRepo --> Build + AddKeyword --> Build + AddTask --> Build + + style Repo fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Keyword fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style TaskMatch fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Evaluation Rules:** + +| Trigger Type | Evaluation Point | Activation Condition | +|--------------|------------------|----------------------| +| **None** | Every step | Always active | +| **KeywordTrigger** | On user message | Keyword/string match in message | +| **TaskTrigger** | On user message | Keyword/string match in message (same as KeywordTrigger) | + +**Note:** Both KeywordTrigger and TaskTrigger use identical string matching logic. TaskTrigger is simply a semantic variant used for skills that include user input parameters. + +## MCP Tool Integration + +Repository skills can include MCP tool configurations: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Skill["Repository Skill"] + MCPConfig["mcp_tools Config"] + Client["MCP Client"] + Tools["Tool Registry"] + + Skill -->|Contains| MCPConfig + MCPConfig -->|Spawns| Client + Client -->|Registers| Tools + + style Skill fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style MCPConfig fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Tools fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**MCP Configuration Format:** + +Skills can embed MCP server configuration following the [FastMCP format](https://gofastmcp.com/clients/client#configuration-format): + +```yaml +--- +name: repo_skill +mcp_tools: + mcpServers: + filesystem: + command: "npx" + args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"] +--- +``` + +**Workflow:** +1. **Load Skill:** Parse markdown file with frontmatter +2. **Extract MCP Config:** Read `mcp_tools` field +3. **Spawn MCP Servers:** Create MCP clients for each server +4. **Register Tools:** Add MCP tools to agent's tool registry +5. **Inject Context:** Add skill content to agent prompt + +## Skill File Format + +Skills are defined in markdown files with YAML frontmatter: + +```markdown +--- +name: skill_name +trigger: + type: keyword + keywords: ["pattern1", "pattern2"] +--- + +# Skill Content + +This is the instruction text that will be added to the agent's context. +``` + +**Frontmatter Fields:** + +| Field | Required | Description | +|-------|----------|-------------| +| **name** | Yes | Unique skill identifier | +| **trigger** | Yes* | Activation trigger (`null` for always active) | +| **mcp_tools** | No | MCP server configuration (repo skills only) | +| **inputs** | No | User input metadata (task skills only) | + +*Repository skills use `trigger: null` (or omit trigger field) + +## Component Relationships + +### How Skills Integrate + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Skills["Skill System"] + Context["Agent Context"] + Agent["Agent"] + MCP["MCP Client"] + + Skills -->|Injects content| Context + Skills -.->|Spawns tools| MCP + Context -->|System prompt| Agent + MCP -->|Tool| Agent + + style Skills fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Context fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Agent fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Relationship Characteristics:** +- **Skills → Agent Context**: Active skills contribute their content to system prompt +- **Skills → MCP**: Repository skills can spawn MCP servers and register tools +- **Context → Agent**: Combined skill content becomes part of agent's instructions +- **Skills Lifecycle**: Loaded at conversation start, evaluated each step + +## See Also + +- **[Agent Architecture](/sdk/arch/agent)** - How agents use skills for context +- **[Tool System](/sdk/arch/tool-system#mcp-integration)** - MCP tool spawning and client management +- **[Context Management Guide](/sdk/guides/skill)** - Using skills in applications + +### Tool System & MCP +Source: https://docs.openhands.dev/sdk/arch/tool-system.md + +The **Tool System** provides a type-safe, extensible framework for defining agent capabilities. It standardizes how agents interact with external systems through a structured Action-Observation pattern with automatic validation and schema generation. + +**Source:** [`openhands-sdk/openhands/sdk/tool/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/tool) + +## Core Responsibilities + +The Tool System has four primary responsibilities: + +1. **Type Safety** - Enforce action/observation schemas via Pydantic models +2. **Schema Generation** - Auto-generate LLM-compatible tool descriptions from Pydantic schemas +3. **Execution Lifecycle** - Validate inputs, execute logic, wrap outputs +4. **Tool Registry** - Discover and resolve tools by name or pattern + +## Tool System + +### Architecture Overview + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 25, "rankSpacing": 50}} }%% +flowchart TB + subgraph Definition["Tool Definition"] + Action["Action
Input schema"] + Observation["Observation
Output schema"] + Executor["Executor
Business logic"] + end + + subgraph Framework["Tool Framework"] + Base["ToolBase
Abstract base"] + Impl["Tool Implementation
Concrete tool"] + Registry["Tool Registry
Spec → Tool"] + end + + Agent["Agent"] + LLM["LLM"] + ToolSpec["Tool Spec
name + params"] + + Base -.->|Extends| Impl + + ToolSpec -->|resolve_tool| Registry + Registry -->|Create instances| Impl + Impl -->|Available in| Agent + Impl -->|Generate schema| LLM + LLM -->|Generate tool call| Agent + Agent -->|Parse & validate| Action + Agent -->|Execute via Tool.\_\_call\_\_| Executor + Executor -->|Return| Observation + + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px + + class Base primary + class Action,Observation,Executor secondary + class Registry tertiary +``` + +### Key Components + +| Component | Purpose | Design | +|-----------|---------|--------| +| **[`ToolBase`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/tool.py)** | Abstract base class | Generic over Action and Observation types, defines abstract `create()` | +| **[`ToolDefinition`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/tool.py)** | Concrete tool class | Can be instantiated directly or subclassed for factory pattern | +| **[`Action`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/schema.py)** | Input model | Pydantic model with `visualize` property | +| **[`Observation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/schema.py)** | Output model | Pydantic model with `to_llm_content` property | +| **[`ToolExecutor`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/tool.py)** | Execution interface | ABC with `__call__()` method, optional `close()` | +| **[`ToolAnnotations`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/tool.py)** | Behavioral hints | MCP-spec hints (readOnly, destructive, idempotent, openWorld) | +| **[`Tool` (spec)](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/spec.py)** | Tool specification | Configuration object with name and params | +| **[`ToolRegistry`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/registry.py)** | Tool discovery | Resolves Tool specs to ToolDefinition instances | + +### Action-Observation Pattern + +The tool system follows a **strict input-output contract**: `Action → Observation`. The Agent layer wraps these in events for conversation management. + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + subgraph Agent["Agent Layer"] + ToolCall["MessageToolCall
from LLM"] + ParseJSON["Parse JSON
arguments"] + CreateAction["tool.action_from_arguments()
Pydantic validation"] + WrapAction["ActionEvent
wraps Action"] + WrapObs["ObservationEvent
wraps Observation"] + Error["AgentErrorEvent"] + end + + subgraph ToolSystem["Tool System"] + ActionType["Action
Pydantic model"] + ToolCall2["tool.\_\_call\_\_(action)
type-safe execution"] + Execute["ToolExecutor
business logic"] + ObsType["Observation
Pydantic model"] + end + + ToolCall --> ParseJSON + ParseJSON -->|Valid JSON| CreateAction + ParseJSON -->|Invalid JSON| Error + CreateAction -->|Valid| ActionType + CreateAction -->|Invalid| Error + ActionType --> WrapAction + ActionType --> ToolCall2 + ToolCall2 --> Execute + Execute --> ObsType + ObsType --> WrapObs + + style ToolSystem fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Agent fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style ActionType fill:#ddd6fe,stroke:#7c3aed,stroke-width:2px + style ObsType fill:#ddd6fe,stroke:#7c3aed,stroke-width:2px +``` + +**Tool System Boundary:** +- **Input**: `dict[str, Any]` (JSON arguments) → validated `Action` instance +- **Output**: `Observation` instance with structured result +- **No knowledge of**: Events, LLM messages, conversation state + +### Tool Definition + +Tools are defined using two patterns depending on complexity: + +#### Pattern 1: Direct Instantiation (Simple Tools) + +For stateless tools that don't need runtime configuration (e.g., `finish`, `think`): + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 20}} }%% +flowchart LR + Action["Define Action
with visualize"] + Obs["Define Observation
with to_llm_content"] + Exec["Define Executor
stateless logic"] + Tool["ToolDefinition(...,
executor=Executor())"] + + Action --> Tool + Obs --> Tool + Exec --> Tool + + style Tool fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px +``` + +**Components:** +1. **Action** - Pydantic model with `visualize` property for display +2. **Observation** - Pydantic model with `to_llm_content` property for LLM +3. **ToolExecutor** - Stateless executor with `__call__(action) → observation` +4. **ToolDefinition** - Direct instantiation with executor instance + +#### Pattern 2: Subclass with Factory (Stateful Tools) + +For tools requiring runtime configuration or persistent state (e.g., `execute_bash`, `file_editor`, `glob`): + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 20}} }%% +flowchart LR + Action["Define Action
with visualize"] + Obs["Define Observation
with to_llm_content"] + Exec["Define Executor
with \_\_init\_\_ and state"] + Subclass["class MyTool(ToolDefinition)
with create() method"] + Instance["Return [MyTool(...,
executor=instance)]"] + + Action --> Subclass + Obs --> Subclass + Exec --> Subclass + Subclass --> Instance + + style Instance fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Components:** +1. **Action/Observation** - Same as Pattern 1 +2. **ToolExecutor** - Stateful executor with `__init__()` for configuration and optional `close()` for cleanup +3. **MyTool(ToolDefinition)** - Subclass with `@classmethod create(conv_state, ...)` factory method +4. **Factory Method** - Returns sequence of configured tool instances + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart TB + subgraph Pattern1["Pattern 1: Direct Instantiation"] + P1A["Define Action/Observation
with visualize/to_llm_content"] + P1E["Define ToolExecutor
with \_\_call\_\_()"] + P1T["ToolDefinition(...,
executor=Executor())"] + end + + subgraph Pattern2["Pattern 2: Subclass with Factory"] + P2A["Define Action/Observation
with visualize/to_llm_content"] + P2E["Define Stateful ToolExecutor
with \_\_init\_\_() and \_\_call\_\_()"] + P2C["class MyTool(ToolDefinition)
@classmethod create()"] + P2I["Return [MyTool(...,
executor=instance)]"] + end + + P1A --> P1E + P1E --> P1T + + P2A --> P2E + P2E --> P2C + P2C --> P2I + + style P1T fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style P2I fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Key Design Elements:** + +| Component | Purpose | Requirements | +|-----------|---------|--------------| +| **Action** | Defines LLM-provided parameters | Extends `Action`, includes `visualize` property returning Rich Text | +| **Observation** | Defines structured output | Extends `Observation`, includes `to_llm_content` property returning content list | +| **ToolExecutor** | Implements business logic | Extends `ToolExecutor[ActionT, ObservationT]`, implements `__call__()` method | +| **ToolDefinition** | Ties everything together | Either instantiate directly (Pattern 1) or subclass with `create()` method (Pattern 2) | + +**When to Use Each Pattern:** + +| Pattern | Use Case | Examples | +|---------|----------|----------| +| **Direct Instantiation** | Stateless tools with no configuration needs | `finish`, `think`, simple utilities | +| **Subclass with Factory** | Tools requiring runtime state or configuration | `execute_bash`, `file_editor`, `glob`, `grep` | + +### Tool Annotations + +Tools include optional `ToolAnnotations` based on the [Model Context Protocol (MCP) spec](https://github.com/modelcontextprotocol/modelcontextprotocol) that provide behavioral hints to LLMs: + +| Field | Meaning | Examples | +|-------|---------|----------| +| `readOnlyHint` | Tool doesn't modify state | `glob` (True), `execute_bash` (False) | +| `destructiveHint` | May delete/overwrite data | `file_editor` (True), `task_tracker` (False) | +| `idempotentHint` | Repeated calls are safe | `glob` (True), `execute_bash` (False) | +| `openWorldHint` | Interacts beyond closed domain | `execute_bash` (True), `task_tracker` (False) | + +**Key Behaviors:** +- [LLM-based Security risk prediction](/sdk/guides/security) automatically added for tools with `readOnlyHint=False` +- Annotations help LLMs reason about tool safety and side effects + +### Tool Registry + +The registry enables **dynamic tool discovery** and instantiation from tool specifications: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + ToolSpec["Tool Spec
name + params"] + + subgraph Registry["Tool Registry"] + Resolver["Resolver
name → factory"] + Factory["Factory
create(params)"] + end + + Instance["Tool Instance
with executor"] + Agent["Agent"] + + ToolSpec -->|"resolve_tool(spec)"| Resolver + Resolver -->|Lookup factory| Factory + Factory -->|"create(**params)"| Instance + Instance -->|Used by| Agent + + style Registry fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Factory fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Resolution Workflow:** + +1. **[Tool (Spec)](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/spec.py)** - Configuration object with `name` (e.g., "BashTool") and `params` (e.g., `{"working_dir": "/workspace"}`) +2. **Resolver Lookup** - Registry finds the registered resolver for the tool name +3. **Factory Invocation** - Resolver calls the tool's `.create()` method with params and conversation state +4. **Instance Creation** - Tool instance(s) are created with configured executors +5. **Agent Usage** - Instances are added to the agent's tools_map for execution + +**Registration Types:** + +| Type | Registration | Resolver Behavior | +|------|-------------|-------------------| +| **Tool Instance** | `register_tool(name, instance)` | Returns the fixed instance (params not allowed) | +| **Tool Subclass** | `register_tool(name, ToolClass)` | Calls `ToolClass.create(**params, conv_state=state)` | +| **Factory Function** | `register_tool(name, factory)` | Calls `factory(**params, conv_state=state)` | + +### File Organization + +Tools follow a consistent file structure for maintainability: + +``` +openhands-tools/openhands/tools/my_tool/ +├── __init__.py # Export MyTool +├── definition.py # Action, Observation, MyTool(ToolDefinition) +├── impl.py # MyExecutor(ToolExecutor) +└── [other modules] # Tool-specific utilities +``` + +**File Responsibilities:** + +| File | Contains | Purpose | +|------|----------|---------| +| `definition.py` | Action, Observation, ToolDefinition subclass | Public API, schema definitions, factory method | +| `impl.py` | ToolExecutor implementation | Business logic, state management, execution | +| `__init__.py` | Tool exports | Package interface | + +**Benefits:** +- **Separation of Concerns** - Public API separate from implementation +- **Avoid Circular Imports** - Import `impl` only inside `create()` method +- **Consistency** - All tools follow same structure for discoverability + +**Example Reference:** See [`terminal/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-tools/openhands/tools/terminal) for complete implementation + + +## MCP Integration + +The tool system supports external tools via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). MCP tools are **configured separately from the tool registry** via the `mcp_config` field in `Agent` class and are automatically discovered from MCP servers during agent initialization. + +**Source:** [`openhands-sdk/openhands/sdk/mcp/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/mcp) + +### Architecture Overview + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 25, "rankSpacing": 50}} }%% +flowchart TB + subgraph External["External MCP Server"] + Server["MCP Server
stdio/HTTP"] + ExtTools["External Tools"] + end + + subgraph Bridge["MCP Integration Layer"] + MCPClient["MCPClient
Sync/Async bridge"] + Convert["Schema Conversion
MCP → MCPToolDefinition"] + MCPExec["MCPToolExecutor
Bridges to MCP calls"] + end + + subgraph Agent["Agent System"] + ToolsMap["tools_map
str -> ToolDefinition"] + AgentLogic["Agent Execution"] + end + + Server -.->|Spawns| ExtTools + MCPClient --> Server + Server --> Convert + Convert -->|create_mcp_tools| MCPExec + MCPExec -->|Added during
agent.initialize| ToolsMap + ToolsMap --> AgentLogic + AgentLogic -->|Tool call| MCPExec + MCPExec --> MCPClient + + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef external fill:#fff4df,stroke:#b7791f,stroke-width:2px + + class MCPClient primary + class Convert,MCPExec secondary + class Server,ExtTools external +``` + +### Key Components + +| Component | Purpose | Design | +|-----------|---------|--------| +| **[`MCPClient`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/client.py)** | MCP server connection | Extends FastMCP with sync/async bridge | +| **[`MCPToolDefinition`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/tool.py)** | Tool wrapper | Wraps MCP tools as SDK `ToolDefinition` with dynamic validation | +| **[`MCPToolExecutor`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/tool.py)** | Execution handler | Bridges agent actions to MCP tool calls via MCPClient | +| **[`MCPToolAction`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/definition.py)** | Generic action wrapper | Simple `dict[str, Any]` wrapper for MCP tool arguments | +| **[`MCPToolObservation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/definition.py)** | Result wrapper | Wraps MCP tool results as observations with content blocks | +| **[`_create_mcp_action_type()`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/tool.py)** | Dynamic schema | Runtime Pydantic model generated from MCP `inputSchema` for validation | + +### Sync/Async Bridge + +MCP protocol is asynchronous, but SDK tools execute synchronously. The bridge pattern in [client.py](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/client.py) solves this: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Sync["Sync Tool Execution"] + Bridge["call_async_from_sync()"] + Loop["Background Event Loop"] + Async["Async MCP Call"] + Result["Return Result"] + + Sync --> Bridge + Bridge --> Loop + Loop --> Async + Async --> Result + Result --> Sync + + style Bridge fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Loop fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Bridge Features:** +- **Background Event Loop** - Executes async code from sync contexts +- **Timeout Support** - Configurable timeouts for MCP operations +- **Error Handling** - Wraps MCP errors in observations +- **Connection Pooling** - Reuses connections across tool calls + +### Tool Discovery Flow + +**Source:** [`create_mcp_tools()`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/utils.py) | [`agent._initialize()`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/agent/base.py) + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart TB + Config["MCP Server Config
command + args"] + Spawn["Spawn Server Process
MCPClient"] + List["List Available Tools
client.list_tools()"] + + subgraph Convert["For Each MCP Tool"] + Store["Store MCP metadata
name, description, inputSchema"] + CreateExec["Create MCPToolExecutor
bound to tool + client"] + Def["Create MCPToolDefinition
generic MCPToolAction type"] + end + + Register["Add to Agent's tools_map
bypasses ToolRegistry"] + Ready["Tools Available
Dynamic models created on-demand"] + + Config --> Spawn + Spawn --> List + List --> Store + Store --> CreateExec + CreateExec --> Def + Def --> Register + Register --> Ready + + style Spawn fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Def fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Register fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Discovery Steps:** +1. **Spawn Server** - Launch MCP server via stdio protocol (using `MCPClient`) +2. **List Tools** - Call MCP `tools/list` endpoint to retrieve available tools +3. **Parse Schemas** - Extract tool names, descriptions, and `inputSchema` from MCP response +4. **Create Definitions** - For each tool, call `MCPToolDefinition.create()` which: + - Creates an `MCPToolExecutor` instance bound to the tool name and client + - Wraps the MCP tool metadata in `MCPToolDefinition` + - Uses generic `MCPToolAction` as the action type (NOT dynamic models yet) +5. **Add to Agent** - All `MCPToolDefinition` instances are added to agent's `tools_map` during `initialize()` (bypasses ToolRegistry) +6. **Lazy Validation** - Dynamic Pydantic models are generated lazily when: + - `action_from_arguments()` is called (argument validation) + - `to_openai_tool()` is called (schema export to LLM) + +**Schema Handling:** + +| MCP Schema | SDK Integration | When Used | +|------------|----------------|-----------| +| `name` | Tool name (stored in `MCPToolDefinition`) | Discovery, execution | +| `description` | Tool description for LLM | Discovery, LLM prompt | +| `inputSchema` | Stored in `mcp_tool.inputSchema` | Lazy model generation | +| `inputSchema` fields | Converted to Pydantic fields via `Schema.from_mcp_schema()` | Validation, schema export | +| `annotations` | Mapped to `ToolAnnotations` | Security analysis, LLM hints | + +### MCP Server Configuration + +MCP servers are configured via the `mcp_config` field on the `Agent` class. Configuration follows [FastMCP config format](https://gofastmcp.com/clients/client#configuration-format): + +```python +from openhands.sdk import Agent + +agent = Agent( + mcp_config={ + "mcpServers": { + "fetch": { + "command": "uvx", + "args": ["mcp-server-fetch"] + }, + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] + } + } + } +) +``` + +## Component Relationships + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart TB + subgraph Sources["Tool Sources"] + Native["Native Tools"] + MCP["MCP Tools"] + end + + Registry["Tool Registry
resolve_tool"] + ToolsMap["Agent.tools_map
Merged tool dict"] + + subgraph AgentSystem["Agent System"] + Agent["Agent Logic"] + LLM["LLM"] + end + + Security["Security Analyzer"] + Conversation["Conversation State"] + + Native -->|register_tool| Registry + Registry --> ToolsMap + MCP -->|create_mcp_tools| ToolsMap + ToolsMap -->|Provide schemas| LLM + Agent -->|Execute tools| ToolsMap + ToolsMap -.->|Action risk| Security + ToolsMap -.->|Read state| Conversation + + style ToolsMap fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Agent fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Security fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Relationship Characteristics:** +- **Native → Registry → tools_map**: Native tools resolved via `ToolRegistry` +- **MCP → tools_map**: MCP tools bypass registry, added directly during `initialize()` +- **tools_map → LLM**: Generate schemas describing all available capabilities +- **Agent → tools_map**: Execute actions, receive observations +- **tools_map → Conversation**: Read state for context-aware execution +- **tools_map → Security**: Tool annotations inform risk assessment + +## See Also + +- **[Agent Architecture](/sdk/arch/agent)** - How agents select and execute tools +- **[Events](/sdk/arch/events)** - ActionEvent and ObservationEvent structures +- **[Security Analyzer](/sdk/arch/security)** - Action risk assessment +- **[Skill Architecture](/sdk/arch/skill)** - Embedding MCP configs in repository skills +- **[Custom Tools Guide](/sdk/guides/custom-tools)** - Building your own tools +- **[FastMCP Documentation](https://gofastmcp.com/)** - Underlying MCP client library + +### Workspace +Source: https://docs.openhands.dev/sdk/arch/workspace.md + +The **Workspace** component abstracts execution environments for agent operations. It provides a unified interface for command execution and file operations across local processes, containers, and remote servers. + +**Source:** [`openhands/sdk/workspace/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/workspace) + +## Core Responsibilities + +The Workspace system has four primary responsibilities: + +1. **Execution Abstraction** - Unified interface for command execution across environments +2. **File Operations** - Upload, download, and manipulate files in workspace +3. **Resource Management** - Context manager protocol for setup/teardown +4. **Environment Isolation** - Separate agent execution from host system + +## Architecture + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 25, "rankSpacing": 60}} }%% +flowchart TB + subgraph Interface["Abstract Interface"] + Base["BaseWorkspace
Abstract base class"] + end + + subgraph Implementations["Concrete Implementations"] + Local["LocalWorkspace
Direct subprocess"] + Remote["RemoteWorkspace
HTTP API calls"] + end + + subgraph Operations["Core Operations"] + Command["execute_command()"] + Upload["file_upload()"] + Download["file_download()"] + Context["__enter__ / __exit__"] + end + + subgraph Targets["Execution Targets"] + Process["Local Process"] + Container["Docker Container"] + Server["Remote Server"] + end + + Base --> Local + Base --> Remote + + Base -.->|Defines| Operations + + Local --> Process + Remote --> Container + Remote --> Server + + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px + + class Base primary + class Local,Remote secondary + class Command,Upload tertiary +``` + +### Key Components + +| Component | Purpose | Design | +|-----------|---------|--------| +| **[`BaseWorkspace`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/base.py)** | Abstract interface | Defines execution and file operation contracts | +| **[`LocalWorkspace`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/local.py)** | Local execution | Subprocess-based command execution | +| **[`RemoteWorkspace`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/remote/base.py)** | Remote execution | HTTP API-based execution via agent-server | +| **[`CommandResult`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/models.py)** | Execution output | Structured result with stdout, stderr, exit_code | +| **[`FileOperationResult`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/models.py)** | File op outcome | Success status and metadata | + +## Workspace Types + +### Local vs Remote Execution + + +| Aspect | LocalWorkspace | RemoteWorkspace | +|--------|----------------|-----------------| +| **Execution** | Direct subprocess | HTTP → agent-server | +| **Isolation** | Process-level | Container/VM-level | +| **Performance** | Fast (no network) | Network overhead | +| **Security** | Host system access | Sandboxed | +| **Use Case** | Development, CLI | Production, web apps | + +## Core Operations + +### Command Execution + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%% +flowchart LR + Tool["Tool invokes
execute_command()"] + + Decision{"Workspace
type?"} + + LocalExec["subprocess.run()
Direct execution"] + RemoteExec["POST /command
HTTP API"] + + Result["CommandResult
stdout, stderr, exit_code"] + + Tool --> Decision + Decision -->|Local| LocalExec + Decision -->|Remote| RemoteExec + + LocalExec --> Result + RemoteExec --> Result + + style Decision fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style LocalExec fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style RemoteExec fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Command Result Structure:** + +| Field | Type | Description | +|-------|------|-------------| +| **stdout** | str | Standard output stream | +| **stderr** | str | Standard error stream | +| **exit_code** | int | Process exit code (0 = success) | +| **timeout** | bool | Whether command timed out | +| **duration** | float | Execution time in seconds | + +### File Operations + +| Operation | Local Implementation | Remote Implementation | +|-----------|---------------------|----------------------| +| **Upload** | `shutil.copy()` | `POST /file/upload` with multipart | +| **Download** | `shutil.copy()` | `GET /file/download` stream | +| **Result** | `FileOperationResult` | `FileOperationResult` | + +## Resource Management + +Workspaces use **context manager** for safe resource handling: + +**Lifecycle Hooks:** + +| Phase | LocalWorkspace | RemoteWorkspace | +|-------|----------------|-----------------| +| **Enter** | Create working directory | Connect to agent-server, verify | +| **Use** | Execute commands | Proxy commands via HTTP | +| **Exit** | No cleanup (persistent) | Disconnect, optionally stop container | + +## Remote Workspace Extensions + +The SDK provides remote workspace implementations in `openhands-workspace` package: + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 50}} }%% +flowchart TB + Base["RemoteWorkspace
SDK base class"] + + Docker["DockerWorkspace
Auto-spawn containers"] + API["RemoteAPIWorkspace
Connect to existing server"] + + Base -.->|Extended by| Docker + Base -.->|Extended by| API + + Docker -->|Creates| Container["Docker Container
with agent-server"] + API -->|Connects| Server["Remote Agent Server"] + + style Base fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Docker fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style API fill:#fff4df,stroke:#b7791f,stroke-width:2px +``` + +**Implementation Comparison:** + +| Type | Setup | Isolation | Use Case | +|------|-------|-----------|----------| +| **LocalWorkspace** | Immediate | Process | Development, trusted code | +| **DockerWorkspace** | Spawn container | Container | Multi-user, untrusted code | +| **RemoteAPIWorkspace** | Connect to URL | Remote server | Distributed systems, cloud | + +**Source:** +- **DockerWorkspace**: [`openhands-workspace/openhands/workspace/docker`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace/openhands/workspace/docker) +- **RemoteAPIWorkspace**: [`openhands-workspace/openhands/workspace/remote_api`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace/openhands/workspace/remote_api) + +## Component Relationships + +### How Workspace Integrates + +```mermaid +%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%% +flowchart LR + Workspace["Workspace"] + Conversation["Conversation"] + AgentServer["Agent Server"] + + Conversation -->|Configures| Workspace + Workspace -.->|Remote type| AgentServer + + style Workspace fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Conversation fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px +``` + +**Relationship Characteristics:** +- **Conversation → Workspace**: Conversation factory uses workspace type to select LocalConversation or RemoteConversation +- **Workspace → Agent Server**: RemoteWorkspace delegates operations to agent-server API +- **Tools Independence**: Tools run in the same environment as workspace + +## See Also + +- **[Conversation Architecture](/sdk/arch/conversation)** - How workspace type determines conversation implementation +- **[Agent Server](/sdk/arch/agent-server)** - Remote execution API +- **[Tool System](/sdk/arch/tool-system)** - Tools that use workspace for execution + +### FAQ +Source: https://docs.openhands.dev/sdk/faq.md + +## How do I use AWS Bedrock with the SDK? + +**Yes, the OpenHands SDK supports AWS Bedrock through LiteLLM.** + +Since LiteLLM requires `boto3` for Bedrock requests, you need to install it alongside the SDK. + +
+
+
+This approach achieves remarkable efficiency gains:
+- Up to **2x reduction** in per-turn API costs
+- **Consistent response times** even in long sessions
+- **Equivalent or better performance** on software engineering tasks
+
+Learn more about the implementation and benchmarks in our [blog post on context condensation](https://openhands.dev/blog/openhands-context-condensensation-for-more-efficient-ai-agents).
+
+### Extensibility
+
+The `LLMSummarizingCondenser` extends the `RollingCondenser` base class, which provides a framework for condensers that work with rolling conversation history. You can create custom condensers by extending base classes ([source code](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/base.py)):
+
+- **`RollingCondenser`** - For condensers that apply condensation to rolling history
+- **`CondenserBase`** - For more specialized condensation strategies
+
+This architecture allows you to implement custom condensation logic tailored to your specific needs while leveraging the SDK's conversation management infrastructure.
+
+
+### Setting Up Condensing
+
+Create a `LLMSummarizingCondenser` to manage the context.
+The condenser will automatically truncate conversation history when it exceeds max_size, and replaces the dropped events with an LLM-generated summary.
+
+This condenser triggers when there are more than `max_context_length` events in
+the conversation history, and always keeps the first `keep_first` events (system prompts,
+initial user messages) to preserve important context.
+
+```python focus={3-4} icon="python"
+from openhands.sdk.context import LLMSummarizingCondenser
+
+condenser = LLMSummarizingCondenser(
+ llm=llm.model_copy(update={"usage_id": "condenser"}), max_size=10, keep_first=2
+)
+
+# Agent with condenser
+agent = Agent(llm=llm, tools=tools, condenser=condenser)
+```
+
+### Ready-to-run example
+
+