> ## Documentation Index > Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt > Use this file to discover all available pages before exploring further. # On Conversation Update > Webhook callback for when a conversation starts, pauses, resumes, or deletes. The ``ConversationInfo.agent`` field is an ``AgentBase`` discriminated union so both OpenHands (``Agent``) and ACP (``ACPAgent``) payloads are accepted on this single endpoint. ## OpenAPI ````yaml /openapi/openhands-cloud.json post /api/v1/webhooks/conversations openapi: 3.1.0 info: title: OpenHands description: 'OpenHands: Code Less, Make More' version: 0.0.1 servers: [] security: [] paths: /api/v1/webhooks/conversations: post: tags: - Webhooks summary: On Conversation Update description: >- Webhook callback for when a conversation starts, pauses, resumes, or deletes. The ``ConversationInfo.agent`` field is an ``AgentBase`` discriminated union so both OpenHands (``Agent``) and ACP (``ACPAgent``) payloads are accepted on this single endpoint. operationId: on_conversation_update_api_v1_webhooks_conversations_post requestBody: content: application/json: schema: $ref: '#/components/schemas/ConversationInfo' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Success' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: ConversationInfo: properties: id: type: string format: uuid title: Id description: Unique conversation ID workspace: $ref: '#/components/schemas/BaseWorkspace' description: >- Workspace used by the agent to execute commands and read/write files. Not the process working directory. persistence_dir: anyOf: - type: string - type: 'null' title: Persistence Dir description: >- Directory for persisting conversation state and events. If None, conversation will not be persisted. default: workspace/conversations max_iterations: type: integer exclusiveMinimum: 0 title: Max Iterations description: Maximum number of iterations the agent can perform in a single run. default: 500 stuck_detection: type: boolean title: Stuck Detection description: Whether to enable stuck detection for the agent. default: true execution_status: $ref: '#/components/schemas/ConversationExecutionStatus' default: idle confirmation_policy: $ref: '#/components/schemas/ConfirmationPolicyBase' default: kind: NeverConfirm security_analyzer: anyOf: - $ref: '#/components/schemas/SecurityAnalyzerBase' - type: 'null' description: Optional security analyzer to evaluate action risks. activated_knowledge_skills: items: type: string type: array title: Activated Knowledge Skills description: List of activated knowledge skills name invoked_skills: items: type: string type: array title: Invoked Skills description: >- Names of progressive-disclosure skills explicitly invoked via the `invoke_skill` tool. blocked_actions: additionalProperties: type: string type: object title: Blocked Actions description: Actions blocked by PreToolUse hooks, keyed by action ID blocked_messages: additionalProperties: type: string type: object title: Blocked Messages description: Messages blocked by UserPromptSubmit hooks, keyed by message ID last_user_message_id: anyOf: - type: string - type: 'null' title: Last User Message Id description: >- Most recent user MessageEvent id for hook block checks. Updated when user messages are emitted so Agent.step can pop blocked_messages without scanning the event log. If None, hook-blocked checks are skipped (legacy conversations). leaf_event_id: anyOf: - type: string - type: 'null' title: Leaf Event Id description: >- HEAD of the conversation tree: the parent of the next appended event. ``None`` means an empty tree (or, for pre-feature conversations, the linear tail). Moving it via ``navigate`` re-roots the active branch the agent runs on. stats: $ref: '#/components/schemas/ConversationStats' description: Conversation statistics for tracking LLM metrics secret_registry: $ref: '#/components/schemas/SecretRegistry' description: Registry for handling secrets and sensitive data agent_state: additionalProperties: true type: object title: Agent State description: >- Dictionary for agent-specific runtime state that persists across iterations. hook_config: anyOf: - $ref: '#/components/schemas/HookConfig-Input' - type: 'null' description: >- Hook configuration for this conversation. Includes definitions for PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, and Stop hooks. title: anyOf: - type: string - type: 'null' title: Title description: User-defined title for the conversation metrics: anyOf: - $ref: '#/components/schemas/MetricsSnapshot' - type: 'null' created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At forked_from_conversation_id: anyOf: - type: string format: uuid - type: 'null' title: Forked From Conversation Id description: >- ID of the conversation this one was forked from. ``None`` for conversations created directly (not via fork). forked_from_event_id: anyOf: - type: string - type: 'null' title: Forked From Event Id description: >- Event ID this conversation was forked at. ``None`` for non-forked conversations or whole-conversation forks. parent_conversation_id: anyOf: - type: string format: uuid - type: 'null' title: Parent Conversation Id description: >- ID of the conversation that owns this one. ``None`` for top-level conversations. sub_conversation_ids: items: type: string format: uuid type: array title: Sub Conversation Ids description: >- IDs of conversations naming this one as their parent. Derived from the server catalog; empty on webhook payloads. Name mirrors the Cloud API field. tags: additionalProperties: type: string type: object title: Tags description: >- Key-value tags for the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters. current_model_id: anyOf: - type: string - type: 'null' title: Current Model Id description: >- Model the agent is actually using for this session. For ACP agents, this is lifted off ``ACPAgent.current_model_id`` (populated from the ``models.currentModelId`` field on the ACP session response, or from ``acp_model`` when the caller forced an override). May be an opaque alias (e.g. claude-agent-acp's ``"default"``); match it against ``available_models`` to get a display label. ``None`` for older ACP servers that don't surface the field, or while the agent is still initializing. Native OpenHands agents leave this ``None`` — consumers should read ``agent.llm.model`` for those. available_models: items: $ref: '#/components/schemas/ACPModelInfo' type: array title: Available Models description: >- Models the ACP server offers for this session, lifted off ``ACPAgent.available_models`` (the ``models.availableModels`` field on the ACP session response). Each entry carries a ``model_id`` plus an optional ``name``/``description``. Surfaced verbatim so clients can render a model picker and resolve ``current_model_id`` to a display label themselves — the server does no name curation. Empty for ACP servers that don't surface the (UNSTABLE) capability and for native OpenHands agents. Client contract: ``current_model_id`` is NOT guaranteed to be a member — a forced ``acp_model`` override may name a model absent from the list — so treat a miss as 'show the raw id'. Some entries are opaque aliases whose human identity lives in ``description`` (e.g. claude-agent-acp's ``"default"`` -> ``"Opus 4.7 with 1M context · ..."``). supports_runtime_model_switch: type: boolean title: Supports Runtime Model Switch description: >- Whether a live, mid-conversation model switch will be attempted for this conversation — tells the inline picker whether to offer a live-switch control. Mirrors the SDK's switch gate: ``True`` for known switch-capable providers; ``False`` for unknown/custom ACP servers because their generic config writes are not guaranteed live-switch primitives. ``False`` for native OpenHands agents, for a known provider that declares no support, and before the conversation has started a session. default: false launched_agent_profile: anyOf: - $ref: '#/components/schemas/LaunchedAgentProfile' - type: 'null' description: >- Provenance snapshot of the agent profile that launched this conversation. Set at creation when the conversation was started via ``agent_profile_id``; ``None`` for conversations started directly with ``agent`` or ``agent_settings``. Clients use this to identify which agent profile is current without fragile settings-comparison. agent: $ref: '#/components/schemas/AgentBase' description: The agent running in the conversation. client_tools: items: $ref: '#/components/schemas/ClientToolSpec' type: array title: Client Tools description: >- Client-defined tool specs registered for this conversation. Surfaced so that a client re-attaching by conversation id can register the dynamic ClientAction_* action types before syncing persisted events, avoiding 'Unknown kind' deserialization errors. type: object required: - id - workspace - agent title: ConversationInfo description: >- Information about a conversation running locally without a Runtime sandbox. Success: properties: success: type: boolean title: Success default: true type: object title: Success HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError BaseWorkspace: oneOf: - $ref: '#/components/schemas/LocalWorkspace-Input' - $ref: '#/components/schemas/RemoteWorkspace' discriminator: propertyName: kind mapping: openhands__sdk__workspace__local__LocalWorkspace-Input__1: $ref: '#/components/schemas/LocalWorkspace-Input' openhands__sdk__workspace__remote__base__RemoteWorkspace-Input__1: $ref: '#/components/schemas/RemoteWorkspace' ConversationExecutionStatus: type: string enum: - idle - running - paused - waiting_for_confirmation - finished - error - stuck - deleting title: ConversationExecutionStatus description: Enum representing the current execution state of the conversation. ConfirmationPolicyBase: oneOf: - $ref: '#/components/schemas/AlwaysConfirm' - $ref: '#/components/schemas/ConfirmRisky' - $ref: '#/components/schemas/NeverConfirm' discriminator: propertyName: kind mapping: openhands__sdk__security__confirmation_policy__AlwaysConfirm-Input__1: $ref: '#/components/schemas/AlwaysConfirm' openhands__sdk__security__confirmation_policy__ConfirmRisky-Input__1: $ref: '#/components/schemas/ConfirmRisky' openhands__sdk__security__confirmation_policy__NeverConfirm-Input__1: $ref: '#/components/schemas/NeverConfirm' SecurityAnalyzerBase: oneOf: - $ref: '#/components/schemas/PatternSecurityAnalyzer' - $ref: '#/components/schemas/PolicyRailSecurityAnalyzer' - $ref: '#/components/schemas/EnsembleSecurityAnalyzer' - $ref: '#/components/schemas/GraySwanAnalyzer' - $ref: '#/components/schemas/LLMSecurityAnalyzer' - $ref: '#/components/schemas/ToolShieldLLMSecurityAnalyzer' discriminator: propertyName: kind mapping: openhands__sdk__security__defense_in_depth__pattern__PatternSecurityAnalyzer-Input__1: $ref: '#/components/schemas/PatternSecurityAnalyzer' openhands__sdk__security__defense_in_depth__policy_rails__PolicyRailSecurityAnalyzer-Input__1: $ref: '#/components/schemas/PolicyRailSecurityAnalyzer' openhands__sdk__security__ensemble__EnsembleSecurityAnalyzer-Input__1: $ref: '#/components/schemas/EnsembleSecurityAnalyzer' openhands__sdk__security__grayswan__analyzer__GraySwanAnalyzer-Input__1: $ref: '#/components/schemas/GraySwanAnalyzer' openhands__sdk__security__llm_analyzer__LLMSecurityAnalyzer-Input__1: $ref: '#/components/schemas/LLMSecurityAnalyzer' openhands__sdk__security__toolshield_llm_analyzer__ToolShieldLLMSecurityAnalyzer-Input__1: $ref: '#/components/schemas/ToolShieldLLMSecurityAnalyzer' ConversationStats: properties: usage_to_metrics: additionalProperties: $ref: '#/components/schemas/Metrics' type: object title: Usage To Metrics description: Active usage metrics tracked by the registry. type: object title: ConversationStats description: Track per-LLM usage metrics observed during conversations. SecretRegistry: properties: secret_sources: additionalProperties: $ref: '#/components/schemas/SecretSource-Input' type: object title: Secret Sources type: object title: SecretRegistry description: >- Manages secrets and injects them into bash commands when needed. The secret registry stores a mapping of secret keys to SecretSources that retrieve the actual secret values. When a bash command is about to be executed, it scans the command for any secret keys and injects the corresponding environment variables. Secret sources will redact / encrypt their sensitive values as appropriate when serializing, depending on the content of the context. If a context is present and contains a 'cipher' object, this is used for encryption. If it contains a boolean 'expose_secrets' flag set to True, secrets are dunped in plain text. Otherwise secrets are redacted. Additionally, it tracks the latest exported values to enable consistent masking even when callable secrets fail on subsequent calls. HookConfig-Input: properties: pre_tool_use: items: $ref: '#/components/schemas/HookMatcher-Input' type: array title: Pre Tool Use description: Hooks that run before tool execution post_tool_use: items: $ref: '#/components/schemas/HookMatcher-Input' type: array title: Post Tool Use description: Hooks that run after tool execution user_prompt_submit: items: $ref: '#/components/schemas/HookMatcher-Input' type: array title: User Prompt Submit description: Hooks that run when user submits a prompt session_start: items: $ref: '#/components/schemas/HookMatcher-Input' type: array title: Session Start description: Hooks that run when a session starts session_end: items: $ref: '#/components/schemas/HookMatcher-Input' type: array title: Session End description: Hooks that run when a session ends stop: items: $ref: '#/components/schemas/HookMatcher-Input' type: array title: Stop description: Hooks that run when the agent attempts to stop additionalProperties: false type: object title: HookConfig description: >- Configuration for all hooks. Hooks can be configured either by loading from `.openhands/hooks.json` or by directly instantiating with typed fields: # Direct instantiation with typed fields (recommended): config = HookConfig( pre_tool_use=[ HookMatcher( matcher="terminal", hooks=[HookDefinition(command="block_dangerous.sh")] ) ] ) # Load from JSON file: config = HookConfig.load(".openhands/hooks.json") MetricsSnapshot: properties: model_name: type: string title: Model Name description: Name of the model default: default accumulated_cost: type: number minimum: 0 title: Accumulated Cost description: Total accumulated cost, must be non-negative default: 0 max_budget_per_task: anyOf: - type: number - type: 'null' title: Max Budget Per Task description: Maximum budget per task accumulated_token_usage: anyOf: - $ref: '#/components/schemas/TokenUsage' - type: 'null' description: Accumulated token usage across all calls type: object title: MetricsSnapshot description: |- A snapshot of metrics at a point in time. Does not include lists of individual costs, latencies, or token usages. ACPModelInfo: properties: model_id: type: string title: Model Id description: >- Server-assigned model identifier. May be concrete (e.g. ``"gpt-5.5"``) or an opaque alias (e.g. ``"default"``, ``"auto"``). This is the value to pass back to the server to switch to this model. name: anyOf: - type: string - type: 'null' title: Name description: Human-readable label, e.g. ``"GPT-5.5"``. description: anyOf: - type: string - type: 'null' title: Description description: Optional longer description supplied by the server. type: object required: - model_id title: ACPModelInfo description: >- One model an ACP server offers for a session. A normalized, stable mirror of the ACP protocol's ``ModelInfo``. The protocol ``models`` capability is flagged **UNSTABLE**, so we re-map it into our own type at the SDK boundary rather than re-serializing the vendored ``acp.schema`` type onto the agent-server's public API — clients get a stable shape regardless of upstream protocol churn. Carries everything a client needs to render a picker and resolve a ``current_model_id`` to a display label *itself*; the SDK deliberately does no name curation. LaunchedAgentProfile: properties: agent_profile_id: type: string format: uuid title: Agent Profile Id description: Stable id of the agent profile that launched the conversation. revision: type: integer minimum: 0 title: Revision description: Revision of the agent profile at launch time. type: object required: - agent_profile_id - revision title: LaunchedAgentProfile description: >- Provenance snapshot recorded when an agent profile launches a conversation. Stored on ``StoredConversation`` and projected onto ``ConversationInfo`` so ts-client ``deriveSwitchPlan`` can identify which agent profile is current without fragile settings-comparison. See #3720. AgentBase: oneOf: - $ref: '#/components/schemas/ACPAgent' - $ref: '#/components/schemas/Agent' discriminator: propertyName: kind mapping: openhands__sdk__agent__acp_agent__ACPAgent-Input__1: $ref: '#/components/schemas/ACPAgent' openhands__sdk__agent__agent__Agent-Input__1: $ref: '#/components/schemas/Agent' ClientToolSpec: properties: name: type: string title: Name description: Unique tool name the agent will use to call this tool. description: type: string title: Description description: >- Description shown to the LLM explaining when and how to use this tool. parameters: additionalProperties: true type: object title: Parameters description: >- JSON Schema describing the tool's input parameters. Must be an object schema. annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: >- Optional MCP-style annotations for the tool. When omitted, the tool is treated conservatively (not read-only), so the agent is asked to predict a security risk before calling it. type: object required: - name - description title: ClientToolSpec description: |- A tool defined by the client, executed externally (not by the SDK). Clients pass these specs in ``POST /conversations`` to register tools whose execution is handled outside the SDK (e.g., by a frontend listening for ActionEvents over WebSocket). ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError LocalWorkspace-Input: properties: working_dir: type: string title: Working Dir description: >- The working directory for agent operations and tool execution. Accepts both string paths and Path objects. Path objects are automatically converted to strings. kind: type: string const: LocalWorkspace title: Kind type: object required: - working_dir title: LocalWorkspace description: >- 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: >>> workspace = LocalWorkspace(working_dir="/path/to/project") >>> with workspace: ... result = workspace.execute_command("ls -la") ... content = workspace.read_file("README.md") RemoteWorkspace: properties: working_dir: type: string title: Working Dir description: The working directory for agent operations and tool execution. host: type: string title: Host description: The remote host URL for the workspace. api_key: anyOf: - type: string - type: 'null' title: Api Key description: API key for authenticating with the remote host. read_timeout: type: number title: Read Timeout description: Timeout in seconds for reading operations of httpx.Client. default: 600 max_connections: anyOf: - type: integer - type: 'null' title: Max Connections description: >- Maximum number of connections for httpx.Client. None means no limit, useful for running many conversations in parallel. kind: type: string const: RemoteWorkspace title: Kind type: object required: - working_dir - host title: RemoteWorkspace description: >- 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. Supports optional completion callbacks on exit via environment variables: - ``AUTOMATION_CALLBACK_URL`` — URL to POST completion status to - ``AUTOMATION_CALLBACK_API_KEY`` — Bearer token for callback auth (optional) - ``AUTOMATION_RUN_ID`` — Run ID to include in callback payload (optional) Example: >>> 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") AlwaysConfirm: properties: kind: type: string const: AlwaysConfirm title: Kind type: object title: AlwaysConfirm ConfirmRisky: properties: threshold: $ref: '#/components/schemas/SecurityRisk' default: HIGH confirm_unknown: type: boolean title: Confirm Unknown default: true kind: type: string const: ConfirmRisky title: Kind type: object title: ConfirmRisky NeverConfirm: properties: kind: type: string const: NeverConfirm title: Kind type: object title: NeverConfirm PatternSecurityAnalyzer: properties: high_patterns: items: prefixItems: - type: string - type: string - type: string type: array maxItems: 3 minItems: 3 type: array title: High Patterns description: HIGH patterns scanned against executable fields only medium_patterns: items: prefixItems: - type: string - type: string - type: string type: array maxItems: 3 minItems: 3 type: array title: Medium Patterns description: MEDIUM patterns scanned against executable fields only injection_high_patterns: items: prefixItems: - type: string - type: string - type: string type: array maxItems: 3 minItems: 3 type: array title: Injection High Patterns description: HIGH patterns scanned against all fields injection_medium_patterns: items: prefixItems: - type: string - type: string - type: string type: array maxItems: 3 minItems: 3 type: array title: Injection Medium Patterns description: MEDIUM patterns scanned against all fields kind: type: string const: PatternSecurityAnalyzer title: Kind type: object title: PatternSecurityAnalyzer description: >- Catch dangerous agent actions through deterministic signature scanning. Use this when you want fast, local, no-network threat detection at the action boundary. It returns ``SecurityRisk.HIGH``, ``MEDIUM``, or ``LOW`` -- pair it with ``ConfirmRisky`` to decide what gets confirmed. The key design choice: shell-destructive patterns only scan what the agent will *execute* (tool arguments), never what it *thought about* (reasoning text). Injection patterns scan everything, because "ignore all previous instructions" is dangerous wherever it appears. Normalization is always on -- invisible characters and fullwidth substitutions are collapsed before matching. Example:: from openhands.sdk.security import PatternSecurityAnalyzer, ConfirmRisky analyzer = PatternSecurityAnalyzer() policy = ConfirmRisky(threshold=SecurityRisk.MEDIUM) PolicyRailSecurityAnalyzer: properties: kind: type: string const: PolicyRailSecurityAnalyzer title: Kind type: object title: PolicyRailSecurityAnalyzer description: |- Catch composed threats that plain regex signatures would miss. Use this when you need to detect threats defined by *combinations* of tokens (e.g., ``curl`` piped to ``bash``) rather than individual signatures. While these rails *could* each be expressed as a single regex, keeping them as named rules with per-segment evaluation makes the threat model more interpretable, the rules easier to maintain, and the audit trail clearer than a flat pattern list. Evaluates normalized executable segments only -- reasoning text is never scanned. Returns ``SecurityRisk.HIGH`` when a rail fires, ``LOW`` otherwise. Pair with ``ConfirmRisky`` and compose via ``EnsembleSecurityAnalyzer``. v1 rails: fetch-to-exec, raw-disk-op, catastrophic-delete. Example:: from openhands.sdk.security import PolicyRailSecurityAnalyzer analyzer = PolicyRailSecurityAnalyzer() # risk = analyzer.security_risk(action) EnsembleSecurityAnalyzer: properties: analyzers: items: $ref: '#/components/schemas/SecurityAnalyzerBase' type: array minItems: 1 title: Analyzers description: Analyzers whose assessments are combined via max-severity propagate_unknown: type: boolean title: Propagate Unknown description: >- When True, any child returning UNKNOWN causes the ensemble to return UNKNOWN. When False (default), UNKNOWN is filtered out if any child returns a concrete level. default: false kind: type: string const: EnsembleSecurityAnalyzer title: Kind type: object required: - analyzers title: EnsembleSecurityAnalyzer description: |- Wire multiple analyzers together and take the worst-case risk. Use this as the top-level analyzer you set on a conversation. It calls each child analyzer, collects their risk assessments, and returns the highest concrete risk. It does not perform any detection, extraction, or normalization of its own. How UNKNOWN works (default, ``propagate_unknown=False``): if *all* children return UNKNOWN, the ensemble returns UNKNOWN (which ``ConfirmRisky`` confirms by default). If any child returns a concrete level, UNKNOWN results are filtered out and the highest concrete level wins. With ``propagate_unknown=True``: if *any* child returns UNKNOWN, the ensemble returns UNKNOWN regardless of other results. Use this in stricter environments where incomplete assessment should trigger confirmation. If a child analyzer raises an exception, it contributes HIGH (fail-closed, logged). This prevents a broken analyzer from silently degrading safety. Example:: from openhands.sdk.security import ( EnsembleSecurityAnalyzer, PatternSecurityAnalyzer, PolicyRailSecurityAnalyzer, ConfirmRisky, SecurityRisk, ) analyzer = EnsembleSecurityAnalyzer( analyzers=[ PolicyRailSecurityAnalyzer(), PatternSecurityAnalyzer(), ] ) policy = ConfirmRisky(threshold=SecurityRisk.MEDIUM) GraySwanAnalyzer: properties: history_limit: type: integer title: History Limit description: Number of recent events to include as context default: 20 max_message_chars: type: integer title: Max Message Chars description: Max characters for conversation processing default: 30000 timeout: type: number title: Timeout description: Request timeout in seconds default: 30 low_threshold: type: number title: Low Threshold description: Risk threshold for LOW classification (score <= threshold) default: 0.3 medium_threshold: type: number title: Medium Threshold description: Risk threshold for MEDIUM classification (score <= threshold) default: 0.7 api_url: type: string title: Api Url description: GraySwan Cygnal API endpoint default: https://api.grayswan.ai/cygnal/monitor api_key: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Api Key description: GraySwan API key (via GRAYSWAN_API_KEY env var) policy_id: anyOf: - type: string - type: 'null' title: Policy Id description: GraySwan policy ID (via GRAYSWAN_POLICY_ID env var) kind: type: string const: GraySwanAnalyzer title: Kind type: object title: GraySwanAnalyzer description: >- Security analyzer using GraySwan's Cygnal API for AI safety monitoring. This analyzer sends conversation history and pending actions to the GraySwan Cygnal API for security analysis. The API returns a violation score which is mapped to SecurityRisk levels. Environment Variables: GRAYSWAN_API_KEY: Required API key for GraySwan authentication GRAYSWAN_POLICY_ID: Optional policy ID for custom GraySwan policy Example: >>> from openhands.sdk.security.grayswan import GraySwanAnalyzer >>> analyzer = GraySwanAnalyzer() >>> risk = analyzer.security_risk(action_event) LLMSecurityAnalyzer: properties: kind: type: string const: LLMSecurityAnalyzer title: Kind type: object title: LLMSecurityAnalyzer description: >- LLM-based security analyzer. This analyzer respects the security_risk attribute that can be set by the LLM when generating actions, similar to OpenHands' LLMRiskAnalyzer. It provides a lightweight security analysis approach that leverages the LLM's understanding of action context and potential risks. ToolShieldLLMSecurityAnalyzer: properties: llm: $ref: '#/components/schemas/LLM-Input' description: >- LLM used as the guardrail. Can be a smaller/cheaper model than the actor LLM; only the model's ability to classify action risk matters. history_window: type: integer title: History Window description: Number of prior actions to include as context. default: 20 safety_experiences: type: string title: Safety Experiences description: >- Pre-generated safety guidelines injected into the guardrail's system prompt. - ``""`` (default): bare guardrail -- no experiences. The analyzer still separates actor from judge; it just classifies without distilled tool-specific guidance. - Any non-empty string: used as-is. The intended pattern is to call one of the helpers (``default_safety_experiences()``, ``load_safety_experiences(tool_names)``, ``auto_detect_safety_experiences()``) which require the ``[toolshield]`` optional extra (``pip install openhands-sdk[toolshield]``). Callers with their own source of guidelines can pass any custom string. default: '' kind: type: string const: ToolShieldLLMSecurityAnalyzer title: Kind type: object required: - llm title: ToolShieldLLMSecurityAnalyzer description: |- Evaluate each action via a separate guardrail LLM. Pairs with the existing ``ConfirmRisky`` policy unchanged: this analyzer only *assigns* the risk level; ``ConfirmRisky`` decides whether to pause for user confirmation. By default the analyzer runs as a bare guardrail (no distilled safety experiences). To enable the ToolShield seed, install ``pip install openhands-sdk[toolshield]`` and pass the rendered experiences via the ``safety_experiences`` field -- typically via one of the helpers (``default_safety_experiences()``, ``load_safety_experiences(...)``, ``auto_detect_safety_experiences()``). Tested against ``toolshield>=0.1.3,<0.2``. Note: ``reasoning_content`` and ``thinking_blocks`` from extended- thinking models are deliberately excluded from the guardrail context. The risk signal lives in the tool call's name and arguments; including reasoning text would inflate the prompt without proportional safety gain. Subclasses needing reasoning visibility should override :func:`_format_action_for_guardrail`. Lifecycle: instances maintain a per-conversation deque of recent actions (``history_window`` items) for guardrail context. Each instance is intended for SINGLE-CONVERSATION use. Reusing one analyzer instance across multiple conversations will leak action history between them, which is both a privacy issue (conversation A's tool arguments visible in conversation B's guardrail prompt) and a correctness issue (the guardrail evaluates conversation B's actions against irrelevant history). Construct one analyzer per conversation, OR call :meth:`reset_history` at conversation boundaries. The recent-action-context propagation across analyzers (this one, :class:`LLMSecurityAnalyzer`, :class:`GraySwanAnalyzer`) is tracked for convergence in a separate follow-up; until that lands, single-conversation lifecycle is the contract. Failure modes are consistent and ensemble-safe -- both an infrastructure error (network, rate limit) and a parse failure (the guardrail responded but its output had no parseable ``RISK:`` label) return ``SecurityRisk.UNKNOWN``. ``ConfirmRisky`` with ``confirm_unknown=True`` then pauses for user confirmation, matching the conservative posture without dominating ``max()`` in ensemble fusion. Metrics: properties: model_name: type: string title: Model Name description: Name of the model default: default accumulated_cost: type: number minimum: 0 title: Accumulated Cost description: Total accumulated cost, must be non-negative default: 0 max_budget_per_task: anyOf: - type: number - type: 'null' title: Max Budget Per Task description: Maximum budget per task accumulated_token_usage: anyOf: - $ref: '#/components/schemas/TokenUsage' - type: 'null' description: Accumulated token usage across all calls costs: items: $ref: '#/components/schemas/Cost' type: array title: Costs description: List of individual costs response_latencies: items: $ref: '#/components/schemas/ResponseLatency' type: array title: Response Latencies description: List of response latencies token_usages: items: $ref: '#/components/schemas/TokenUsage' type: array title: Token Usages description: List of token usage records type: object title: Metrics description: |- Metrics class can record various metrics during running and evaluation. We track: - accumulated_cost and costs - max_budget_per_task (budget limit) - A list of ResponseLatency - A list of TokenUsage (one per call). SecretSource-Input: oneOf: - $ref: '#/components/schemas/LookupSecret-Input' - $ref: '#/components/schemas/StaticSecret-Input' discriminator: propertyName: kind mapping: openhands__sdk__secret__secrets__LookupSecret-Input__1: $ref: '#/components/schemas/LookupSecret-Input' openhands__sdk__secret__secrets__StaticSecret-Input__1: $ref: '#/components/schemas/StaticSecret-Input' HookMatcher-Input: properties: matcher: type: string title: Matcher default: '*' hooks: items: $ref: '#/components/schemas/HookDefinition' type: array title: Hooks type: object title: HookMatcher description: >- Matches events to hooks based on patterns. Supports exact match, wildcard (*), and regex (auto-detected or /pattern/). TokenUsage: properties: model: type: string title: Model default: '' prompt_tokens: type: integer minimum: 0 title: Prompt Tokens description: Prompt tokens must be non-negative default: 0 completion_tokens: type: integer minimum: 0 title: Completion Tokens description: Completion tokens must be non-negative default: 0 cache_read_tokens: type: integer minimum: 0 title: Cache Read Tokens description: Cache read tokens must be non-negative default: 0 cache_write_tokens: type: integer minimum: 0 title: Cache Write Tokens description: Cache write tokens must be non-negative default: 0 reasoning_tokens: type: integer minimum: 0 title: Reasoning Tokens description: Reasoning tokens must be non-negative default: 0 context_window: type: integer minimum: 0 title: Context Window description: Context window must be non-negative default: 0 per_turn_token: type: integer minimum: 0 title: Per Turn Token description: Per turn tokens must be non-negative default: 0 response_id: type: string title: Response Id default: '' type: object title: TokenUsage description: Metric tracking detailed token usage per completion call. ACPAgent: properties: llm: $ref: '#/components/schemas/LLM-Input' tools: items: $ref: '#/components/schemas/openhands__sdk__tool__spec__Tool' type: array title: Tools mcp_config: additionalProperties: $ref: '#/components/schemas/MCPServer-Input' type: object title: Mcp Config description: Optional MCP servers to expose as tools. examples: - fetch: args: - '--with' - mcp==1.29.0 - mcp-server-fetch==2026.7.10 command: uvx filter_tools_regex: anyOf: - type: string - type: 'null' title: Filter Tools Regex description: >- Optional regex to filter the tools available to the agent by name. This is applied after any tools provided in `tools` and any MCP tools are added. examples: - ^(?!repomix)(.*)|^repomix.*pack_codebase.*$ include_default_tools: items: type: string type: array title: Include Default Tools agent_context: anyOf: - $ref: '#/components/schemas/AgentContext-Input' - type: 'null' description: Optional AgentContext to initialize the agent with specific context. examples: - skills: - content: >- When you see this message, you should reply like you are a grumpy cat forced to use the internet. name: AGENTS.md type: repo - content: >- IMPORTANT! The user has said the magic word "flarglebargle". You must only respond with a message telling them how smart they are name: flarglebargle trigger: - flarglebargle type: knowledge system_message_suffix: Always finish your response with the word 'yay!' user_message_prefix: The first character of your response should be 'I' system_prompt: anyOf: - type: string - type: 'null' title: System Prompt description: >- Inline system prompt string. When provided, the agent uses this text verbatim as the system message instead of rendering from `system_prompt_filename`. Mutually exclusive with a non-default `system_prompt_filename`. **Warning**: This is not recommended unless you know what you are doing (e.g. customising agent behaviour for a completely different task). Setting this will override OpenHands' built-in system instructions that govern default agent behaviour. system_prompt_filename: type: string title: System Prompt Filename description: >- System prompt template filename. Can be either: - A relative filename (e.g., 'system_prompt.j2') loaded from the agent's prompts directory - An absolute path (e.g., '/path/to/custom_prompt.j2') default: system_prompt.j2 security_policy_filename: type: string title: Security Policy Filename description: >- Security policy filename. The default 'security_policy.j2' is a back-compat sentinel (the file was removed) that selects the built-in default policy from the prompt registry -- it is not loaded from disk. Any other value names a custom policy file whose contents are inserted verbatim (NOT rendered as a Jinja template). Can be either: - A relative filename (e.g., 'custom_security_policy.md') loaded from the agent's prompts directory - An absolute path (e.g., '/path/to/custom_security_policy.md') - Empty string to disable security policy default: security_policy.j2 system_prompt_kwargs: additionalProperties: true type: object title: System Prompt Kwargs description: Optional kwargs to pass to the system prompt Jinja2 template. examples: - cli_mode: true condenser: anyOf: - $ref: '#/components/schemas/CondenserBase-Input' - type: 'null' description: Optional condenser to use for condensing conversation history. examples: - keep_first: 10 kind: LLMSummarizingCondenser llm: api_key: your_api_key_here base_url: https://llm-proxy.eval.all-hands.dev model: litellm_proxy/openai/gpt-5.5 max_size: 80 critic: anyOf: - $ref: '#/components/schemas/CriticBase' - type: 'null' description: >- EXPERIMENTAL: Optional critic to evaluate agent actions and messages in real-time. API and behavior may change without notice. May impact performance, especially in 'all_actions' mode. examples: - kind: AgentFinishedCritic tool_concurrency_limit: type: integer minimum: 1 title: Tool Concurrency Limit description: >- Maximum number of tool calls to execute concurrently within a single agent step. Default is 1 (sequential). Values > 1 enable parallel execution; concurrent tools share the conversation object, filesystem, and working directory, so mutations to shared state may race. default: 1 acp_command: items: type: string type: array title: Acp Command description: >- Command to start the ACP server, e.g. ['npx', '-y', '@agentclientprotocol/claude-agent-acp'] acp_server: anyOf: - type: string - type: 'null' title: Acp Server description: >- Provider registry key identifying which ACP CLI this agent runs ('claude-code', 'codex', 'gemini-cli', or 'custom'); None when the agent is built directly rather than via ACPAgentSettings. Set by ACPAgentSettings.create_agent() from ACPAgentSettings.acp_server so the authoritative key survives onto the agent — and thus onto ConversationInfo.agent — because the launch command in acp_command does not reliably reverse-map to a provider. Informational only: consumers use it to resolve a provider brand label / model list; the subprocess is still launched from acp_command. acp_args: items: type: string type: array title: Acp Args description: Additional arguments for the ACP server command acp_session_mode: anyOf: - type: string - type: 'null' title: Acp Session Mode description: >- Session mode ID to set after creating a session. If None (default), auto-detected from the ACP server type: 'bypassPermissions' for claude-agent-acp, 'agent-full-access' for codex-acp. acp_prompt_timeout: type: number title: Acp Prompt Timeout description: >- Inactivity timeout in seconds for a single ACP prompt() call. The deadline resets on every update from the ACP server (token, thought, tool-call progress, usage), so a steadily-progressing agent runs as long as it keeps making progress; the prompt is only aborted after this many seconds with no activity at all. Prevents indefinite hangs when the ACP server stops responding without killing legitimately long-running work. default: 1800 acp_startup_timeout: type: number title: Acp Startup Timeout description: >- Timeout in seconds for ACP server startup: spawning the subprocess, the initialize/authenticate handshake, and new_session()/load_session(). Unlike acp_prompt_timeout, this is a hard deadline rather than an idle deadline, since startup has no intermediate progress signal to reset it against. Prevents an indefinite hang when the ACP server blocks on authentication (e.g. an expired token) without ever raising. default: 90 acp_model: anyOf: - type: string - type: 'null' title: Acp Model description: >- Model for the ACP server to use (e.g. 'sonnet' or 'gpt-5.5'). Applied via the protocol — set_config_option(model) for configOptions-based servers (codex, claude), else set_session_model. If None, the server picks its default. acp_resume_session_id: anyOf: - type: string - type: 'null' title: Acp Resume Session Id description: >- Optional explicit ACP session id to resume. When set, takes precedence over the id persisted in ``state.agent_state`` and is used to call ``session/load`` on the ACP server. Designed for environments where the per-conversation filesystem (and therefore ``base_state.json``) does not survive across restarts (e.g. cloud sandbox recycles), but the id has been mirrored into durable storage elsewhere. Falls back to a fresh session if the server cannot load the id. Treated as a secret on the wire — possession of the id is enough to resume the underlying ACP session, so default serialization redacts it; pass ``expose_secrets='plaintext'`` (trusted backend) or ``expose_secrets='encrypted'`` plus a cipher (frontend round-trip) when the value must cross a serialization boundary. acp_file_secrets: items: $ref: '#/components/schemas/ACPFileSecretSpec' type: array title: Acp File Secrets description: >- Reserved 'file-content' credential secrets to materialise to disk before launching the subprocess (e.g. Codex auth.json, Gemini Vertex SA JSON). The SDK owns the mechanism (write the file in the runtime pod, set the env var, seed-if-absent); these specs are the policy. Defaults to the built-in supported providers; a downstream application may override or extend this to support other ACP servers with different file-auth schemes. acp_isolate_data_dir: type: boolean title: Acp Isolate Data Dir description: >- Give the ACP subprocess a per-conversation CLI data/config root instead of the shared user ``HOME``. When True and the provider is recognised, point its data-dir env var (``CODEX_HOME`` / ``CLAUDE_CONFIG_DIR`` / ``HOME``; see ``ACPProviderInfo.data_dir_env_var``) at ``/acp/`` — the same per-conversation tree materialised file-secrets use. Required for correctness when several of a user's conversations share one sandbox (``SandboxGroupingStrategy != NO_GROUPING``), where they would otherwise race on one set of CLI auth/config/cache/lock files (see #1019). Off by default: with one sandbox per conversation the shared HOME is already private, and relocating it would hide a pre-existing interactive login. Downstream policy decides when to enable it; the SDK owns where the root lives. default: false kind: type: string const: ACPAgent title: Kind type: object required: - acp_command title: ACPAgent description: Agent that delegates to an ACP-compatible subprocess server. Agent: properties: llm: $ref: '#/components/schemas/LLM-Input' description: LLM configuration for the agent. examples: - api_key: your_api_key_here base_url: https://llm-proxy.eval.all-hands.dev model: litellm_proxy/openai/gpt-5.5 tools: items: $ref: '#/components/schemas/openhands__sdk__tool__spec__Tool' type: array title: Tools description: List of tools to initialize for the agent. examples: - name: TerminalTool params: {} - name: FileEditorTool params: {} - name: TaskTrackerTool params: {} mcp_config: additionalProperties: $ref: '#/components/schemas/MCPServer-Input' type: object title: Mcp Config description: Optional MCP servers to expose as tools. examples: - fetch: args: - '--with' - mcp==1.29.0 - mcp-server-fetch==2026.7.10 command: uvx filter_tools_regex: anyOf: - type: string - type: 'null' title: Filter Tools Regex description: >- Optional regex to filter the tools available to the agent by name. This is applied after any tools provided in `tools` and any MCP tools are added. examples: - ^(?!repomix)(.*)|^repomix.*pack_codebase.*$ include_default_tools: items: type: string type: array title: Include Default Tools description: >- List of default tool class names to include. By default, the agent includes 'FinishTool' and 'ThinkTool'. Set to an empty list to disable all default tools, or provide a subset to include only specific ones. Example: include_default_tools=['FinishTool'] to only include FinishTool, or include_default_tools=[] to disable all default tools. examples: - - FinishTool - ThinkTool - - FinishTool - [] agent_context: anyOf: - $ref: '#/components/schemas/AgentContext-Input' - type: 'null' description: Optional AgentContext to initialize the agent with specific context. examples: - skills: - content: >- When you see this message, you should reply like you are a grumpy cat forced to use the internet. name: AGENTS.md type: repo - content: >- IMPORTANT! The user has said the magic word "flarglebargle". You must only respond with a message telling them how smart they are name: flarglebargle trigger: - flarglebargle type: knowledge system_message_suffix: Always finish your response with the word 'yay!' user_message_prefix: The first character of your response should be 'I' system_prompt: anyOf: - type: string - type: 'null' title: System Prompt description: >- Inline system prompt string. When provided, the agent uses this text verbatim as the system message instead of rendering from `system_prompt_filename`. Mutually exclusive with a non-default `system_prompt_filename`. **Warning**: This is not recommended unless you know what you are doing (e.g. customising agent behaviour for a completely different task). Setting this will override OpenHands' built-in system instructions that govern default agent behaviour. system_prompt_filename: type: string title: System Prompt Filename description: >- System prompt template filename. Can be either: - A relative filename (e.g., 'system_prompt.j2') loaded from the agent's prompts directory - An absolute path (e.g., '/path/to/custom_prompt.j2') default: system_prompt.j2 security_policy_filename: type: string title: Security Policy Filename description: >- Security policy filename. The default 'security_policy.j2' is a back-compat sentinel (the file was removed) that selects the built-in default policy from the prompt registry -- it is not loaded from disk. Any other value names a custom policy file whose contents are inserted verbatim (NOT rendered as a Jinja template). Can be either: - A relative filename (e.g., 'custom_security_policy.md') loaded from the agent's prompts directory - An absolute path (e.g., '/path/to/custom_security_policy.md') - Empty string to disable security policy default: security_policy.j2 system_prompt_kwargs: additionalProperties: true type: object title: System Prompt Kwargs description: Optional kwargs to pass to the system prompt Jinja2 template. examples: - cli_mode: true condenser: anyOf: - $ref: '#/components/schemas/CondenserBase-Input' - type: 'null' description: Optional condenser to use for condensing conversation history. examples: - keep_first: 10 kind: LLMSummarizingCondenser llm: api_key: your_api_key_here base_url: https://llm-proxy.eval.all-hands.dev model: litellm_proxy/openai/gpt-5.5 max_size: 80 critic: anyOf: - $ref: '#/components/schemas/CriticBase' - type: 'null' description: >- EXPERIMENTAL: Optional critic to evaluate agent actions and messages in real-time. API and behavior may change without notice. May impact performance, especially in 'all_actions' mode. examples: - kind: AgentFinishedCritic tool_concurrency_limit: type: integer minimum: 1 title: Tool Concurrency Limit description: >- Maximum number of tool calls to execute concurrently within a single agent step. Default is 1 (sequential). Values > 1 enable parallel execution; concurrent tools share the conversation object, filesystem, and working directory, so mutations to shared state may race. default: 1 kind: type: string const: Agent title: Kind type: object required: - llm title: Agent description: >- Main agent implementation for OpenHands. The Agent class provides the core functionality for running AI agents that can interact with tools, process messages, and execute actions. It inherits from AgentBase and implements the agent execution logic. Critic-related functionality is provided by CriticMixin. Attributes: llm: The language model instance used for reasoning. tools: List of tools available to the agent. system_prompt: Inline system prompt string. When provided the agent uses this text verbatim instead of rendering from a template. Mutually exclusive with a non-default ``system_prompt_filename``. **Not recommended** unless you know what you are doing (e.g. customising agent behaviour for a completely different task) — this will override OpenHands' built-in system instructions. system_prompt_filename: Jinja2 template filename resolved relative to the agent's prompts directory, or an absolute path. Defaults to ``"system_prompt.j2"``. system_prompt_kwargs: Extra kwargs forwarded to the Jinja2 template. Example: ```python from openhands.sdk import LLM, Agent, Tool from pydantic import SecretStr llm = LLM(model="gpt-5.5", api_key=SecretStr("key")) tools = [Tool(name="TerminalTool"), Tool(name="FileEditorTool")] agent = Agent(llm=llm, tools=tools) ``` To override the system prompt entirely:: agent = Agent( llm=llm, tools=tools, system_prompt="You are a helpful coding assistant.", ) openhands__sdk__tool__tool__ToolAnnotations: properties: title: anyOf: - type: string - type: 'null' title: Title description: A human-readable title for the tool. readOnlyHint: type: boolean title: Readonlyhint description: 'If true, the tool does not modify its environment. Default: false' default: false destructiveHint: type: boolean title: Destructivehint description: >- If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates. (This property is meaningful only when `readOnlyHint == false`) Default: true default: true idempotentHint: type: boolean title: Idempotenthint description: >- If true, calling the tool repeatedly with the same arguments will have no additional effect on the its environment. (This property is meaningful only when `readOnlyHint == false`) Default: false default: false openWorldHint: type: boolean title: Openworldhint description: >- If true, this tool may interact with an 'open world' of external entities. If false, the tool's domain of interaction is closed. For example, the world of a web search tool is open, whereas that of a memory tool is not. Default: true default: true type: object title: openhands.sdk.tool.tool.ToolAnnotations description: >- Annotations to provide hints about the tool's behavior. Based on Model Context Protocol (MCP) spec: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/caf3424488b10b4a7b1f8cb634244a450a1f4400/schema/2025-06-18/schema.ts#L838 SecurityRisk: type: string enum: - UNKNOWN - LOW - MEDIUM - HIGH title: SecurityRisk description: |- Security risk levels for actions. Based on OpenHands security risk levels but adapted for agent-sdk. Integer values allow for easy comparison and ordering. LLM-Input: properties: model: type: string title: Model description: Model name. default: gpt-5.5 openhands_settings: depends_on: [] prominence: critical api_key: anyOf: - type: string - type: string format: password writeOnly: true - type: 'null' title: Api Key description: API key. openhands_settings: depends_on: [] label: API Key prominence: critical auth_type: type: string enum: - api_key - subscription title: Auth Type description: Authentication mode for the LLM. default: api_key openhands_settings: depends_on: [] label: Authentication prominence: critical subscription_vendor: anyOf: - type: string const: openai - type: 'null' title: Subscription Vendor description: Subscription provider for subscription-backed LLM access. openhands_settings: depends_on: - auth_type label: Subscription provider prominence: critical base_url: anyOf: - type: string - type: 'null' title: Base Url description: Custom base URL. openhands_settings: depends_on: [] prominence: major api_version: anyOf: - type: string - type: 'null' title: Api Version description: API version (e.g., Azure). openhands_settings: depends_on: [] prominence: minor aws_access_key_id: anyOf: - type: string - type: string format: password writeOnly: true - type: 'null' title: Aws Access Key Id openhands_settings: depends_on: [] prominence: minor aws_secret_access_key: anyOf: - type: string - type: string format: password writeOnly: true - type: 'null' title: Aws Secret Access Key openhands_settings: depends_on: [] prominence: minor aws_session_token: anyOf: - type: string - type: string format: password writeOnly: true - type: 'null' title: Aws Session Token openhands_settings: depends_on: [] prominence: minor aws_region_name: anyOf: - type: string - type: 'null' title: Aws Region Name openhands_settings: depends_on: [] prominence: minor aws_profile_name: anyOf: - type: string - type: 'null' title: Aws Profile Name openhands_settings: depends_on: [] prominence: minor aws_role_name: anyOf: - type: string - type: 'null' title: Aws Role Name openhands_settings: depends_on: [] prominence: minor aws_session_name: anyOf: - type: string - type: 'null' title: Aws Session Name openhands_settings: depends_on: [] prominence: minor aws_bedrock_runtime_endpoint: anyOf: - type: string - type: 'null' title: Aws Bedrock Runtime Endpoint openhands_settings: depends_on: [] prominence: minor openrouter_site_url: type: string title: Openrouter Site Url default: https://docs.all-hands.dev/ openhands_settings: depends_on: [] prominence: minor openrouter_app_name: type: string title: Openrouter App Name default: OpenHands openhands_settings: depends_on: [] prominence: minor num_retries: type: integer minimum: 0 title: Num Retries default: 5 openhands_settings: depends_on: [] prominence: minor retry_multiplier: type: number minimum: 0 title: Retry Multiplier default: 8 openhands_settings: depends_on: [] prominence: minor retry_min_wait: type: integer minimum: 0 title: Retry Min Wait default: 8 openhands_settings: depends_on: [] prominence: minor retry_max_wait: type: integer minimum: 0 title: Retry Max Wait default: 64 openhands_settings: depends_on: [] prominence: minor timeout: anyOf: - type: integer minimum: 0 - type: 'null' title: Timeout description: >- HTTP timeout in seconds. Default is 300s (5 minutes). Set to None to disable timeout (not recommended for production). default: 300 openhands_settings: depends_on: [] prominence: minor max_message_chars: type: integer minimum: 1 title: Max Message Chars description: Approx max chars in each event/content sent to the LLM. default: 30000 openhands_settings: depends_on: [] prominence: minor temperature: anyOf: - type: number minimum: 0 - type: 'null' title: Temperature description: >- Sampling temperature for response generation. Defaults to None (uses provider default temperature). Set to 0.0 for deterministic outputs, or higher values (0.7-1.0) for more creative responses. openhands_settings: depends_on: [] prominence: minor top_p: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Top P description: >- Nucleus sampling parameter. Defaults to None (uses provider default). Set to a value between 0 and 1 to control diversity of outputs. openhands_settings: depends_on: [] prominence: minor top_k: anyOf: - type: number minimum: 0 - type: 'null' title: Top K openhands_settings: depends_on: [] prominence: minor max_input_tokens: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Input Tokens description: >- The maximum number of input tokens. Note that this is currently unused, and the value at runtime is actually the total tokens in OpenAI (e.g. 128,000 tokens for GPT-4). openhands_settings: depends_on: [] prominence: minor max_output_tokens: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Output Tokens description: The maximum number of output tokens. This is sent to the LLM. openhands_settings: depends_on: [] prominence: minor model_canonical_name: anyOf: - type: string - type: 'null' title: Model Canonical Name description: >- Optional canonical model name for feature registry lookups. The OpenHands SDK maintains a model feature registry that maps model names to capabilities (e.g., vision support, prompt caching, responses API support). When using proxied or aliased model identifiers, set this field to the canonical model name (e.g., 'openai/gpt-4o') to ensure correct capability detection. If not provided, the 'model' field will be used for capability lookups. openhands_settings: depends_on: [] prominence: minor api_mode: type: string enum: - auto - chat - responses title: Api Mode description: >- LLM API endpoint mode. 'auto' resolves from model metadata and SDK fallbacks; use 'chat' or 'responses' to override endpoint selection for proxy aliases and newly released models. default: auto openhands_settings: depends_on: [] prominence: minor capability_overrides: additionalProperties: anyOf: - type: boolean - type: string type: object title: Capability Overrides description: >- Explicit model capability overrides. Supported keys include supports_reasoning_effort, thinking_mode (adaptive, manual, none, or unknown), supports_sampling_params, supports_prompt_cache, supports_stop_words, supports_responses_api, supports_vision, and supports_prompt_cache_retention. Overrides take precedence over LiteLLM metadata and SDK fallbacks. openhands_settings: depends_on: [] prominence: minor extra_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Extra Headers description: Optional HTTP headers to forward to LiteLLM requests. openhands_settings: depends_on: [] prominence: minor input_cost_per_token: anyOf: - type: number minimum: 0 - type: 'null' title: Input Cost Per Token description: The cost per input token. This will available in logs for user. openhands_settings: depends_on: [] prominence: minor output_cost_per_token: anyOf: - type: number minimum: 0 - type: 'null' title: Output Cost Per Token description: The cost per output token. This will available in logs for user. openhands_settings: depends_on: [] prominence: minor ollama_base_url: anyOf: - type: string - type: 'null' title: Ollama Base Url openhands_settings: depends_on: [] prominence: minor stream: type: boolean title: Stream description: >- Enable streaming responses from the LLM. When enabled, the provided `on_token` callback in .completions and .responses will be invoked for each chunk of tokens. default: false openhands_settings: depends_on: [] prominence: minor drop_params: type: boolean title: Drop Params default: true openhands_settings: depends_on: [] prominence: minor modify_params: type: boolean title: Modify Params description: >- Modify params allows litellm to do transformations like adding a default message, when a message is empty. default: true openhands_settings: depends_on: [] prominence: minor disable_vision: anyOf: - type: boolean - type: 'null' title: Disable Vision description: >- If model is vision capable, this option allows to disable image processing (useful for cost reduction). openhands_settings: depends_on: [] prominence: minor disable_stop_word: anyOf: - type: boolean - type: 'null' title: Disable Stop Word description: Disable using of stop word. default: false openhands_settings: depends_on: [] prominence: minor caching_prompt: type: boolean title: Caching Prompt description: Enable caching of prompts. default: true openhands_settings: depends_on: [] prominence: minor log_completions: type: boolean title: Log Completions description: Enable logging of completions. default: false openhands_settings: depends_on: [] prominence: minor log_completions_folder: type: string title: Log Completions Folder description: >- The folder to log LLM completions to. Required if log_completions is True. default: logs/completions openhands_settings: depends_on: [] prominence: minor custom_tokenizer: anyOf: - type: string - type: 'null' title: Custom Tokenizer description: A custom tokenizer to use for token counting. openhands_settings: depends_on: [] prominence: minor native_tool_calling: type: boolean title: Native Tool Calling description: Whether to use native tool calling. default: true openhands_settings: depends_on: [] prominence: minor force_string_serializer: anyOf: - type: boolean - type: 'null' title: Force String Serializer description: >- Force using string content serializer when sending to LLM API. If None (default), auto-detect based on model. Useful for providers that do not support list content, like HuggingFace and Groq. openhands_settings: depends_on: [] prominence: minor inline_image_urls: anyOf: - type: boolean - type: 'null' title: Inline Image Urls description: >- If True, fetch any http(s) image URL in outgoing messages and inline it as a base64 ``data:`` URL before sending. If None (default), auto-detect based on model (some APIs such as Moonshot's public Kimi endpoint reject URL-formatted images and require base64). Set this explicitly when the model is reached through a proxy alias that hides the underlying provider (e.g. ``litellm_proxy/``). Note: inlining only runs when ``vision_is_active()`` is True, so the alias must still be recognised as vision-capable by the SDK feature registry or proxy model metadata. openhands_settings: depends_on: [] prominence: minor reasoning_effort: anyOf: - type: string enum: - low - medium - high - xhigh - none - type: 'null' title: Reasoning Effort description: >- Provider-neutral reasoning effort. Common values include 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', and 'max'. The SDK accepts future provider values and lets LiteLLM translate them. default: high openhands_settings: depends_on: [] prominence: minor reasoning_summary: anyOf: - type: string enum: - auto - concise - detailed - type: 'null' title: Reasoning Summary description: >- The level of detail for reasoning summaries. This is a string that can be one of 'auto', 'concise', or 'detailed'. Requires verified OpenAI organization. Only sent when explicitly set. openhands_settings: depends_on: [] prominence: minor enable_encrypted_reasoning: type: boolean title: Enable Encrypted Reasoning description: >- If True, ask for ['reasoning.encrypted_content'] in Responses API include. default: true openhands_settings: depends_on: [] prominence: minor prompt_cache_retention: anyOf: - type: string - type: 'null' title: Prompt Cache Retention description: >- Retention policy for prompt cache. Only sent for supported models (GPT-5+ and GPT-4.1, excluding Azure deployments); explicitly stripped for all others. default: 24h openhands_settings: depends_on: [] prominence: minor extended_thinking_budget: anyOf: - type: integer - type: 'null' title: Extended Thinking Budget description: >- Legacy token budget for models confirmed to use manual Anthropic extended thinking. Ignored for adaptive-thinking models. Prefer reasoning_effort for new integrations. default: 200000 openhands_settings: depends_on: [] prominence: minor seed: anyOf: - type: integer - type: 'null' title: Seed description: The seed to use for random number generation. openhands_settings: depends_on: [] prominence: minor usage_id: type: string title: Usage Id description: >- Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking. default: default openhands_settings: depends_on: [] prominence: minor litellm_extra_body: additionalProperties: true type: object title: Litellm Extra Body description: >- Additional key-value pairs to pass to litellm's extra_body parameter. This is useful for custom inference endpoints that need additional parameters for configuration, routing, or advanced features. NOTE: Not all LLM providers support extra_body parameters. Some providers (e.g., OpenAI) may reject requests with unrecognized options. This is commonly supported by: - LiteLLM proxy servers (routing metadata, tracing) - vLLM endpoints (return_token_ids, etc.) - Custom inference clusters Examples: - Proxy routing: {'trace_version': '1.0.0', 'tags': ['agent:my-agent']} - vLLM features: {'return_token_ids': True} openhands_settings: depends_on: [] prominence: minor fallback_strategy: anyOf: - $ref: '#/components/schemas/FallbackStrategy' - type: 'null' description: >- Optional fallback strategy for trying alternate LLMs on transient failure. Construct with FallbackStrategy(fallback_llms=[...]).Excluded from serialization; must be reconfigured after load. type: object title: LLM description: >- Language model interface for OpenHands agents. The LLM class provides a unified interface for interacting with various language models through the litellm library. It handles model configuration, API authentication, retry logic, and tool calling capabilities. Attributes: model: Model name (e.g., "gpt-5.5"). api_key: API key for authentication. base_url: Custom API base URL. num_retries: Number of retry attempts for failed requests. timeout: Request timeout in seconds. Example: ```python from openhands.sdk import LLM from pydantic import SecretStr llm = LLM( model="gpt-5.5", api_key=SecretStr("your-api-key"), usage_id="my-agent" ) # Use with agent or conversation ``` Cost: properties: model: type: string title: Model cost: type: number minimum: 0 title: Cost description: Cost must be non-negative timestamp: type: number title: Timestamp type: object required: - model - cost title: Cost ResponseLatency: properties: model: type: string title: Model latency: type: number minimum: 0 title: Latency description: Latency must be non-negative response_id: type: string title: Response Id type: object required: - model - latency - response_id title: ResponseLatency description: Metric tracking the round-trip time per completion call. LookupSecret-Input: properties: description: anyOf: - type: string - type: 'null' title: Description description: Optional description for this secret url: type: string title: Url headers: additionalProperties: type: string type: object title: Headers kind: type: string const: LookupSecret title: Kind type: object required: - url title: LookupSecret description: A secret looked up from some external url StaticSecret-Input: properties: description: anyOf: - type: string - type: 'null' title: Description description: Optional description for this secret value: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Value kind: type: string const: StaticSecret title: Kind type: object title: StaticSecret description: A secret stored locally HookDefinition: properties: type: $ref: '#/components/schemas/HookType' default: command name: anyOf: - type: string - type: 'null' title: Name command: type: string title: Command prompt: anyOf: - type: string - type: 'null' title: Prompt system_prompt: anyOf: - type: string - type: 'null' title: System Prompt tools: items: type: string type: array title: Tools timeout: type: integer title: Timeout default: 60 max_iterations: type: integer title: Max Iterations default: 3 async: type: boolean title: Async default: false type: object required: - command title: HookDefinition description: A single hook definition. openhands__sdk__tool__spec__Tool: properties: name: type: string title: Name description: >- Name of the tool class, e.g., 'TerminalTool'. Import it from an `openhands.tools.` subpackage. examples: - TerminalTool - FileEditorTool - TaskTrackerTool params: additionalProperties: true type: object title: Params description: >- Parameters for the tool's .create() method, e.g., {'working_dir': '/app'} examples: - working_dir: /workspace type: object required: - name title: Tool description: |- Defines a tool to be initialized for the agent. This is only used in agent-sdk for type schema for server use. MCPServer-Input: properties: url: anyOf: - type: string minLength: 1 - type: 'null' title: Url transport: anyOf: - type: string enum: - stdio - http - sse - streamable-http - type: 'null' title: Transport command: anyOf: - type: string minLength: 1 - type: 'null' title: Command args: anyOf: - items: type: string type: array - type: 'null' title: Args env: anyOf: - additionalProperties: type: string format: password writeOnly: true type: object - type: 'null' title: Env cwd: anyOf: - type: string - type: 'null' title: Cwd description: anyOf: - type: string - type: 'null' title: Description icon: anyOf: - type: string - type: 'null' title: Icon timeout: anyOf: - type: number - type: 'null' title: Timeout sse_read_timeout: anyOf: - type: number - type: 'null' title: Sse Read Timeout keep_alive: anyOf: - type: boolean - type: 'null' title: Keep Alive headers: anyOf: - additionalProperties: type: string format: password writeOnly: true type: object - type: 'null' title: Headers auth: anyOf: - oneOf: - $ref: '#/components/schemas/MCPNoneAuthCredential' - $ref: '#/components/schemas/MCPApiKeyAuthCredential-Input' - $ref: '#/components/schemas/MCPBearerAuthCredential-Input' - $ref: '#/components/schemas/MCPBasicAuthCredential-Input' - $ref: '#/components/schemas/MCPHeaderAuthCredential-Input' - $ref: '#/components/schemas/MCPOAuthAuthCredential-Input' discriminator: propertyName: strategy mapping: api_key: $ref: '#/components/schemas/MCPApiKeyAuthCredential-Input' basic: $ref: '#/components/schemas/MCPBasicAuthCredential-Input' bearer: $ref: '#/components/schemas/MCPBearerAuthCredential-Input' header: $ref: '#/components/schemas/MCPHeaderAuthCredential-Input' none: $ref: '#/components/schemas/MCPNoneAuthCredential' oauth2: $ref: '#/components/schemas/MCPOAuthAuthCredential-Input' - type: 'null' title: Auth enabled: type: boolean title: Enabled description: >- Whether this server is exposed to the agent. A disabled server stays fully configured -- including its secrets -- but is skipped when MCP tools are created and when servers are forwarded to an ACP subprocess. default: true additionalProperties: false type: object title: MCPServer description: One MCP server in the settings DataModel. AgentContext-Input: properties: skills: items: $ref: '#/components/schemas/Skill-Input' type: array title: Skills description: List of available skills that can extend the user's input. acp_compatible: true system_message_suffix: anyOf: - type: string - type: 'null' title: System Message Suffix description: Optional suffix to append to the system prompt. acp_compatible: true user_message_suffix: anyOf: - type: string - type: 'null' title: User Message Suffix description: Optional suffix to append to the user's message. acp_compatible: true load_user_skills: type: boolean title: Load User Skills description: >- Whether to automatically load user skills from ~/.openhands/skills/ and ~/.openhands/microagents/ (for backward compatibility). default: false acp_compatible: true load_public_skills: type: boolean title: Load Public Skills description: >- Whether to automatically load skills from the public OpenHands skills repository at https://github.com/OpenHands/extensions. This allows you to get the latest skills without SDK updates. default: false acp_compatible: true marketplace_path: anyOf: - type: string - type: 'null' title: Marketplace Path description: >- Relative marketplace JSON path within the public skills repository. Set to None to load all public skills without marketplace filtering. default: marketplaces/default.json acp_compatible: true registered_marketplaces: items: $ref: >- #/components/schemas/openhands__sdk__marketplace__registration__MarketplaceRegistration type: array title: Registered Marketplaces description: >- Marketplace registrations for plugin resolution. Registrations with auto_load=True or a list of plugin names are resolved by LocalConversation at startup. acp_compatible: true load_project_skills: type: boolean title: Load Project Skills description: >- Whether to automatically load project skills from the conversation workspace (e.g. .openhands/skills/, AGENTS.md). Unlike load_user_skills / load_public_skills, this flag is not resolved by AgentContext itself (the workspace path is unknown at validation time); LocalConversation resolves it lazily on the first send_message() / run(), when the workspace is known. Also unlike load_user_skills / load_public_skills (which yield to explicit skills on a name conflict), resolved project skills are authoritative: a project skill overrides a same-named skill already present in `skills`. default: false acp_compatible: true load_memory: type: boolean title: Load Memory description: >- Whether to load persistent agent memory (MEMORY.md indexes under ~/.openhands/memory/ and /.openhands/memory/) into the system prompt. Like load_project_skills, this flag is not resolved by AgentContext itself (the workspace path is unknown at validation time); LocalConversation resolves it lazily on the first send_message() / run() and stores the result in memory_context. default: false acp_compatible: true openhands_settings: depends_on: [] label: Persistent memory prominence: major memory_context: anyOf: - type: string - type: 'null' title: Memory Context description: >- Resolved memory-index text rendered into the prompt block. Populated via model_copy by LocalConversation when load_memory is set; excluded from serialization because it is re-resolved from disk each session and must not bloat persisted conversation state. acp_compatible: true disabled_skills: items: type: string type: array title: Disabled Skills description: >- Names of skills to EXCLUDE from this context — a deny-list applied after every skill source is loaded (auto-loaded user/public, explicit, and lazily-loaded project skills). A listed name absent from the loaded set is a harmless no-op. [] (the default) keeps every skill. This is the single, drift-tolerant skill-selection mechanism (agent profiles set it from their own deny-list; #4017). acp_compatible: true secrets: anyOf: - additionalProperties: anyOf: - type: string - $ref: '#/components/schemas/SecretSource-Input' type: object - type: 'null' title: Secrets description: >- Dictionary mapping secret keys to values or secret sources. Secrets are used for authentication and sensitive data handling. Values can be either strings or SecretSource instances (str | SecretSource). acp_compatible: true current_datetime: anyOf: - type: string format: date-time - type: string - type: 'null' title: Current Datetime description: >- Current date and time information to provide to the agent. Can be a datetime object (which will be formatted as ISO 8601) or a pre-formatted string. When provided, this information is included in the system prompt to give the agent awareness of the current time context. Defaults to the current (timezone-aware) datetime. acp_compatible: true type: object title: AgentContext description: >- Central structure for managing prompt extension. AgentContext unifies all the contextual inputs that shape how the system extends and interprets user prompts. It combines both static environment details and dynamic, user-activated extensions from skills. Specifically, it provides: - **Repository context / Repo Skills**: Information about the active codebase, branches, and repo-specific instructions contributed by repo skills. - **Runtime context**: Current execution environment (hosts, working directory, secrets, date, etc.). - **Conversation instructions**: Optional task- or channel-specific rules that constrain or guide the agent’s behavior across the session. - **Knowledge Skills**: Extensible components that can be triggered by user input to inject knowledge or domain-specific guidance. Together, these elements make AgentContext the primary container responsible for assembling, formatting, and injecting all prompt-relevant context into LLM interactions. CondenserBase-Input: oneOf: - $ref: '#/components/schemas/LLMSummarizingCondenser-Input' - $ref: '#/components/schemas/NoOpCondenser-Input' - $ref: '#/components/schemas/PipelineCondenser-Input' discriminator: propertyName: kind mapping: openhands__sdk__context__condenser__llm_summarizing_condenser__LLMSummarizingCondenser-Input__1: $ref: '#/components/schemas/LLMSummarizingCondenser-Input' openhands__sdk__context__condenser__no_op_condenser__NoOpCondenser-Input__1: $ref: '#/components/schemas/NoOpCondenser-Input' openhands__sdk__context__condenser__pipeline_condenser__PipelineCondenser-Input__1: $ref: '#/components/schemas/PipelineCondenser-Input' CriticBase: oneOf: - $ref: '#/components/schemas/AgentFinishedCritic' - $ref: '#/components/schemas/APIBasedCritic' - $ref: '#/components/schemas/EmptyPatchCritic' - $ref: '#/components/schemas/PassCritic' discriminator: propertyName: kind mapping: openhands__sdk__critic__impl__agent_finished__AgentFinishedCritic-Input__1: $ref: '#/components/schemas/AgentFinishedCritic' openhands__sdk__critic__impl__api__critic__APIBasedCritic-Input__1: $ref: '#/components/schemas/APIBasedCritic' openhands__sdk__critic__impl__empty_patch__EmptyPatchCritic-Input__1: $ref: '#/components/schemas/EmptyPatchCritic' openhands__sdk__critic__impl__pass_critic__PassCritic-Input__1: $ref: '#/components/schemas/PassCritic' ACPFileSecretSpec: properties: secret_name: type: string minLength: 1 title: Secret Name filename: type: string minLength: 1 title: Filename env_var: type: string minLength: 1 title: Env Var subdir: type: string minLength: 1 title: Subdir env_points_to: type: string enum: - dir - file title: Env Points To default: file warn_if_unset: items: type: string type: array title: Warn If Unset default: [] type: object required: - secret_name - filename - env_var - subdir title: ACPFileSecretSpec description: >- Declarative mapping from a reserved "file-content" secret to a credential file the ACP subprocess authenticates from. Some providers read their credential from a *file on disk* rather than an env var: Codex reads ``$CODEX_HOME/auth.json``; Gemini (Vertex AI) reads a service-account JSON pointed at by ``GOOGLE_APPLICATION_CREDENTIALS``. The user supplies that credential as a pasted blob — a reserved secret named :attr:`secret_name` — and :class:`~openhands.sdk.agent.ACPAgent` materialises it to :attr:`filename` under the conversation's durable per-conversation root (seed-if-absent), then sets :attr:`env_var` so the CLI can find it. Materialisation is keyed off :attr:`secret_name` (not the launch command), so a custom or aliased ``acp_command`` still works as long as the reserved secret is supplied. The SDK owns the *mechanism* (writing the file in the runtime pod, setting the env var, seed-if-absent, permissions); the *policy* — which secrets map to which files for which CLIs — lives in these specs. Built-in defaults cover the supported providers, but downstream applications can override :attr:`~openhands.sdk.agent.ACPAgent.acp_file_secrets` to support other ACP servers with different file-auth schemes without an SDK change. FallbackStrategy: properties: fallback_llms: items: type: string type: array title: Fallback Llms description: Ordered list of LLM profile names to try on transient failure. profile_store_dir: anyOf: - type: string - type: string format: path - type: 'null' title: Profile Store Dir description: >- Path to directory containing profiles. If not specified, defaults to `.openhands/profiles`. type: object required: - fallback_llms title: FallbackStrategy description: |- Encapsulates fallback behavior for LLM calls. When the primary LLM fails with a transient error (after retries), this strategy tries alternate LLMs loaded from LLMProfileStore profiles. Fallback is per-call: each new request starts with the primary model. HookType: type: string enum: - command - prompt - agent title: HookType description: Types of hooks that can be executed. MCPNoneAuthCredential: properties: strategy: type: string const: none title: Strategy type: object required: - strategy title: MCPNoneAuthCredential MCPApiKeyAuthCredential-Input: properties: strategy: type: string const: api_key title: Strategy value: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Value header_name: anyOf: - type: string - type: 'null' title: Header Name type: object required: - strategy title: MCPApiKeyAuthCredential MCPBearerAuthCredential-Input: properties: strategy: type: string const: bearer title: Strategy value: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Value type: object required: - strategy title: MCPBearerAuthCredential MCPBasicAuthCredential-Input: properties: strategy: type: string const: basic title: Strategy username: type: string title: Username password: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Password type: object required: - strategy - username title: MCPBasicAuthCredential MCPHeaderAuthCredential-Input: properties: strategy: type: string const: header title: Strategy headers: additionalProperties: type: string format: password writeOnly: true type: object title: Headers type: object required: - strategy title: MCPHeaderAuthCredential MCPOAuthAuthCredential-Input: properties: strategy: type: string const: oauth2 title: Strategy authentication: anyOf: - $ref: '#/components/schemas/MCPOAuthAuthentication-Input' - type: 'null' state: anyOf: - $ref: '#/components/schemas/MCPOAuthState-Input' - type: 'null' type: object required: - strategy title: MCPOAuthAuthCredential Skill-Input: properties: name: type: string title: Name content: type: string title: Content trigger: anyOf: - oneOf: - $ref: '#/components/schemas/KeywordTrigger' - $ref: '#/components/schemas/TaskTrigger' - $ref: '#/components/schemas/PathTrigger' discriminator: propertyName: type mapping: keyword: $ref: '#/components/schemas/KeywordTrigger' path: $ref: '#/components/schemas/PathTrigger' task: $ref: '#/components/schemas/TaskTrigger' - type: 'null' title: Trigger description: >- Trigger determines when skill content is auto-injected. None = no auto-injection (for AgentSkills: agent reads on demand; for legacy: full content always in system prompt). KeywordTrigger = auto-inject when keywords appear in user messages. TaskTrigger = auto-inject for specific tasks, may require user input. source: anyOf: - type: string - type: 'null' title: Source description: >- The source path or identifier of the skill. When it is None, it is treated as a programmatically defined skill. mcp_tools: anyOf: - additionalProperties: $ref: '#/components/schemas/MCPServer-Input' type: object - type: 'null' title: Mcp Tools description: MCP servers for the skill (repo skills only). inputs: items: $ref: '#/components/schemas/InputMetadata' type: array title: Inputs description: Input metadata for the skill (task skills only) is_agentskills_format: type: boolean title: Is Agentskills Format description: >- Whether this skill was loaded from a SKILL.md file following the AgentSkills standard. AgentSkills-format skills use progressive disclosure: always listed in with name, description, and location. If the skill also has triggers, content is auto-injected when triggered AND agent can read file anytime. default: false version: type: string title: Version description: Skill version (AgentSkills standard field). default: 1.0.0 description: anyOf: - type: string - type: 'null' title: Description description: >- A brief description of what the skill does and when to use it. Descriptions exceeding MAX_DESCRIPTION_LENGTH are truncated with a notice pointing to the skill's source path. license: anyOf: - type: string - type: 'null' title: License description: >- The license under which the skill is distributed. AgentSkills standard field (e.g., 'Apache-2.0', 'MIT'). compatibility: anyOf: - type: string - type: 'null' title: Compatibility description: >- Environment requirements or compatibility notes for the skill. AgentSkills standard field (e.g., 'Requires git and docker'). metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: >- Arbitrary key-value metadata for the skill. AgentSkills standard field for extensibility. allowed_tools: anyOf: - items: type: string type: array - type: 'null' title: Allowed Tools description: >- List of pre-approved tools for this skill. AgentSkills standard field (parsed from space-delimited string). disable_model_invocation: type: boolean title: Disable Model Invocation description: >- Whether this skill can only be activated by trigger matching and should not be advertised to the model for direct invocation. default: false resources: anyOf: - $ref: '#/components/schemas/SkillResources' - type: 'null' description: >- Resource directories for the skill (scripts/, references/, assets/). AgentSkills standard field. Only populated for SKILL.md directory format. type: object required: - name - content title: Skill description: >- A skill provides specialized knowledge or functionality. Skill behavior depends on format (is_agentskills_format) and trigger: AgentSkills format (SKILL.md files): - Always listed in with name, description, location - Agent reads full content on demand (progressive disclosure) - If has triggers: content is ALSO auto-injected when triggered Legacy OpenHands format: - With triggers: Listed in , content injected on trigger - Without triggers (None): Full content in , always active This model supports both OpenHands-specific fields and AgentSkills standard fields (https://agentskills.io/specification) for cross-platform compatibility. openhands__sdk__marketplace__registration__MarketplaceRegistration: properties: name: type: string title: Name description: Identifier for this marketplace registration source: type: string title: Source description: 'Marketplace source: ''github:owner/repo'', git URL, or local path' ref: anyOf: - type: string - type: 'null' title: Ref description: Optional branch, tag, or commit for git sources repo_path: anyOf: - type: string - type: 'null' title: Repo Path description: >- Subdirectory path within the git repository containing the marketplace. Only relevant for git sources. auto_load: anyOf: - type: boolean - items: type: string type: array title: Auto Load description: >- Whether to load marketplace plugins and standalone skills at conversation start. Use True for all, False or [] for none, or a list of plugin/skill names for selective loading. default: false type: object required: - name - source title: MarketplaceRegistration description: Registration for a marketplace source used for plugin resolution. LLMSummarizingCondenser-Input: properties: llm: $ref: '#/components/schemas/LLM-Input' max_size: type: integer exclusiveMinimum: 0 title: Max Size default: 240 max_tokens: anyOf: - type: integer - type: 'null' title: Max Tokens keep_first: type: integer minimum: 0 title: Keep First default: 2 minimum_progress: type: number exclusiveMaximum: 1 exclusiveMinimum: 0 title: Minimum Progress default: 0.1 hard_context_reset_max_retries: type: integer exclusiveMinimum: 0 title: Hard Context Reset Max Retries default: 5 hard_context_reset_context_scaling: type: number exclusiveMaximum: 1 exclusiveMinimum: 0 title: Hard Context Reset Context Scaling default: 0.8 kind: type: string const: LLMSummarizingCondenser title: Kind type: object required: - llm title: LLMSummarizingCondenser description: >- LLM-based condenser that summarizes forgotten events. Uses an independent LLM (stored in the `llm` attribute) for generating summaries of forgotten events. The optional `agent_llm` parameter passed to condense() is the LLM used by the agent for token counting purposes, and you should not assume it is the same as the one defined in this condenser. NoOpCondenser-Input: properties: kind: type: string const: NoOpCondenser title: Kind type: object title: NoOpCondenser description: |- Simple condenser that returns a view un-manipulated. Primarily intended for testing purposes. PipelineCondenser-Input: properties: condensers: items: $ref: '#/components/schemas/CondenserBase-Input' type: array title: Condensers kind: type: string const: PipelineCondenser title: Kind type: object required: - condensers title: PipelineCondenser description: >- A condenser that applies a sequence of condensers in order. All condensers are defined primarily by their `condense` method, which takes a `View` and an optional `agent_llm` parameter, returning either a new `View` or a `Condensation` event. That means we can chain multiple condensers together by passing `View`s along and exiting early if any condenser returns a `Condensation`. For example: # Use the pipeline condenser to chain multiple other condensers together condenser = PipelineCondenser(condensers=[ CondenserA(...), CondenserB(...), CondenserC(...), ]) result = condenser.condense(view, agent_llm=agent_llm) # Doing the same thing without the pipeline condenser requires more boilerplate # for the monadic chaining other_result = view if isinstance(other_result, View): other_result = CondenserA(...).condense(other_result, agent_llm=agent_llm) if isinstance(other_result, View): other_result = CondenserB(...).condense(other_result, agent_llm=agent_llm) if isinstance(other_result, View): other_result = CondenserC(...).condense(other_result, agent_llm=agent_llm) assert result == other_result AgentFinishedCritic: properties: mode: type: string enum: - finish_and_message - all_actions title: Mode description: >- When to run critic evaluation: - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) default: finish_and_message iterative_refinement: anyOf: - $ref: '#/components/schemas/IterativeRefinementConfig' - type: 'null' description: >- Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. kind: type: string const: AgentFinishedCritic title: Kind type: object title: AgentFinishedCritic description: |- Critic that evaluates whether an agent properly finished a task. This critic checks two main criteria: 1. The agent's last action was a FinishAction (proper completion) 2. The generated git patch is non-empty (actual changes were made) APIBasedCritic: properties: server_url: type: string title: Server Url description: Base URL of the vLLM classification service default: https://llm-proxy.app.all-hands.dev/vllm api_key: anyOf: - type: string - type: string format: password writeOnly: true title: Api Key description: API key for authenticating with the vLLM service model_name: type: string title: Model Name description: Name of the model to use default: critic tokenizer_name: type: string title: Tokenizer Name description: HuggingFace tokenizer name for loading chat template default: Qwen/Qwen3-4B-Instruct-2507 pass_tools_definitions: type: boolean title: Pass Tools Definitions description: Whether to pass tool definitions to the model default: true timeout_seconds: type: number title: Timeout Seconds description: Timeout for requests to the model default: 300 has_success_label: type: boolean title: Has Success Label description: Whether the model predicts success label at index 0 default: true sentiment_labels: items: type: string type: array title: Sentiment Labels default: - sentiment_positive - sentiment_neutral - sentiment_negative agent_issue_labels: items: type: string type: array title: Agent Issue Labels default: - misunderstood_intention - did_not_follow_instruction - insufficient_analysis - insufficient_clarification - improper_tool_use_or_setup - loop_behavior - insufficient_testing - insufficient_debugging - incomplete_implementation - file_management_errors - scope_creep - risky_actions_or_permission - other_agent_issue infra_labels: items: type: string type: array title: Infra Labels default: - infrastructure_external_issue - infrastructure_agent_caused_issue user_followup_labels: items: type: string type: array title: User Followup Labels default: - clarification_or_restatement - correction - direction_change - vcs_update_requests - progress_or_scope_concern - frustration_or_complaint - removal_or_reversion_request - other_user_issue sentiment_map: additionalProperties: type: string type: object title: Sentiment Map default: Positive: sentiment_positive Neutral: sentiment_neutral Negative: sentiment_negative mode: type: string enum: - finish_and_message - all_actions title: Mode description: >- When to run critic evaluation: - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) default: finish_and_message iterative_refinement: anyOf: - $ref: '#/components/schemas/IterativeRefinementConfig' - type: 'null' description: >- Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. issue_threshold: type: number maximum: 1 minimum: 0 title: Issue Threshold description: >- APIBasedCritic-specific probability threshold for agent issue labels that should trigger iterative refinement. default: 0.75 kind: type: string const: APIBasedCritic title: Kind type: object required: - api_key title: APIBasedCritic EmptyPatchCritic: properties: mode: type: string enum: - finish_and_message - all_actions title: Mode description: >- When to run critic evaluation: - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) default: finish_and_message iterative_refinement: anyOf: - $ref: '#/components/schemas/IterativeRefinementConfig' - type: 'null' description: >- Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. kind: type: string const: EmptyPatchCritic title: Kind type: object title: EmptyPatchCritic description: |- Critic that only evaluates whether a git patch is non-empty. This critic checks only one criterion: - The generated git patch is non-empty (actual changes were made) Unlike AgentFinishedCritic, this critic does not check for proper agent completion with FinishAction. PassCritic: properties: mode: type: string enum: - finish_and_message - all_actions title: Mode description: >- When to run critic evaluation: - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) default: finish_and_message iterative_refinement: anyOf: - $ref: '#/components/schemas/IterativeRefinementConfig' - type: 'null' description: >- Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. kind: type: string const: PassCritic title: Kind type: object title: PassCritic description: >- Critic that always returns success. This critic can be used when no evaluation is needed or when all instances should be considered successful regardless of their output. MCPOAuthAuthentication-Input: properties: type: type: string const: oauth title: Type client_auth_method: anyOf: - type: string enum: - none - client_secret_post - client_secret_basic - private_key_jwt - type: 'null' title: Client Auth Method scopes: anyOf: - type: string - items: type: string type: array - type: 'null' title: Scopes client_name: anyOf: - type: string - type: 'null' title: Client Name client_metadata_url: anyOf: - type: string - type: 'null' title: Client Metadata Url client_id: anyOf: - type: string - type: 'null' title: Client Id client_secret: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Client Secret additional_client_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Additional Client Metadata additionalProperties: false type: object required: - type title: MCPOAuthAuthentication MCPOAuthState-Input: properties: tokens: anyOf: - $ref: '#/components/schemas/MCPOAuthTokenState-Input' - type: 'null' client_info: anyOf: - $ref: '#/components/schemas/MCPOAuthClientInfoState-Input' - type: 'null' token_expires_at: anyOf: - type: number - type: 'null' title: Token Expires At type: object title: MCPOAuthState KeywordTrigger: properties: type: type: string const: keyword title: Type default: keyword keywords: items: type: string type: array title: Keywords type: object required: - keywords title: KeywordTrigger description: >- Trigger for keyword-based skills. These skills are activated when specific keywords appear in the user's query. TaskTrigger: properties: type: type: string const: task title: Type default: task triggers: items: type: string type: array title: Triggers type: object required: - triggers title: TaskTrigger description: >- Trigger for task-specific skills. These skills are activated for specific task types and can modify prompts. PathTrigger: properties: type: type: string const: path title: Type default: path paths: items: type: string type: array title: Paths type: object required: - paths title: PathTrigger description: >- Trigger for path-scoped skills ("rules"). These skills are activated when the agent touches a file whose path matches one of the ``paths`` glob patterns (gitignore-style ``**`` semantics). InputMetadata: properties: name: type: string title: Name description: Name of the input parameter description: type: string title: Description description: Description of the input parameter type: object required: - name - description title: InputMetadata description: Metadata for task skill inputs. SkillResources: properties: skill_root: type: string title: Skill Root description: Root directory of the skill (absolute path) scripts: items: type: string type: array title: Scripts description: List of script files in scripts/ directory (relative paths) references: items: type: string type: array title: References description: List of reference files in references/ directory (relative paths) assets: items: type: string type: array title: Assets description: List of asset files in assets/ directory (relative paths) type: object required: - skill_root title: SkillResources description: |- Resource directories for a skill (AgentSkills standard). Per the AgentSkills specification, skills can include: - scripts/: Executable scripts the agent can run - references/: Reference documentation and examples - assets/: Static assets (images, data files, etc.) IterativeRefinementConfig: properties: success_threshold: type: number maximum: 1 minimum: 0 title: Success Threshold description: Score threshold (0-1) to consider task successful. default: 0.6 max_iterations: type: integer minimum: 1 title: Max Iterations description: Maximum number of iterations before giving up. default: 3 type: object title: IterativeRefinementConfig description: |- Configuration for iterative refinement based on critic feedback. When attached to a CriticBase, the Conversation.run() method will automatically retry the task if the critic score is below the threshold. Example: critic = APIBasedCritic( server_url="...", api_key="...", model_name="critic", iterative_refinement=IterativeRefinementConfig( success_threshold=0.7, max_iterations=3, ), ) agent = Agent(llm=llm, tools=tools, critic=critic) conversation = Conversation(agent=agent, workspace=workspace) conversation.send_message("Create a calculator module...") conversation.run() # Will automatically retry if critic score < 0.7 MCPOAuthTokenState-Input: properties: access_token: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Access Token refresh_token: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Refresh Token additionalProperties: true type: object title: MCPOAuthTokenState MCPOAuthClientInfoState-Input: properties: client_secret: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Client Secret additionalProperties: true type: object title: MCPOAuthClientInfoState securitySchemes: APIKeyHeader: type: apiKey in: header name: X-Access-Token ````