OpenHands Software Agent SDK

The TerminalTool provides a persistent shell session (bash-compatible) for executing commands within the OpenHands SDK. Unlike single-command execution, this tool maintains state such as environment variables, virtual environments, and the current working directory between consecutive commands.

Key Features

• Persistent session: State is preserved across commands.
• Backend support: Uses tmux if available, otherwise falls back to a subprocess-based PTY.
• Configurable environment: Allows setting session-scoped environment variables that are not exposed to the LLM.
• Long-running commands: Supports soft timeouts and interrupts.
• Terminal reset: Ability to reset the session if it becomes unresponsive.

from openhands.sdk import Conversation
from openhands.tools.terminal.definition import TerminalTool, TerminalAction

conversation = Conversation()
tools = TerminalTool.create(conv_state=conversation.state)
terminal = tools[0]

# Execute a command
action = TerminalAction(command="echo 'Hello, World!'")
result = terminal.executor(action)
print(result.text)

The installation module is a generic, extension-type agnostic framework for installing, tracking, and loading extensions from local or remote sources.

It relies on two main components:

1. An extension type T: Any object that possesses name, version, and description attributes (typically a Pydantic BaseModel).
2. An InstallationInterface[T]: A loader implementation that defines how to load the extension type T from a specific directory.

The framework handles all other logic generically, including fetching, copying, metadata bookkeeping, and managing the enabled/disabled state.

from pathlib import Path
from pydantic import BaseModel
from openhands.sdk.extensions.installation import (
    InstallationInterface,
    InstallationManager,
)

class Widget(BaseModel):
    name: str
    version: str
    description: str

class WidgetLoader(InstallationInterface[Widget]):
    @staticmethod
    def load_from_dir(extension_dir: Path) -> Widget:
        return Widget.model_validate_json(
            (extension_dir / "widget.json").read_text()
        )

The web-researcher is a specialized subagent designed for researching documentation, API references, changelogs, and other publicly available web content. It returns a structured summary of findings accompanied by source URLs.

Available Interfaces

1. Tavily search (tavily_search): Use this as your first choice for fast, API-based web searches.
2. Fetch (fetch): A lightweight URL fetcher for grabbing text content from a specific URL without a full browser. Note: fetch respects robots.txt and may be blocked from sites that a browser can access.
3. Browser tools: A full browser for navigating, reading, and interacting with web UIs when simpler tools are insufficient.

name: web-researcher
model: inherit
description: >-
    USE THIS when you need to research information on the web — documentation,
    API references, changelogs, Stack Overflow answers, or any publicly available
    content. Returns a structured summary of findings with source URLs.
tools:
  - browser_tool_set
mcp_servers:
  fetch:
    command: uvx
    args: ["--with", "mcp==1.29.0", "mcp-server-fetch==2026.7.10"]
  tavily:
    command: npx
    args: ["-y", "tavily-mcp@0.2.1"]
    env:
      TAVILY_API_KEY: "${TAVILY_API_KEY}"

Context is the mechanism used to provide agents with skills and knowledge during a conversation. It is composed of two main parts:

1. AgentContext: The container that composes various skills and runtime context. You pass an AgentContext instance to an Agent to condition its behavior.
2. Skill: A unit of structured knowledge. Each skill is defined by a name, content, and a source, and is activated based on a trigger type:
   • trigger=None: The skill is always active and provides repository-wide context for all conversations.
   • KeywordTrigger: The skill activates only when specific keywords are detected in user messages.
   • TaskTrigger: The skill activates based on specific task-related conditions.

Additionally, AgentContext supports time awareness via current_datetime, which defaults to datetime.now().

from openhands.sdk.context import AgentContext, KeywordTrigger, Skill

agent_context = AgentContext(
    skills=[
        Skill(
            name="repo-guidelines",
            content="Repository-wide coding standards and best practices.",
            source="AGENTS.md",
            trigger=None,  # Always-active skill
        ),
        Skill(
            name="flarglebargle",
            content="If the user says flarglebargle, compliment them.",
            source="flarglebargle.md",
            trigger=KeywordTrigger(keywords=["flarglebargle"]),
        ),
    ],
)

The agent server can emit product-analytics events (e.g., agent_server.conversation_started) to PostHog or an HTTP endpoint. This is disabled by default.

Consent Model

Consent is managed via misc_settings.telemetry.consent (granted | denied | unset).

• Precedence: DO_NOT_TRACK=1 > OH_TELEMETRY_CONSENT (if mode is override) > misc_settings.telemetry.consent > OH_TELEMETRY_CONSENT (if mode is seed).
• Revocation: When consent is revoked, delivery stops immediately and queued events are discarded.

Exporters

• none: Default. No delivery.
• posthog: Requires OH_TELEMETRY_POSTHOG_API_KEY and the [posthog] pip extra.
• http: POSTs sanitized batches to OH_TELEMETRY_HTTP_ENDPOINT.

Privacy

Telemetry only sends allowlisted lifecycle/failure events. It never sends prompts, messages, file contents, secrets, or tracebacks. Magnitudes (like token counts or costs) are bucketed to prevent re-identification.