> ## Documentation Index > Fetch the complete documentation index at: https://allhandsai-chore-regenerate-agent-sdk-openapi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Batch Get Conversations > Get a batch of conversations given their ids, returning null for any missing item ## OpenAPI ````yaml /openapi/agent-sdk.json get /api/conversations openapi: 3.1.0 info: description: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent title: OpenHands Agent Server version: 1.52.0 servers: [] security: [] paths: /api/conversations: get: tags: - Conversations summary: Batch Get Conversations description: |- Get a batch of conversations given their ids, returning null for any missing item operationId: batch_get_conversations_api_conversations_get parameters: - in: query name: ids required: true schema: items: format: uuid type: string title: Ids type: array - in: query name: include_skills required: false schema: default: false title: >- Whether to include ``agent.agent_context.skills`` in the response. Default ``false`` (breaking change as of this release): skills are trimmed to ``[]`` on the wire because no known consumer reads them from HTTP responses, and a stock agent inlines ~260 KB of skill content per fetch. Pass ``true`` to opt back into the legacy full-payload shape — useful only for callers that still rely on ``RemoteConversation.agent.agent_context.skills`` round-tripping over the wire. The persisted conversation state on disk and the in-memory runtime copy are untouched either way. type: boolean responses: '200': content: application/json: schema: items: anyOf: - $ref: '#/components/schemas/ConversationInfo' - type: 'null' title: Response Batch Get Conversations Api Conversations Get type: array description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error security: - APIKeyHeader: [] components: schemas: ConversationInfo: description: >- Information about a conversation running locally without a Runtime sandbox. properties: activated_knowledge_skills: description: List of activated knowledge skills name items: type: string title: Activated Knowledge Skills type: array agent: $ref: '#/components/schemas/AgentBase-Output' description: The agent running in the conversation. agent_state: additionalProperties: true description: >- Dictionary for agent-specific runtime state that persists across iterations. title: Agent State type: object 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 · ..."``). items: $ref: '#/components/schemas/ACPModelInfo' title: Available Models type: array blocked_actions: additionalProperties: type: string description: Actions blocked by PreToolUse hooks, keyed by action ID title: Blocked Actions type: object blocked_messages: additionalProperties: type: string description: Messages blocked by UserPromptSubmit hooks, keyed by message ID title: Blocked Messages type: object 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. items: $ref: '#/components/schemas/ClientToolSpec-Output' title: Client Tools type: array confirmation_policy: $ref: '#/components/schemas/ConfirmationPolicyBase-Output' default: kind: NeverConfirm created_at: format: date-time title: Created At type: string current_model_id: anyOf: - type: string - type: 'null' 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. title: Current Model Id execution_status: $ref: '#/components/schemas/ConversationExecutionStatus' default: idle forked_from_conversation_id: anyOf: - format: uuid type: string - type: 'null' description: >- ID of the conversation this one was forked from. ``None`` for conversations created directly (not via fork). title: Forked From Conversation Id forked_from_event_id: anyOf: - type: string - type: 'null' description: >- Event ID this conversation was forked at. ``None`` for non-forked conversations or whole-conversation forks. title: Forked From Event Id hook_config: anyOf: - $ref: '#/components/schemas/HookConfig' - type: 'null' description: >- Hook configuration for this conversation. Includes definitions for PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, and Stop hooks. id: description: Unique conversation ID format: uuid title: Id type: string invoked_skills: description: >- Names of progressive-disclosure skills explicitly invoked via the `invoke_skill` tool. items: type: string title: Invoked Skills type: array last_user_message_id: anyOf: - type: string - type: 'null' 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). title: Last User Message Id 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. leaf_event_id: anyOf: - type: string - type: 'null' 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. title: Leaf Event Id max_iterations: default: 500 description: Maximum number of iterations the agent can perform in a single run. exclusiveMinimum: 0 title: Max Iterations type: integer metrics: anyOf: - $ref: '#/components/schemas/MetricsSnapshot' - type: 'null' parent_conversation_id: anyOf: - format: uuid type: string - type: 'null' description: >- ID of the conversation that owns this one. ``None`` for top-level conversations. title: Parent Conversation Id persistence_dir: anyOf: - type: string - type: 'null' default: workspace/conversations description: >- Directory for persisting conversation state and events. If None, conversation will not be persisted. title: Persistence Dir runtime_info: anyOf: - $ref: '#/components/schemas/ConversationRuntimeInfo' - type: 'null' description: >- Availability of the execution runtime. Catalog responses populate this when the hosting server manages runtime lifecycle. secret_registry: $ref: '#/components/schemas/SecretRegistry' description: Registry for handling secrets and sensitive data security_analyzer: anyOf: - $ref: '#/components/schemas/SecurityAnalyzerBase-Output' - type: 'null' description: Optional security analyzer to evaluate action risks. stats: $ref: '#/components/schemas/ConversationStats' description: Conversation statistics for tracking LLM metrics stuck_detection: default: true description: Whether to enable stuck detection for the agent. title: Stuck Detection type: boolean 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. items: format: uuid type: string title: Sub Conversation Ids type: array supports_runtime_model_switch: default: false 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. title: Supports Runtime Model Switch type: boolean tags: additionalProperties: type: string description: >- Key-value tags for the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters. title: Tags type: object title: anyOf: - type: string - type: 'null' description: User-defined title for the conversation title: Title tool_module_qualnames: additionalProperties: type: string description: >- Tool names mapped to importable module qualnames. SDK clients use this metadata to restore the registrations needed to deserialize the conversation's tool events when attaching. title: Tool Module Qualnames type: object updated_at: format: date-time title: Updated At type: string workspace: $ref: '#/components/schemas/BaseWorkspace' description: >- Workspace used by the agent to execute commands and read/write files. Not the process working directory. required: - id - workspace - agent title: ConversationInfo type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object AgentBase-Output: discriminator: mapping: openhands__sdk__agent__acp_agent__ACPAgent-Output__1: '#/components/schemas/ACPAgent-Output' openhands__sdk__agent__agent__Agent-Output__1: '#/components/schemas/Agent-Output' propertyName: kind oneOf: - $ref: '#/components/schemas/ACPAgent-Output' - $ref: '#/components/schemas/Agent-Output' 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. properties: description: anyOf: - type: string - type: 'null' description: Optional longer description supplied by the server. title: Description model_id: description: >- Server-assigned model identifier. May be concrete (e.g. ``"gpt-5.6"``) or an opaque alias (e.g. ``"default"``, ``"auto"``). This is the value to pass back to the server to switch to this model. title: Model Id type: string name: anyOf: - type: string - type: 'null' description: Human-readable label, e.g. ``"GPT-5.5"``. title: Name required: - model_id title: ACPModelInfo type: object ClientToolSpec-Output: 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). properties: 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. description: description: >- Description shown to the LLM explaining when and how to use this tool. title: Description type: string name: description: Unique tool name the agent will use to call this tool. title: Name type: string parameters: additionalProperties: true description: >- JSON Schema describing the tool's input parameters. Must be an object schema. title: Parameters type: object required: - name - description title: ClientToolSpec type: object ConfirmationPolicyBase-Output: discriminator: mapping: openhands__sdk__security__confirmation_policy__AlwaysConfirm-Output__1: '#/components/schemas/AlwaysConfirm-Output' openhands__sdk__security__confirmation_policy__ConfirmRisky-Output__1: '#/components/schemas/ConfirmRisky-Output' openhands__sdk__security__confirmation_policy__NeverConfirm-Output__1: '#/components/schemas/NeverConfirm-Output' propertyName: kind oneOf: - $ref: '#/components/schemas/AlwaysConfirm-Output' - $ref: '#/components/schemas/ConfirmRisky-Output' - $ref: '#/components/schemas/NeverConfirm-Output' ConversationExecutionStatus: description: Enum representing the current execution state of the conversation. enum: - idle - running - paused - waiting_for_confirmation - finished - error - stuck - deleting title: ConversationExecutionStatus type: string HookConfig: additionalProperties: false 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") properties: post_tool_use: description: Hooks that run after tool execution items: $ref: '#/components/schemas/HookMatcher' title: Post Tool Use type: array pre_tool_use: description: Hooks that run before tool execution items: $ref: '#/components/schemas/HookMatcher' title: Pre Tool Use type: array session_end: description: Hooks that run when a session ends items: $ref: '#/components/schemas/HookMatcher' title: Session End type: array session_start: description: Hooks that run when a session starts items: $ref: '#/components/schemas/HookMatcher' title: Session Start type: array stop: description: Hooks that run when the agent attempts to stop items: $ref: '#/components/schemas/HookMatcher' title: Stop type: array user_prompt_submit: description: Hooks that run when user submits a prompt items: $ref: '#/components/schemas/HookMatcher' title: User Prompt Submit type: array title: HookConfig type: object 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. properties: agent_profile_id: description: Stable id of the agent profile that launched the conversation. format: uuid title: Agent Profile Id type: string revision: description: Revision of the agent profile at launch time. minimum: 0 title: Revision type: integer secret_refs: anyOf: - items: type: string type: array - type: 'null' description: >- Secret allow-list captured at launch, also enforced on resume. null preserves unrestricted behavior for older conversations. title: Secret Refs required: - agent_profile_id - revision title: LaunchedAgentProfile type: object MetricsSnapshot: description: |- A snapshot of metrics at a point in time. Does not include lists of individual costs, latencies, or token usages. properties: accumulated_cost: default: 0 description: Total accumulated cost, must be non-negative minimum: 0 title: Accumulated Cost type: number accumulated_token_usage: anyOf: - $ref: '#/components/schemas/TokenUsage' - type: 'null' description: Accumulated token usage across all calls max_budget_per_task: anyOf: - type: number - type: 'null' description: Maximum budget per task title: Max Budget Per Task model_name: default: default description: Name of the model title: Model Name type: string title: MetricsSnapshot type: object ConversationRuntimeInfo: description: Runtime availability and recovery information for a conversation. properties: can_resume: title: Can Resume type: boolean runtime_error: anyOf: - $ref: '#/components/schemas/ConversationRuntimeError' - type: 'null' runtime_status: $ref: '#/components/schemas/ConversationRuntimeStatus' required: - runtime_status - can_resume title: ConversationRuntimeInfo type: object 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. properties: secret_sources: additionalProperties: $ref: '#/components/schemas/SecretSource-Output' title: Secret Sources type: object title: SecretRegistry type: object SecurityAnalyzerBase-Output: discriminator: mapping: openhands__sdk__security__defense_in_depth__pattern__PatternSecurityAnalyzer-Output__1: '#/components/schemas/PatternSecurityAnalyzer-Output' openhands__sdk__security__defense_in_depth__policy_rails__PolicyRailSecurityAnalyzer-Output__1: '#/components/schemas/PolicyRailSecurityAnalyzer-Output' openhands__sdk__security__ensemble__EnsembleSecurityAnalyzer-Output__1: '#/components/schemas/EnsembleSecurityAnalyzer-Output' openhands__sdk__security__grayswan__analyzer__GraySwanAnalyzer-Output__1: '#/components/schemas/GraySwanAnalyzer-Output' openhands__sdk__security__llm_analyzer__LLMSecurityAnalyzer-Output__1: '#/components/schemas/LLMSecurityAnalyzer-Output' openhands__sdk__security__toolshield_llm_analyzer__ToolShieldLLMSecurityAnalyzer-Output__1: '#/components/schemas/ToolShieldLLMSecurityAnalyzer-Output' propertyName: kind oneOf: - $ref: '#/components/schemas/PatternSecurityAnalyzer-Output' - $ref: '#/components/schemas/PolicyRailSecurityAnalyzer-Output' - $ref: '#/components/schemas/EnsembleSecurityAnalyzer-Output' - $ref: '#/components/schemas/GraySwanAnalyzer-Output' - $ref: '#/components/schemas/LLMSecurityAnalyzer-Output' - $ref: '#/components/schemas/ToolShieldLLMSecurityAnalyzer-Output' ConversationStats: additionalProperties: true type: object BaseWorkspace: discriminator: mapping: openhands__sdk__workspace__local__LocalWorkspace-Output__1: '#/components/schemas/LocalWorkspace-Output' openhands__sdk__workspace__remote__base__RemoteWorkspace-Output__1: '#/components/schemas/RemoteWorkspace' propertyName: kind oneOf: - $ref: '#/components/schemas/LocalWorkspace-Output' - $ref: '#/components/schemas/RemoteWorkspace' ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object ACPAgent-Output: description: Agent that delegates to an ACP-compatible subprocess server. properties: acp_args: description: Additional arguments for the ACP server command items: type: string title: Acp Args type: array acp_command: description: >- Command to start the ACP server, e.g. ['npx', '-y', '@agentclientprotocol/claude-agent-acp'] items: type: string title: Acp Command type: array 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. items: $ref: '#/components/schemas/ACPFileSecretSpec' title: Acp File Secrets type: array acp_isolate_data_dir: default: false 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. title: Acp Isolate Data Dir type: boolean acp_model: anyOf: - type: string - type: 'null' 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. title: Acp Model acp_prompt_timeout: default: 1800 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. title: Acp Prompt Timeout type: number acp_resume_session_id: anyOf: - type: string - type: 'null' 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. title: Acp Resume Session Id acp_server: anyOf: - type: string - type: 'null' description: >- Provider registry key identifying which ACP CLI this agent runs (any ACP_PROVIDERS key, 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. title: Acp Server acp_session_mode: anyOf: - type: string - type: 'null' 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; a provider with no such mode (pi-acp) skips the call. title: Acp Session Mode acp_startup_timeout: default: 90 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. title: Acp Startup Timeout type: number agent_context: anyOf: - $ref: '#/components/schemas/AgentContext-Output' - 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' condenser: anyOf: - $ref: '#/components/schemas/CondenserBase-Output' - 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-Output' - 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 filter_tools_regex: anyOf: - type: string - type: 'null' 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.*$ title: Filter Tools Regex include_default_tools: items: type: string title: Include Default Tools type: array kind: const: ACPAgent title: Kind type: string llm: $ref: '#/components/schemas/LLM-Output' mcp_config: additionalProperties: $ref: '#/components/schemas/MCPServer-Output' description: Optional MCP servers to expose as tools. examples: - fetch: args: - '--with' - mcp==1.29.0 - mcp-server-fetch==2026.7.10 command: uvx title: Mcp Config type: object security_policy_filename: default: security_policy.j2 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 title: Security Policy Filename type: string system_prompt: anyOf: - type: string - type: 'null' 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. title: System Prompt system_prompt_filename: default: system_prompt.j2 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') title: System Prompt Filename type: string system_prompt_kwargs: additionalProperties: true description: Optional kwargs to pass to the system prompt Jinja2 template. examples: - cli_mode: true title: System Prompt Kwargs type: object tool_concurrency_limit: default: 1 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. minimum: 1 title: Tool Concurrency Limit type: integer tools: items: $ref: '#/components/schemas/openhands__sdk__tool__spec__Tool' title: Tools type: array required: - acp_command - kind title: ACPAgent type: object Agent-Output: 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.6", 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.", ) properties: agent_context: anyOf: - $ref: '#/components/schemas/AgentContext-Output' - 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' condenser: anyOf: - $ref: '#/components/schemas/CondenserBase-Output' - 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-Output' - 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 filter_tools_regex: anyOf: - type: string - type: 'null' 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.*$ title: Filter Tools Regex 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 - [] items: type: string title: Include Default Tools type: array kind: const: Agent title: Kind type: string llm: $ref: '#/components/schemas/LLM-Output' 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 mcp_config: additionalProperties: $ref: '#/components/schemas/MCPServer-Output' description: Optional MCP servers to expose as tools. examples: - fetch: args: - '--with' - mcp==1.29.0 - mcp-server-fetch==2026.7.10 command: uvx title: Mcp Config type: object persona: anyOf: - type: string - type: 'null' description: >- Persona text that replaces OpenHands' built-in persona and coding-workflow sections of the system prompt. Capability and policy sections (memory, security policy, risk assessment, browser, external services, process management, model-specific guidance) and the dynamic context still apply. Ignored when `system_prompt` is set; a custom template receives it as the `persona` kwarg. title: Persona security_policy_filename: default: security_policy.j2 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 title: Security Policy Filename type: string system_prompt: anyOf: - type: string - type: 'null' 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. title: System Prompt system_prompt_filename: default: system_prompt.j2 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') title: System Prompt Filename type: string system_prompt_kwargs: additionalProperties: true description: Optional kwargs to pass to the system prompt Jinja2 template. examples: - cli_mode: true title: System Prompt Kwargs type: object tool_concurrency_limit: default: 1 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. minimum: 1 title: Tool Concurrency Limit type: integer tools: description: List of tools to initialize for the agent. examples: - name: TerminalTool params: {} - name: FileEditorTool params: {} - name: TaskTrackerTool params: {} items: $ref: '#/components/schemas/openhands__sdk__tool__spec__Tool' title: Tools type: array required: - llm - kind title: Agent type: object 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 properties: destructiveHint: default: true 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 title: Destructivehint type: boolean idempotentHint: default: false 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 title: Idempotenthint type: boolean openWorldHint: default: true 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 title: Openworldhint type: boolean readOnlyHint: default: false description: 'If true, the tool does not modify its environment. Default: false' title: Readonlyhint type: boolean title: anyOf: - type: string - type: 'null' description: A human-readable title for the tool. title: Title title: openhands.sdk.tool.tool.ToolAnnotations type: object AlwaysConfirm-Output: properties: kind: const: AlwaysConfirm title: Kind type: string required: - kind title: AlwaysConfirm type: object ConfirmRisky-Output: properties: confirm_unknown: default: true title: Confirm Unknown type: boolean kind: const: ConfirmRisky title: Kind type: string threshold: $ref: '#/components/schemas/SecurityRisk' default: HIGH required: - kind title: ConfirmRisky type: object NeverConfirm-Output: properties: kind: const: NeverConfirm title: Kind type: string required: - kind title: NeverConfirm type: object HookMatcher: description: >- Matches events to hooks based on patterns. Supports exact match, wildcard (*), and regex (auto-detected or /pattern/). properties: hooks: items: $ref: '#/components/schemas/HookDefinition' title: Hooks type: array matcher: default: '*' title: Matcher type: string title: HookMatcher type: object TokenUsage: description: Metric tracking detailed token usage per completion call. properties: cache_read_tokens: default: 0 description: Cache read tokens must be non-negative minimum: 0 title: Cache Read Tokens type: integer cache_write_tokens: default: 0 description: Cache write tokens must be non-negative minimum: 0 title: Cache Write Tokens type: integer completion_tokens: default: 0 description: Completion tokens must be non-negative minimum: 0 title: Completion Tokens type: integer context_window: default: 0 description: Context window must be non-negative minimum: 0 title: Context Window type: integer model: default: '' title: Model type: string per_turn_token: default: 0 description: Per turn tokens must be non-negative minimum: 0 title: Per Turn Token type: integer prompt_tokens: default: 0 description: Prompt tokens must be non-negative minimum: 0 title: Prompt Tokens type: integer reasoning_tokens: default: 0 description: Reasoning tokens must be non-negative minimum: 0 title: Reasoning Tokens type: integer response_id: default: '' title: Response Id type: string title: TokenUsage type: object ConversationRuntimeError: description: Structured details for the latest runtime lifecycle failure. properties: code: title: Code type: string message: title: Message type: string required: - code - message title: ConversationRuntimeError type: object ConversationRuntimeStatus: description: Availability of the runtime that executes a conversation. enum: - available - starting - missing - ownership_lost - error title: ConversationRuntimeStatus type: string SecretSource-Output: discriminator: mapping: openhands__sdk__secret__secrets__LookupSecret-Output__1: '#/components/schemas/LookupSecret-Output' openhands__sdk__secret__secrets__StaticSecret-Output__1: '#/components/schemas/StaticSecret-Output' propertyName: kind oneOf: - $ref: '#/components/schemas/LookupSecret-Output' - $ref: '#/components/schemas/StaticSecret-Output' PatternSecurityAnalyzer-Output: 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) properties: high_patterns: description: HIGH patterns scanned against executable fields only items: maxItems: 3 minItems: 3 prefixItems: - type: string - type: string - type: string type: array title: High Patterns type: array injection_high_patterns: description: HIGH patterns scanned against all fields items: maxItems: 3 minItems: 3 prefixItems: - type: string - type: string - type: string type: array title: Injection High Patterns type: array injection_medium_patterns: description: MEDIUM patterns scanned against all fields items: maxItems: 3 minItems: 3 prefixItems: - type: string - type: string - type: string type: array title: Injection Medium Patterns type: array kind: const: PatternSecurityAnalyzer title: Kind type: string medium_patterns: description: MEDIUM patterns scanned against executable fields only items: maxItems: 3 minItems: 3 prefixItems: - type: string - type: string - type: string type: array title: Medium Patterns type: array required: - kind title: PatternSecurityAnalyzer type: object PolicyRailSecurityAnalyzer-Output: 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) properties: kind: const: PolicyRailSecurityAnalyzer title: Kind type: string required: - kind title: PolicyRailSecurityAnalyzer type: object EnsembleSecurityAnalyzer-Output: 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) properties: analyzers: description: Analyzers whose assessments are combined via max-severity items: $ref: '#/components/schemas/SecurityAnalyzerBase-Output' minItems: 1 title: Analyzers type: array kind: const: EnsembleSecurityAnalyzer title: Kind type: string propagate_unknown: default: false 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. title: Propagate Unknown type: boolean required: - analyzers - kind title: EnsembleSecurityAnalyzer type: object GraySwanAnalyzer-Output: 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) properties: api_key: anyOf: - format: password type: string writeOnly: true - type: 'null' description: GraySwan API key (via GRAYSWAN_API_KEY env var) title: Api Key api_url: default: https://api.grayswan.ai/cygnal/monitor description: GraySwan Cygnal API endpoint title: Api Url type: string history_limit: default: 20 description: Number of recent events to include as context title: History Limit type: integer kind: const: GraySwanAnalyzer title: Kind type: string low_threshold: default: 0.3 description: Risk threshold for LOW classification (score <= threshold) title: Low Threshold type: number max_message_chars: default: 30000 description: Max characters for conversation processing title: Max Message Chars type: integer medium_threshold: default: 0.7 description: Risk threshold for MEDIUM classification (score <= threshold) title: Medium Threshold type: number policy_id: anyOf: - type: string - type: 'null' description: GraySwan policy ID (via GRAYSWAN_POLICY_ID env var) title: Policy Id timeout: default: 30 description: Request timeout in seconds title: Timeout type: number required: - kind title: GraySwanAnalyzer type: object LLMSecurityAnalyzer-Output: 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. properties: kind: const: LLMSecurityAnalyzer title: Kind type: string required: - kind title: LLMSecurityAnalyzer type: object ToolShieldLLMSecurityAnalyzer-Output: 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. properties: history_window: default: 20 description: Number of prior actions to include as context. title: History Window type: integer kind: const: ToolShieldLLMSecurityAnalyzer title: Kind type: string llm: $ref: '#/components/schemas/LLM-Output' 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. safety_experiences: default: '' 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. title: Safety Experiences type: string required: - llm - kind title: ToolShieldLLMSecurityAnalyzer type: object LocalWorkspace-Output: 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") properties: kind: const: LocalWorkspace title: Kind type: string 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. title: Working Dir type: string required: - working_dir - kind title: LocalWorkspace type: object 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") properties: api_key: anyOf: - type: string - type: 'null' description: API key for authenticating with the remote host. title: Api Key host: description: The remote host URL for the workspace. title: Host type: string kind: const: RemoteWorkspace title: Kind type: string max_connections: anyOf: - type: integer - type: 'null' description: >- Maximum number of connections for httpx.Client. None means no limit, useful for running many conversations in parallel. title: Max Connections read_timeout: default: 600 description: Timeout in seconds for reading operations of httpx.Client. title: Read Timeout type: number runtime_conversation_id: anyOf: - format: uuid type: string - type: 'null' description: Conversation runtime scope; None uses the host workspace. title: Runtime Conversation Id working_dir: description: The working directory for agent operations and tool execution. title: Working Dir type: string required: - working_dir - host - kind title: RemoteWorkspace type: object 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. properties: env_points_to: default: file enum: - dir - file title: Env Points To type: string env_var: minLength: 1 title: Env Var type: string filename: minLength: 1 title: Filename type: string secret_name: minLength: 1 title: Secret Name type: string subdir: minLength: 1 title: Subdir type: string warn_if_unset: default: [] items: type: string title: Warn If Unset type: array required: - secret_name - filename - env_var - subdir title: ACPFileSecretSpec type: object AgentContext-Output: 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. properties: current_datetime: acp_compatible: true anyOf: - format: date-time type: string - type: string - type: 'null' 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. title: Current Datetime disabled_skills: acp_compatible: true 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). items: type: string title: Disabled Skills type: array load_memory: acp_compatible: true default: false 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. openhands_settings: depends_on: [] label: Persistent memory prominence: major title: Load Memory type: boolean load_project_skills: acp_compatible: true default: false 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`. title: Load Project Skills type: boolean load_public_skills: acp_compatible: true default: false 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. title: Load Public Skills type: boolean load_user_skills: acp_compatible: true default: false description: >- Whether to automatically load user skills from ~/.openhands/skills/ and ~/.openhands/microagents/ (for backward compatibility). title: Load User Skills type: boolean marketplace_path: acp_compatible: true anyOf: - type: string - type: 'null' default: marketplaces/default.json description: >- Relative marketplace JSON path within the public skills repository. Set to None to load all public skills without marketplace filtering. title: Marketplace Path registered_marketplaces: acp_compatible: true description: >- Marketplace registrations for plugin resolution. Registrations with auto_load=True or a list of plugin names are resolved by LocalConversation at startup. items: $ref: '#/components/schemas/MarketplaceRegistration' title: Registered Marketplaces type: array secrets: acp_compatible: true anyOf: - additionalProperties: true type: object - type: 'null' 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). title: Secrets skills: acp_compatible: true description: List of available skills that can extend the user's input. items: $ref: '#/components/schemas/Skill-Output' title: Skills type: array system_message_suffix: acp_compatible: true anyOf: - type: string - type: 'null' description: Optional suffix to append to the system prompt. title: System Message Suffix user_message_suffix: acp_compatible: true anyOf: - type: string - type: 'null' description: Optional suffix to append to the user's message. title: User Message Suffix title: AgentContext type: object CondenserBase-Output: discriminator: mapping: openhands__sdk__context__condenser__llm_summarizing_condenser__LLMSummarizingCondenser-Output__1: '#/components/schemas/LLMSummarizingCondenser-Output' openhands__sdk__context__condenser__no_op_condenser__NoOpCondenser-Output__1: '#/components/schemas/NoOpCondenser-Output' openhands__sdk__context__condenser__pipeline_condenser__PipelineCondenser-Output__1: '#/components/schemas/PipelineCondenser-Output' propertyName: kind oneOf: - $ref: '#/components/schemas/LLMSummarizingCondenser-Output' - $ref: '#/components/schemas/NoOpCondenser-Output' - $ref: '#/components/schemas/PipelineCondenser-Output' CriticBase-Output: discriminator: mapping: openhands__sdk__critic__impl__agent_finished__AgentFinishedCritic-Output__1: '#/components/schemas/AgentFinishedCritic-Output' openhands__sdk__critic__impl__api__critic__APIBasedCritic-Output__1: '#/components/schemas/APIBasedCritic-Output' openhands__sdk__critic__impl__empty_patch__EmptyPatchCritic-Output__1: '#/components/schemas/EmptyPatchCritic-Output' openhands__sdk__critic__impl__pass_critic__PassCritic-Output__1: '#/components/schemas/PassCritic-Output' propertyName: kind oneOf: - $ref: '#/components/schemas/AgentFinishedCritic-Output' - $ref: '#/components/schemas/APIBasedCritic-Output' - $ref: '#/components/schemas/EmptyPatchCritic-Output' - $ref: '#/components/schemas/PassCritic-Output' LLM-Output: 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.6"). 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.6", api_key=SecretStr("your-api-key"), usage_id="my-agent" ) # Use with agent or conversation ``` properties: api_key: anyOf: - type: string - format: password type: string writeOnly: true - type: 'null' description: API key. openhands_settings: depends_on: [] label: API Key prominence: critical title: Api Key api_mode: default: auto 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. enum: - auto - chat - responses openhands_settings: depends_on: [] prominence: minor title: Api Mode type: string api_version: anyOf: - type: string - type: 'null' description: API version (e.g., Azure). openhands_settings: depends_on: [] prominence: minor title: Api Version auth_type: default: api_key description: Authentication mode for the LLM. enum: - api_key - subscription openhands_settings: depends_on: [] label: Authentication prominence: critical title: Auth Type type: string aws_access_key_id: anyOf: - type: string - format: password type: string writeOnly: true - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Access Key Id aws_bedrock_runtime_endpoint: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Bedrock Runtime Endpoint aws_profile_name: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Profile Name aws_region_name: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Region Name aws_role_name: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Role Name aws_secret_access_key: anyOf: - type: string - format: password type: string writeOnly: true - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Secret Access Key aws_session_name: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Session Name aws_session_token: anyOf: - type: string - format: password type: string writeOnly: true - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Session Token base_url: anyOf: - type: string - type: 'null' description: Custom base URL. openhands_settings: depends_on: [] prominence: major title: Base Url caching_prompt: default: true description: Enable caching of prompts. openhands_settings: depends_on: [] prominence: minor title: Caching Prompt type: boolean capability_overrides: additionalProperties: anyOf: - type: boolean - type: string 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 title: Capability Overrides type: object custom_tokenizer: anyOf: - type: string - type: 'null' description: A custom tokenizer to use for token counting. openhands_settings: depends_on: [] prominence: minor title: Custom Tokenizer disable_stop_word: anyOf: - type: boolean - type: 'null' default: false description: Disable using of stop word. openhands_settings: depends_on: [] prominence: minor title: Disable Stop Word disable_vision: anyOf: - type: boolean - type: 'null' description: >- If model is vision capable, this option allows to disable image processing (useful for cost reduction). openhands_settings: depends_on: [] prominence: minor title: Disable Vision drop_params: default: true openhands_settings: depends_on: [] prominence: minor title: Drop Params type: boolean enable_encrypted_reasoning: default: true description: >- If True, ask for ['reasoning.encrypted_content'] in Responses API include. openhands_settings: depends_on: [] prominence: minor title: Enable Encrypted Reasoning type: boolean extended_thinking_budget: anyOf: - type: integer - type: 'null' default: 200000 description: >- Legacy token budget for models confirmed to use manual Anthropic extended thinking. Ignored for adaptive-thinking models. Prefer reasoning_effort for new integrations. openhands_settings: depends_on: [] prominence: minor title: Extended Thinking Budget extra_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' description: Optional HTTP headers to forward to LiteLLM requests. openhands_settings: depends_on: [] prominence: minor title: Extra Headers force_string_serializer: anyOf: - type: boolean - type: 'null' 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 title: Force String Serializer inline_image_urls: anyOf: - type: boolean - type: 'null' 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 title: Inline Image Urls input_cost_per_token: anyOf: - minimum: 0 type: number - type: 'null' description: The cost per input token. This will available in logs for user. openhands_settings: depends_on: [] prominence: minor title: Input Cost Per Token is_subscription: description: >- Whether this LLM uses subscription-based authentication. Serialized so that subscription-specific request handling survives transport to a remote agent-server. readOnly: true title: Is Subscription type: boolean litellm_extra_body: additionalProperties: true 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 title: Litellm Extra Body type: object log_completions: default: false description: Enable logging of completions. openhands_settings: depends_on: [] prominence: minor title: Log Completions type: boolean log_completions_folder: default: logs/completions description: >- The folder to log LLM completions to. Required if log_completions is True. openhands_settings: depends_on: [] prominence: minor title: Log Completions Folder type: string max_input_tokens: anyOf: - minimum: 1 type: integer - type: 'null' 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 title: Max Input Tokens max_message_chars: default: 30000 description: Approx max chars in each event/content sent to the LLM. minimum: 1 openhands_settings: depends_on: [] prominence: minor title: Max Message Chars type: integer max_output_tokens: anyOf: - minimum: 1 type: integer - type: 'null' description: The maximum number of output tokens. This is sent to the LLM. openhands_settings: depends_on: [] prominence: minor title: Max Output Tokens model: default: gpt-5.6 description: Model name. openhands_settings: depends_on: [] prominence: critical title: Model type: string model_canonical_name: anyOf: - type: string - type: 'null' 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 title: Model Canonical Name native_tool_calling: default: true description: Whether to use native tool calling. openhands_settings: depends_on: [] prominence: minor title: Native Tool Calling type: boolean num_retries: default: 5 minimum: 0 openhands_settings: depends_on: [] prominence: minor title: Num Retries type: integer ollama_base_url: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Ollama Base Url openrouter_app_name: default: OpenHands openhands_settings: depends_on: [] prominence: minor title: Openrouter App Name type: string openrouter_site_url: default: https://docs.all-hands.dev/ openhands_settings: depends_on: [] prominence: minor title: Openrouter Site Url type: string output_cost_per_token: anyOf: - minimum: 0 type: number - type: 'null' description: The cost per output token. This will available in logs for user. openhands_settings: depends_on: [] prominence: minor title: Output Cost Per Token prompt_cache_retention: anyOf: - type: string - type: 'null' default: 24h 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. openhands_settings: depends_on: [] prominence: minor title: Prompt Cache Retention provider_connection_id: anyOf: - type: string - type: 'null' description: >- Optional provider connection whose shared API key and base URL are resolved and applied each time this LLM profile is loaded (read-at-use). When set, the profile stores no inline api_key or base_url of its own. openhands_settings: depends_on: [] prominence: major title: Provider Connection Id reasoning_effort: anyOf: - enum: - low - medium - high - xhigh - none type: string - type: 'null' default: high 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. openhands_settings: depends_on: [] prominence: minor title: Reasoning Effort reasoning_summary: anyOf: - enum: - auto - concise - detailed type: string - type: 'null' 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 title: Reasoning Summary retry_max_wait: default: 64 minimum: 0 openhands_settings: depends_on: [] prominence: minor title: Retry Max Wait type: integer retry_min_wait: default: 8 minimum: 0 openhands_settings: depends_on: [] prominence: minor title: Retry Min Wait type: integer retry_multiplier: default: 8 minimum: 0 openhands_settings: depends_on: [] prominence: minor title: Retry Multiplier type: number seed: anyOf: - type: integer - type: 'null' description: The seed to use for random number generation. openhands_settings: depends_on: [] prominence: minor title: Seed stream: default: false 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. openhands_settings: depends_on: [] prominence: minor title: Stream type: boolean stream_idle_timeout: anyOf: - minimum: 0 type: number - type: 'null' default: 300 description: >- Maximum seconds between chunks in an asynchronous streaming response. Default is 300s (5 minutes); set to None to disable. openhands_settings: depends_on: [] prominence: minor title: Stream Idle Timeout subscription_vendor: anyOf: - const: openai type: string - type: 'null' description: Subscription provider for subscription-backed LLM access. openhands_settings: depends_on: - auth_type label: Subscription provider prominence: critical title: Subscription Vendor temperature: anyOf: - minimum: 0 type: number - type: 'null' 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 title: Temperature timeout: anyOf: - minimum: 0 type: integer - type: 'null' default: 300 description: >- HTTP and hard per-attempt timeout in seconds. Default is 300s (5 minutes). Set to None to disable the hard timeout. openhands_settings: depends_on: [] prominence: minor title: Timeout top_k: anyOf: - minimum: 0 type: number - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Top K top_p: anyOf: - maximum: 1 minimum: 0 type: number - type: 'null' 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 title: Top P usage_id: default: default description: >- Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking. openhands_settings: depends_on: [] prominence: minor title: Usage Id type: string required: - is_subscription title: LLM type: object MCPServer-Output: additionalProperties: false description: One MCP server in the settings DataModel. properties: args: anyOf: - items: type: string type: array - type: 'null' title: Args auth: anyOf: - discriminator: mapping: api_key: '#/components/schemas/MCPApiKeyAuthCredential-Output' basic: '#/components/schemas/MCPBasicAuthCredential-Output' bearer: '#/components/schemas/MCPBearerAuthCredential-Output' header: '#/components/schemas/MCPHeaderAuthCredential-Output' none: '#/components/schemas/MCPNoneAuthCredential' oauth2: '#/components/schemas/MCPOAuthAuthCredential-Output' propertyName: strategy oneOf: - $ref: '#/components/schemas/MCPNoneAuthCredential' - $ref: '#/components/schemas/MCPApiKeyAuthCredential-Output' - $ref: '#/components/schemas/MCPBearerAuthCredential-Output' - $ref: '#/components/schemas/MCPBasicAuthCredential-Output' - $ref: '#/components/schemas/MCPHeaderAuthCredential-Output' - $ref: '#/components/schemas/MCPOAuthAuthCredential-Output' - type: 'null' title: Auth command: anyOf: - minLength: 1 type: string - type: 'null' title: Command cwd: anyOf: - type: string - type: 'null' title: Cwd description: anyOf: - type: string - type: 'null' title: Description enabled: default: true 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. title: Enabled type: boolean env: anyOf: - additionalProperties: anyOf: - type: string - type: 'null' type: object - type: 'null' title: Env headers: anyOf: - additionalProperties: anyOf: - type: string - type: 'null' type: object - type: 'null' title: Headers icon: anyOf: - type: string - type: 'null' title: Icon keep_alive: anyOf: - type: boolean - type: 'null' title: Keep Alive sse_read_timeout: anyOf: - type: number - type: 'null' title: Sse Read Timeout timeout: anyOf: - type: number - type: 'null' title: Timeout transport: anyOf: - enum: - stdio - http - sse - streamable-http type: string - type: 'null' title: Transport url: anyOf: - minLength: 1 type: string - type: 'null' title: Url title: MCPServer type: object openhands__sdk__tool__spec__Tool: description: |- Defines a tool to be initialized for the agent. This is only used in agent-sdk for type schema for server use. properties: name: description: >- Name of the tool class, e.g., 'TerminalTool'. Import it from an `openhands.tools.` subpackage. examples: - TerminalTool - FileEditorTool - TaskTrackerTool title: Name type: string params: additionalProperties: true description: >- Parameters for the tool's .create() method, e.g., {'working_dir': '/app'} examples: - working_dir: /workspace title: Params type: object required: - name title: Tool type: object 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. enum: - UNKNOWN - LOW - MEDIUM - HIGH title: SecurityRisk type: string HookDefinition: description: A single hook definition. properties: async: default: false title: Async type: boolean command: title: Command type: string max_iterations: default: 3 title: Max Iterations type: integer name: anyOf: - type: string - type: 'null' title: Name prompt: anyOf: - type: string - type: 'null' title: Prompt system_prompt: anyOf: - type: string - type: 'null' title: System Prompt timeout: default: 60 title: Timeout type: integer tools: items: type: string title: Tools type: array type: $ref: '#/components/schemas/HookType' default: command required: - command title: HookDefinition type: object LookupSecret-Output: description: A secret looked up from some external url properties: description: anyOf: - type: string - type: 'null' description: Optional description for this secret title: Description headers: additionalProperties: type: string title: Headers type: object kind: const: LookupSecret title: Kind type: string url: title: Url type: string required: - url - kind title: LookupSecret type: object StaticSecret-Output: description: A secret stored locally properties: description: anyOf: - type: string - type: 'null' description: Optional description for this secret title: Description kind: const: StaticSecret title: Kind type: string value: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Value required: - kind title: StaticSecret type: object MarketplaceRegistration: description: Registration for a marketplace source used for plugin resolution. properties: auto_load: anyOf: - type: boolean - items: type: string type: array default: false 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. title: Auto Load name: description: Identifier for this marketplace registration title: Name type: string ref: anyOf: - type: string - type: 'null' description: Optional branch, tag, or commit for git sources title: Ref repo_path: anyOf: - type: string - type: 'null' description: >- Subdirectory path within the git repository containing the marketplace. Only relevant for git sources. title: Repo Path source: description: 'Marketplace source: ''github:owner/repo'', git URL, or local path' title: Source type: string required: - name - source title: MarketplaceRegistration type: object Skill-Output: 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. properties: allowed_tools: anyOf: - items: type: string type: array - type: 'null' description: >- List of pre-approved tools for this skill. AgentSkills standard field (parsed from space-delimited string). title: Allowed Tools compatibility: anyOf: - type: string - type: 'null' description: >- Environment requirements or compatibility notes for the skill. AgentSkills standard field (e.g., 'Requires git and docker'). title: Compatibility content: title: Content type: string description: anyOf: - type: string - type: 'null' 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. title: Description disable_model_invocation: default: false description: >- Whether this skill can only be activated by trigger matching and should not be advertised to the model for direct invocation. title: Disable Model Invocation type: boolean inputs: description: Input metadata for the skill (task skills only) items: $ref: '#/components/schemas/InputMetadata' title: Inputs type: array is_agentskills_format: default: false 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. title: Is Agentskills Format type: boolean license: anyOf: - type: string - type: 'null' description: >- The license under which the skill is distributed. AgentSkills standard field (e.g., 'Apache-2.0', 'MIT'). title: License mcp_tools: anyOf: - additionalProperties: additionalProperties: true type: object type: object - type: 'null' description: MCP servers for the skill (repo skills only). title: Mcp Tools metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' description: >- Arbitrary key-value metadata for the skill. AgentSkills standard field for extensibility. title: Metadata name: title: Name type: string 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. source: anyOf: - type: string - type: 'null' description: >- The source path or identifier of the skill. When it is None, it is treated as a programmatically defined skill. title: Source trigger: anyOf: - discriminator: mapping: keyword: '#/components/schemas/KeywordTrigger' path: '#/components/schemas/PathTrigger' task: '#/components/schemas/TaskTrigger' propertyName: type oneOf: - $ref: '#/components/schemas/KeywordTrigger' - $ref: '#/components/schemas/TaskTrigger' - $ref: '#/components/schemas/PathTrigger' - type: 'null' 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. title: Trigger version: default: 1.0.0 description: Skill version (AgentSkills standard field). title: Version type: string required: - name - content title: Skill type: object LLMSummarizingCondenser-Output: 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. properties: hard_context_reset_context_scaling: default: 0.8 exclusiveMaximum: 1 exclusiveMinimum: 0 title: Hard Context Reset Context Scaling type: number hard_context_reset_max_retries: default: 5 exclusiveMinimum: 0 title: Hard Context Reset Max Retries type: integer keep_first: default: 2 minimum: 0 title: Keep First type: integer kind: const: LLMSummarizingCondenser title: Kind type: string llm: $ref: '#/components/schemas/LLM-Output' max_size: default: 240 exclusiveMinimum: 0 title: Max Size type: integer max_tokens: anyOf: - type: integer - type: 'null' title: Max Tokens minimum_progress: default: 0.1 exclusiveMaximum: 1 exclusiveMinimum: 0 title: Minimum Progress type: number required: - llm - kind title: LLMSummarizingCondenser type: object NoOpCondenser-Output: description: |- Simple condenser that returns a view un-manipulated. Primarily intended for testing purposes. properties: kind: const: NoOpCondenser title: Kind type: string required: - kind title: NoOpCondenser type: object PipelineCondenser-Output: 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 properties: condensers: items: $ref: '#/components/schemas/CondenserBase-Output' title: Condensers type: array kind: const: PipelineCondenser title: Kind type: string required: - condensers - kind title: PipelineCondenser type: object AgentFinishedCritic-Output: 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) properties: 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: const: AgentFinishedCritic title: Kind type: string mode: default: finish_and_message 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) enum: - finish_and_message - all_actions title: Mode type: string required: - kind title: AgentFinishedCritic type: object APIBasedCritic-Output: properties: 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 items: type: string title: Agent Issue Labels type: array api_key: anyOf: - type: string - format: password type: string writeOnly: true description: API key for authenticating with the vLLM service title: Api Key has_success_label: default: true description: Whether the model predicts success label at index 0 title: Has Success Label type: boolean infra_labels: default: - infrastructure_external_issue - infrastructure_agent_caused_issue items: type: string title: Infra Labels type: array issue_threshold: default: 0.75 description: >- APIBasedCritic-specific probability threshold for agent issue labels that should trigger iterative refinement. maximum: 1 minimum: 0 title: Issue Threshold type: number 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: const: APIBasedCritic title: Kind type: string mode: default: finish_and_message 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) enum: - finish_and_message - all_actions title: Mode type: string model_name: default: critic description: Name of the model to use title: Model Name type: string pass_tools_definitions: default: true description: Whether to pass tool definitions to the model title: Pass Tools Definitions type: boolean sentiment_labels: default: - sentiment_positive - sentiment_neutral - sentiment_negative items: type: string title: Sentiment Labels type: array sentiment_map: additionalProperties: type: string default: Negative: sentiment_negative Neutral: sentiment_neutral Positive: sentiment_positive title: Sentiment Map type: object server_url: default: https://llm-proxy.app.all-hands.dev/vllm description: Base URL of the vLLM classification service title: Server Url type: string timeout_seconds: default: 300 description: Timeout for requests to the model title: Timeout Seconds type: number tokenizer_name: default: Qwen/Qwen3-4B-Instruct-2507 description: HuggingFace tokenizer name for loading chat template title: Tokenizer Name type: string 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 items: type: string title: User Followup Labels type: array required: - api_key - kind title: APIBasedCritic type: object EmptyPatchCritic-Output: 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. properties: 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: const: EmptyPatchCritic title: Kind type: string mode: default: finish_and_message 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) enum: - finish_and_message - all_actions title: Mode type: string required: - kind title: EmptyPatchCritic type: object PassCritic-Output: 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. properties: 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: const: PassCritic title: Kind type: string mode: default: finish_and_message 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) enum: - finish_and_message - all_actions title: Mode type: string required: - kind title: PassCritic type: object MCPApiKeyAuthCredential-Output: properties: header_name: anyOf: - type: string - type: 'null' title: Header Name strategy: const: api_key title: Strategy type: string value: anyOf: - type: string - type: 'null' title: Value required: - strategy title: MCPApiKeyAuthCredential type: object MCPBasicAuthCredential-Output: properties: password: anyOf: - type: string - type: 'null' title: Password strategy: const: basic title: Strategy type: string username: title: Username type: string required: - strategy - username title: MCPBasicAuthCredential type: object MCPBearerAuthCredential-Output: properties: strategy: const: bearer title: Strategy type: string value: anyOf: - type: string - type: 'null' title: Value required: - strategy title: MCPBearerAuthCredential type: object MCPHeaderAuthCredential-Output: properties: headers: additionalProperties: anyOf: - type: string - type: 'null' title: Headers type: object strategy: const: header title: Strategy type: string required: - strategy title: MCPHeaderAuthCredential type: object MCPNoneAuthCredential: properties: strategy: const: none title: Strategy type: string required: - strategy title: MCPNoneAuthCredential type: object MCPOAuthAuthCredential-Output: properties: authentication: anyOf: - $ref: '#/components/schemas/MCPOAuthAuthentication-Output' - type: 'null' state: anyOf: - $ref: '#/components/schemas/MCPOAuthState-Output' - type: 'null' strategy: const: oauth2 title: Strategy type: string required: - strategy title: MCPOAuthAuthCredential type: object HookType: description: Types of hooks that can be executed. enum: - command - prompt - agent title: HookType type: string InputMetadata: description: Metadata for task skill inputs. properties: description: description: Description of the input parameter title: Description type: string name: description: Name of the input parameter title: Name type: string required: - name - description title: InputMetadata type: object 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.) properties: assets: description: List of asset files in assets/ directory (relative paths) items: type: string title: Assets type: array references: description: List of reference files in references/ directory (relative paths) items: type: string title: References type: array scripts: description: List of script files in scripts/ directory (relative paths) items: type: string title: Scripts type: array skill_root: description: Root directory of the skill (absolute path) title: Skill Root type: string required: - skill_root title: SkillResources type: object KeywordTrigger: description: >- Trigger for keyword-based skills. These skills are activated when specific keywords appear in the user's query. properties: keywords: items: type: string title: Keywords type: array type: const: keyword default: keyword title: Type type: string required: - keywords title: KeywordTrigger type: object 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). properties: paths: items: type: string title: Paths type: array type: const: path default: path title: Type type: string required: - paths title: PathTrigger type: object TaskTrigger: description: >- Trigger for task-specific skills. These skills are activated for specific task types and can modify prompts. properties: triggers: items: type: string title: Triggers type: array type: const: task default: task title: Type type: string required: - triggers title: TaskTrigger type: object 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 properties: max_iterations: default: 3 description: Maximum number of iterations before giving up. minimum: 1 title: Max Iterations type: integer success_threshold: default: 0.6 description: Score threshold (0-1) to consider task successful. maximum: 1 minimum: 0 title: Success Threshold type: number title: IterativeRefinementConfig type: object MCPOAuthAuthentication-Output: additionalProperties: false properties: additional_client_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Additional Client Metadata client_auth_method: anyOf: - enum: - none - client_secret_post - client_secret_basic - private_key_jwt type: string - type: 'null' title: Client Auth Method client_id: anyOf: - type: string - type: 'null' title: Client Id client_metadata_url: anyOf: - type: string - type: 'null' title: Client Metadata Url client_name: anyOf: - type: string - type: 'null' title: Client Name client_secret: anyOf: - type: string - type: 'null' title: Client Secret scopes: anyOf: - type: string - items: type: string type: array - type: 'null' title: Scopes type: const: oauth title: Type type: string required: - type title: MCPOAuthAuthentication type: object MCPOAuthState-Output: properties: client_info: anyOf: - $ref: '#/components/schemas/MCPOAuthClientInfoState-Output' - type: 'null' token_expires_at: anyOf: - type: number - type: 'null' title: Token Expires At tokens: anyOf: - $ref: '#/components/schemas/MCPOAuthTokenState-Output' - type: 'null' title: MCPOAuthState type: object MCPOAuthClientInfoState-Output: additionalProperties: true properties: client_secret: anyOf: - type: string - type: 'null' title: Client Secret title: MCPOAuthClientInfoState type: object MCPOAuthTokenState-Output: additionalProperties: true properties: access_token: anyOf: - type: string - type: 'null' title: Access Token refresh_token: anyOf: - type: string - type: 'null' title: Refresh Token title: MCPOAuthTokenState type: object securitySchemes: APIKeyHeader: in: header name: X-Session-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.