> ## 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. # Get Conversation Event > Get a local event given an id ## OpenAPI ````yaml /openapi/agent-sdk.json get /api/conversations/{conversation_id}/events/{event_id} 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/{conversation_id}/events/{event_id}: get: tags: - Events summary: Get Conversation Event description: Get a local event given an id operationId: >- get_conversation_event_api_conversations__conversation_id__events__event_id__get parameters: - in: path name: event_id required: true schema: title: Event Id type: string - in: path name: conversation_id required: true schema: format: uuid title: Conversation Id type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Event' description: Successful Response '404': description: Item not found '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error security: - APIKeyHeader: [] components: schemas: Event: discriminator: mapping: openhands__agent_server__models__ServerErrorEvent-Output__1: '#/components/schemas/ServerErrorEvent' openhands__sdk__event__acp_tool_call__ACPToolCallEvent-Output__1: '#/components/schemas/ACPToolCallEvent' openhands__sdk__event__condenser__Condensation-Output__1: '#/components/schemas/Condensation' openhands__sdk__event__condenser__CondensationRequest-Output__1: '#/components/schemas/CondensationRequest' openhands__sdk__event__condenser__CondensationSummaryEvent-Output__1: '#/components/schemas/CondensationSummaryEvent' openhands__sdk__event__conversation_error__ConversationErrorEvent-Output__1: '#/components/schemas/ConversationErrorEvent' openhands__sdk__event__conversation_state__ConversationStateUpdateEvent-Output__1: '#/components/schemas/ConversationStateUpdateEvent' openhands__sdk__event__hook_execution__HookExecutionEvent-Output__1: '#/components/schemas/HookExecutionEvent' openhands__sdk__event__llm_completion_log__LLMCompletionLogEvent-Output__1: '#/components/schemas/LLMCompletionLogEvent' openhands__sdk__event__llm_convertible__action__ActionEvent-Output__1: '#/components/schemas/ActionEvent' openhands__sdk__event__llm_convertible__message__MessageEvent-Output__1: '#/components/schemas/MessageEvent' openhands__sdk__event__llm_convertible__observation__AgentErrorEvent-Output__1: '#/components/schemas/AgentErrorEvent' openhands__sdk__event__llm_convertible__observation__ObservationEvent-Output__1: '#/components/schemas/ObservationEvent' openhands__sdk__event__llm_convertible__observation__UserRejectObservation-Output__1: '#/components/schemas/UserRejectObservation' openhands__sdk__event__llm_convertible__system__SystemPromptEvent-Output__1: '#/components/schemas/SystemPromptEvent' openhands__sdk__event__streaming_delta__StreamingDeltaEvent-Output__1: '#/components/schemas/StreamingDeltaEvent' openhands__sdk__event__token__TokenEvent-Output__1: '#/components/schemas/TokenEvent' openhands__sdk__event__user_action__InterruptEvent-Output__1: '#/components/schemas/InterruptEvent' openhands__sdk__event__user_action__PauseEvent-Output__1: '#/components/schemas/PauseEvent' propertyName: kind oneOf: - $ref: '#/components/schemas/ServerErrorEvent' - $ref: '#/components/schemas/ACPToolCallEvent' - $ref: '#/components/schemas/Condensation' - $ref: '#/components/schemas/CondensationRequest' - $ref: '#/components/schemas/CondensationSummaryEvent' - $ref: '#/components/schemas/ConversationErrorEvent' - $ref: '#/components/schemas/ConversationStateUpdateEvent' - $ref: '#/components/schemas/HookExecutionEvent' - $ref: '#/components/schemas/LLMCompletionLogEvent' - $ref: '#/components/schemas/ActionEvent' - $ref: '#/components/schemas/MessageEvent' - $ref: '#/components/schemas/AgentErrorEvent' - $ref: '#/components/schemas/ObservationEvent' - $ref: '#/components/schemas/UserRejectObservation' - $ref: '#/components/schemas/SystemPromptEvent' - $ref: '#/components/schemas/StreamingDeltaEvent' - $ref: '#/components/schemas/TokenEvent' - $ref: '#/components/schemas/InterruptEvent' - $ref: '#/components/schemas/PauseEvent' HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object ServerErrorEvent: additionalProperties: false description: >- Event emitted by the agent server when a server-level error occurs. This event is used for errors that originate from the agent server itself, such as MCP connection failures, WebSocket errors, or other infrastructure issues. Unlike ConversationErrorEvent which is for conversation-level failures, this event indicates a problem with the server environment. properties: code: description: Code for the error - typically an error type title: Code type: string detail: description: Details about the error title: Detail type: string id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: ServerErrorEvent title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: description: The source of this event enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string required: - source - code - detail - kind title: ServerErrorEvent type: object ACPToolCallEvent: additionalProperties: false description: |- Event representing a tool call executed by an ACP server. Captures the tool name, inputs, outputs, and status from ACP ``ToolCallStart`` / ``ToolCallProgress`` notifications so they can be surfaced in the OpenHands event stream and visualizer. This is *not* an ``LLMConvertibleEvent`` — ACP tool calls do not participate in LLM message conversion. properties: content: anyOf: - items: {} type: array - type: 'null' title: Content id: description: Unique event id (ULID/UUID) title: Id type: string is_error: default: false title: Is Error type: boolean kind: const: ACPToolCallEvent title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id raw_input: anyOf: - {} - type: 'null' title: Raw Input raw_output: anyOf: - {} - type: 'null' title: Raw Output source: default: agent enum: - agent - user - environment - hook title: Source type: string status: anyOf: - type: string - type: 'null' title: Status timestamp: description: Event timestamp title: Timestamp type: string title: title: Title type: string tool_call_id: title: Tool Call Id type: string tool_kind: anyOf: - type: string - type: 'null' title: Tool Kind required: - tool_call_id - title - kind title: ACPToolCallEvent type: object Condensation: additionalProperties: false description: >- This action indicates a condensation of the conversation history is happening. properties: forgotten_event_ids: description: >- The IDs of the events that are being forgotten (removed from the `View` given to the LLM). items: type: string title: Forgotten Event Ids type: array uniqueItems: true id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: Condensation title: Kind type: string llm_response_id: description: >- Completion or Response ID of the LLM response that generated this event title: Llm Response Id type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: default: environment enum: - agent - user - environment - hook title: Source type: string summary: anyOf: - type: string - type: 'null' description: An optional summary of the events being forgotten. title: Summary summary_offset: anyOf: - minimum: 0 type: integer - type: 'null' description: >- An optional offset to the start of the resulting view (after forgotten events have been removed) indicating where the summary should be inserted. If not provided, the summary will not be inserted into the view. title: Summary Offset timestamp: description: Event timestamp title: Timestamp type: string required: - llm_response_id - kind title: Condensation type: object CondensationRequest: additionalProperties: false description: >- This action is used to request a condensation of the conversation history. Attributes: action (str): The action type, namely ActionType.CONDENSATION_REQUEST. properties: id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: CondensationRequest title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: default: environment enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string required: - kind title: CondensationRequest type: object CondensationSummaryEvent: additionalProperties: false description: This event represents a summary generated by a condenser. properties: id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: CondensationSummaryEvent title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: default: environment enum: - agent - user - environment - hook title: Source type: string summary: title: Summary type: string timestamp: description: Event timestamp title: Timestamp type: string required: - summary - kind title: CondensationSummaryEvent type: object ConversationErrorEvent: additionalProperties: false description: >- Conversation-level failure that is NOT sent back to the LLM. This event is emitted by the conversation runtime when an unexpected exception bubbles up and prevents the run loop from continuing. It is intended for client applications (e.g., UIs) to present a top-level error state, and for orchestration to react. It is not an observation and it is not LLM-convertible. Differences from AgentErrorEvent: - Not tied to any tool_name/tool_call_id (AgentErrorEvent is a tool observation). - Typically source='environment' and the run loop moves to an ERROR state, while AgentErrorEvent has source='agent' and the conversation can continue. properties: classification: anyOf: - $ref: '#/components/schemas/ErrorClassification' - type: 'null' description: Safe structured error semantics for API consumers. code: description: Code for the error - typically a type title: Code type: string detail: description: Details about the error title: Detail type: string id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: ConversationErrorEvent title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: description: The source of this event enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string required: - source - code - detail - kind title: ConversationErrorEvent type: object ConversationStateUpdateEvent: additionalProperties: false description: >- Event that contains conversation state updates. This event is sent via websocket whenever the conversation state changes, allowing remote clients to stay in sync without making REST API calls. All fields are serialized versions of the corresponding ConversationState fields to ensure compatibility with websocket transmission. properties: id: description: Unique event id (ULID/UUID) title: Id type: string key: description: Unique key for this state update event title: Key type: string kind: const: ConversationStateUpdateEvent title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: default: environment enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string value: description: Serialized conversation state updates title: Value required: - kind title: ConversationStateUpdateEvent type: object HookExecutionEvent: additionalProperties: false description: |- Event emitted when a hook is executed. This event provides observability into hook execution, including: - Which hook type was triggered - The command that was run - The result (success/blocked/error) - Any output from the hook This allows clients to track hook execution via the event stream. properties: action_id: anyOf: - type: string - type: 'null' description: >- ID of the action this hook is associated with (PreToolUse/PostToolUse) title: Action Id additional_context: anyOf: - type: string - type: 'null' description: Additional context injected by hook (e.g., for UserPromptSubmit) title: Additional Context blocked: default: false description: Whether the hook blocked the operation (exit code 2 or deny) title: Blocked type: boolean error: anyOf: - type: string - type: 'null' description: Error message if hook execution failed title: Error exit_code: description: Exit code from the hook command title: Exit Code type: integer hook_command: description: The hook command that was executed title: Hook Command type: string hook_event_type: description: The type of hook event that triggered this execution enum: - PreToolUse - PostToolUse - UserPromptSubmit - SessionStart - SessionEnd - Stop title: Hook Event Type type: string hook_input: anyOf: - additionalProperties: true type: object - type: 'null' description: The input data that was passed to the hook title: Hook Input id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: HookExecutionEvent title: Kind type: string message_id: anyOf: - type: string - type: 'null' description: ID of the message this hook is associated with (UserPromptSubmit) title: Message Id parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id reason: anyOf: - type: string - type: 'null' description: Reason provided by hook (for blocking) title: Reason source: default: hook description: Source is always 'hook' for hook execution events enum: - agent - user - environment - hook title: Source type: string stderr: default: '' description: Standard error from the hook title: Stderr type: string stdout: default: '' description: Standard output from the hook title: Stdout type: string success: description: Whether the hook executed successfully title: Success type: boolean timestamp: description: Event timestamp title: Timestamp type: string tool_name: anyOf: - type: string - type: 'null' description: Tool name for PreToolUse/PostToolUse hooks title: Tool Name required: - hook_event_type - hook_command - success - exit_code - kind title: HookExecutionEvent type: object LLMCompletionLogEvent: additionalProperties: false description: >- Event containing LLM completion log data. When an LLM is configured with log_completions=True in a remote conversation, this event streams the completion log data back to the client through WebSocket instead of writing it to a file inside the Docker container. properties: filename: description: The intended filename for this log (relative to log directory) title: Filename type: string id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: LLMCompletionLogEvent title: Kind type: string log_data: description: The JSON-encoded log data to be written to the file title: Log Data type: string model_name: default: unknown description: The model name for context title: Model Name type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: default: environment enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string usage_id: default: default description: The LLM usage_id that produced this log title: Usage Id type: string required: - filename - log_data - kind title: LLMCompletionLogEvent type: object ActionEvent: additionalProperties: false properties: action: anyOf: - $ref: '#/components/schemas/Action' - type: 'null' description: Single tool call returned by LLM (None when non-executable) critic_result: anyOf: - $ref: '#/components/schemas/CriticResult' - type: 'null' description: Optional critic evaluation of this action and preceding history. id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: ActionEvent title: Kind type: string llm_response_id: description: >- Completion or Response ID of the LLM response that generated this eventE.g., Can be used to group related actions from same LLM response. This helps in tracking and managing results of parallel function calling from the same LLM response. title: Llm Response Id type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id reasoning_content: anyOf: - type: string - type: 'null' description: Intermediate reasoning/thinking content from reasoning models title: Reasoning Content responses_reasoning_item: anyOf: - $ref: '#/components/schemas/ReasoningItemModel' - type: 'null' description: OpenAI Responses reasoning item from model output security_risk: $ref: '#/components/schemas/SecurityRisk' default: UNKNOWN description: The LLM's assessment of the safety risk of this action. source: default: agent enum: - agent - user - environment - hook title: Source type: string summary: anyOf: - type: string - type: 'null' description: >- A concise summary (approximately 10 words) of what this action does, provided by the LLM for explainability and debugging. Examples of good summaries: 'editing configuration file for deployment settings' | 'searching codebase for authentication function definitions' | 'installing required dependencies from package manifest' | 'running tests to verify bug fix' | 'viewing directory structure to locate source files' title: Summary thinking_blocks: description: Anthropic thinking blocks from the LLM response items: anyOf: - $ref: '#/components/schemas/ThinkingBlock' - $ref: '#/components/schemas/RedactedThinkingBlock' title: Thinking Blocks type: array thought: description: The thought process of the agent before taking this action items: $ref: '#/components/schemas/TextContent' title: Thought type: array timestamp: description: Event timestamp title: Timestamp type: string tool_call: $ref: '#/components/schemas/MessageToolCall' description: >- The tool call received from the LLM response. We keep a copy of it so it is easier to construct it into LLM messageThis could be different from `action`: e.g., `tool_call` may contain `security_risk` field predicted by LLM when LLM risk analyzer is enabled, while `action` does not. tool_call_id: description: The unique id returned by LLM API for this tool call title: Tool Call Id type: string tool_name: description: The name of the tool being called title: Tool Name type: string required: - thought - tool_name - tool_call_id - tool_call - llm_response_id - kind title: ActionEvent type: object MessageEvent: additionalProperties: false description: >- Message from either agent or user. This is originally the "MessageAction", but it suppose not to be tool call. properties: activated_skills: description: List of activated skill name items: type: string title: Activated Skills type: array critic_result: anyOf: - $ref: '#/components/schemas/CriticResult' - type: 'null' description: Optional critic evaluation of this message and preceding history. extended_content: description: List of content added by agent context items: $ref: '#/components/schemas/TextContent' title: Extended Content type: array id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: MessageEvent title: Kind type: string llm_message: $ref: '#/components/schemas/Message' description: The exact LLM message for this message event llm_response_id: anyOf: - type: string - type: 'null' description: >- Completion or Response ID of the LLM response that generated this eventIf the source != 'agent', this field is None title: Llm Response Id parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id sender: anyOf: - type: string - type: 'null' description: >- Optional identifier of the sender. Can be used to track message origin in multi-agent scenarios. title: Sender source: enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string required: - source - llm_message - kind title: MessageEvent type: object AgentErrorEvent: additionalProperties: false description: >- Error triggered by the agent. Note: This event should not contain model "thought" or "reasoning_content". It represents an error produced by the agent/scaffold, not model output. properties: classification: anyOf: - $ref: '#/components/schemas/ErrorClassification' - type: 'null' description: Safe structured error semantics for API consumers. error: description: The error message from the scaffold title: Error type: string id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: AgentErrorEvent title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: default: agent enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string tool_call_id: description: The tool call id that this observation is responding to title: Tool Call Id type: string tool_name: description: The tool name that this observation is responding to title: Tool Name type: string required: - tool_name - tool_call_id - error - kind title: AgentErrorEvent type: object ObservationEvent: additionalProperties: false properties: action_id: description: The action id that this observation is responding to title: Action Id type: string extended_content: description: >- Content added by agent context (e.g. path-scoped rules triggered by the touched file), appended after the tool result in to_llm_message. items: $ref: '#/components/schemas/TextContent' title: Extended Content type: array id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: ObservationEvent title: Kind type: string observation: $ref: '#/components/schemas/Observation' description: The observation (tool call) sent to LLM parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: default: environment enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string tool_call_id: description: The tool call id that this observation is responding to title: Tool Call Id type: string tool_name: description: The tool name that this observation is responding to title: Tool Name type: string required: - tool_name - tool_call_id - observation - action_id - kind title: ObservationEvent type: object UserRejectObservation: additionalProperties: false description: >- Observation when an action is rejected by user or hook. This event is emitted when: - User rejects an action during confirmation mode (rejection_source="user") - A PreToolUse hook blocks an action (rejection_source="hook") properties: action_id: description: The action id that this observation is responding to title: Action Id type: string id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: UserRejectObservation title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id rejection_reason: default: User rejected the action description: Reason for rejecting the action title: Rejection Reason type: string rejection_source: default: user description: >- Source of the rejection: 'user' for confirmation mode rejections, 'hook' for PreToolUse hook blocks enum: - user - hook title: Rejection Source type: string source: default: environment enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string tool_call_id: description: The tool call id that this observation is responding to title: Tool Call Id type: string tool_name: description: The tool name that this observation is responding to title: Tool Name type: string required: - tool_name - tool_call_id - action_id - kind title: UserRejectObservation type: object SystemPromptEvent: additionalProperties: false description: >- System prompt added by the agent. The system prompt can optionally include dynamic context that varies between conversations. When ``dynamic_context`` is provided, it is included as a second content block in the same system message. Cache markers are NOT applied here - they are applied by ``LLM._apply_prompt_caching()`` when caching is enabled, ensuring provider-specific cache control is only added when appropriate. Attributes: system_prompt: The static system prompt text (cacheable across conversations) tools: List of available tools dynamic_context: Optional per-conversation context (hosts, repo info, etc.) Sent as a second TextContent block inside the system message. properties: dynamic_context: anyOf: - $ref: '#/components/schemas/TextContent' - type: 'null' description: >- Optional dynamic per-conversation context (runtime info, repo context, secrets). When provided, this is included as a second content block in the system message (not cached). id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: SystemPromptEvent title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: default: agent enum: - agent - user - environment - hook title: Source type: string system_prompt: $ref: '#/components/schemas/TextContent' description: The system prompt text timestamp: description: Event timestamp title: Timestamp type: string tools: description: List of tools as ToolDefinition objects items: $ref: '#/components/schemas/ToolDefinition' title: Tools type: array required: - system_prompt - tools - kind title: SystemPromptEvent type: object StreamingDeltaEvent: additionalProperties: false description: |- Transient LLM token delta for real-time WebSocket delivery. Not persisted to the conversation event log: these events are published directly to PubSub, bypassing the callback chain that writes to ConversationState.events. Clients reconnecting mid-stream will receive the final MessageEvent from history but none of the deltas that produced it — deltas are a UX affordance, not part of the durable conversation record. properties: content: anyOf: - type: string - type: 'null' title: Content id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: StreamingDeltaEvent title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id reasoning_content: anyOf: - type: string - type: 'null' title: Reasoning Content source: default: agent enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string required: - kind title: StreamingDeltaEvent type: object TokenEvent: additionalProperties: false description: Event from VLLM representing token IDs used in LLM interaction. properties: id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: TokenEvent title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id prompt_token_ids: description: The exact prompt token IDs for this message event items: type: integer title: Prompt Token Ids type: array response_token_ids: description: The exact response token IDs for this message event items: type: integer title: Response Token Ids type: array source: enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string required: - source - prompt_token_ids - response_token_ids - kind title: TokenEvent type: object InterruptEvent: additionalProperties: false description: |- Event indicating the agent was interrupted mid-operation. Unlike :class:`PauseEvent` which takes effect between agent steps, an interrupt cancels the in-flight LLM call immediately. The conversation state is set to PAUSED so it can be resumed later. properties: id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: InterruptEvent title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: default: user enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string required: - kind title: InterruptEvent type: object PauseEvent: additionalProperties: false description: Event indicating that the agent execution was paused by user request. properties: id: description: Unique event id (ULID/UUID) title: Id type: string kind: const: PauseEvent title: Kind type: string parent_id: anyOf: - type: string - type: 'null' description: >- Parent event id in the conversation tree. None for the root, or for legacy events predating the tree (see EventLog's effective-parent rule). Events sharing a parent_id are sibling branches. title: Parent Id source: default: user enum: - agent - user - environment - hook title: Source type: string timestamp: description: Event timestamp title: Timestamp type: string required: - kind title: PauseEvent type: object 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 ErrorClassification: additionalProperties: false description: |- The only failure metadata that crosses the event/API boundary. It is intentionally small. ``detail`` is inspected locally only to map broad third-party errors to this closed vocabulary; it is never copied here or sent to telemetry. properties: error_id: anyOf: - type: string - type: 'null' title: Error Id kind: $ref: '#/components/schemas/FailureKind' retryable: title: Retryable type: boolean user_action: default: none enum: - none - retry - settings title: User Action type: string required: - kind - retryable title: ErrorClassification type: object Action: discriminator: mapping: openhands__sdk__mcp__definition__MCPToolAction-Output__1: '#/components/schemas/MCPToolAction' openhands__sdk__tool__builtins__classify_and_switch_llm__ClassifyAndSwitchLLMAction-Output__1: '#/components/schemas/ClassifyAndSwitchLLMAction' openhands__sdk__tool__builtins__finish__FinishAction-Output__1: '#/components/schemas/FinishAction' openhands__sdk__tool__builtins__invoke_skill__InvokeSkillAction-Output__1: '#/components/schemas/InvokeSkillAction' openhands__sdk__tool__builtins__switch_llm__SwitchLLMAction-Output__1: '#/components/schemas/SwitchLLMAction' openhands__sdk__tool__builtins__think__ThinkAction-Output__1: '#/components/schemas/ThinkAction' openhands__sdk__tool__builtins__vision_inspect__VisionInspectAction-Output__1: '#/components/schemas/VisionInspectAction' openhands__tools__ask_oracle__definition__AskOracleAction-Output__1: '#/components/schemas/AskOracleAction' openhands__tools__browser_use__definition__BrowserAction-Output__1: '#/components/schemas/BrowserAction' openhands__tools__browser_use__definition__BrowserClickAction-Output__1: '#/components/schemas/BrowserClickAction' openhands__tools__browser_use__definition__BrowserCloseTabAction-Output__1: '#/components/schemas/BrowserCloseTabAction' openhands__tools__browser_use__definition__BrowserGetContentAction-Output__1: '#/components/schemas/BrowserGetContentAction' openhands__tools__browser_use__definition__BrowserGetStateAction-Output__1: '#/components/schemas/BrowserGetStateAction' openhands__tools__browser_use__definition__BrowserGetStorageAction-Output__1: '#/components/schemas/BrowserGetStorageAction' openhands__tools__browser_use__definition__BrowserGoBackAction-Output__1: '#/components/schemas/BrowserGoBackAction' openhands__tools__browser_use__definition__BrowserListTabsAction-Output__1: '#/components/schemas/BrowserListTabsAction' openhands__tools__browser_use__definition__BrowserNavigateAction-Output__1: '#/components/schemas/BrowserNavigateAction' openhands__tools__browser_use__definition__BrowserScrollAction-Output__1: '#/components/schemas/BrowserScrollAction' openhands__tools__browser_use__definition__BrowserSetStorageAction-Output__1: '#/components/schemas/BrowserSetStorageAction' openhands__tools__browser_use__definition__BrowserStartRecordingAction-Output__1: '#/components/schemas/BrowserStartRecordingAction' openhands__tools__browser_use__definition__BrowserStopRecordingAction-Output__1: '#/components/schemas/BrowserStopRecordingAction' openhands__tools__browser_use__definition__BrowserSwitchTabAction-Output__1: '#/components/schemas/BrowserSwitchTabAction' openhands__tools__browser_use__definition__BrowserTypeAction-Output__1: '#/components/schemas/BrowserTypeAction' openhands__tools__delegate__definition__DelegateAction-Output__1: '#/components/schemas/DelegateAction' openhands__tools__file_editor__definition__FileEditorAction-Output__1: '#/components/schemas/FileEditorAction' openhands__tools__gemini__edit__definition__EditAction-Output__1: '#/components/schemas/EditAction' openhands__tools__gemini__list_directory__definition__ListDirectoryAction-Output__1: '#/components/schemas/ListDirectoryAction' openhands__tools__gemini__read_file__definition__ReadFileAction-Output__1: '#/components/schemas/ReadFileAction' openhands__tools__gemini__write_file__definition__WriteFileAction-Output__1: '#/components/schemas/WriteFileAction' openhands__tools__glob__definition__GlobAction-Output__1: '#/components/schemas/GlobAction' openhands__tools__grep__definition__GrepAction-Output__1: '#/components/schemas/GrepAction' openhands__tools__planning_file_editor__definition__PlanningFileEditorAction-Output__1: '#/components/schemas/PlanningFileEditorAction' openhands__tools__task__definition__TaskAction-Output__1: '#/components/schemas/TaskAction' openhands__tools__task_tracker__definition__TaskTrackerAction-Output__1: '#/components/schemas/TaskTrackerAction' openhands__tools__terminal__definition__TerminalAction-Output__1: '#/components/schemas/TerminalAction' openhands__tools__workflow__definition__WorkflowAction-Output__1: '#/components/schemas/WorkflowAction' propertyName: kind oneOf: - $ref: '#/components/schemas/MCPToolAction' - $ref: '#/components/schemas/ClassifyAndSwitchLLMAction' - $ref: '#/components/schemas/FinishAction' - $ref: '#/components/schemas/InvokeSkillAction' - $ref: '#/components/schemas/SwitchLLMAction' - $ref: '#/components/schemas/ThinkAction' - $ref: '#/components/schemas/VisionInspectAction' - $ref: '#/components/schemas/AskOracleAction' - $ref: '#/components/schemas/BrowserAction' - $ref: '#/components/schemas/BrowserClickAction' - $ref: '#/components/schemas/BrowserCloseTabAction' - $ref: '#/components/schemas/BrowserGetContentAction' - $ref: '#/components/schemas/BrowserGetStateAction' - $ref: '#/components/schemas/BrowserGetStorageAction' - $ref: '#/components/schemas/BrowserGoBackAction' - $ref: '#/components/schemas/BrowserListTabsAction' - $ref: '#/components/schemas/BrowserNavigateAction' - $ref: '#/components/schemas/BrowserScrollAction' - $ref: '#/components/schemas/BrowserSetStorageAction' - $ref: '#/components/schemas/BrowserStartRecordingAction' - $ref: '#/components/schemas/BrowserStopRecordingAction' - $ref: '#/components/schemas/BrowserSwitchTabAction' - $ref: '#/components/schemas/BrowserTypeAction' - $ref: '#/components/schemas/DelegateAction' - $ref: '#/components/schemas/FileEditorAction' - $ref: '#/components/schemas/EditAction' - $ref: '#/components/schemas/ListDirectoryAction' - $ref: '#/components/schemas/ReadFileAction' - $ref: '#/components/schemas/WriteFileAction' - $ref: '#/components/schemas/GlobAction' - $ref: '#/components/schemas/GrepAction' - $ref: '#/components/schemas/PlanningFileEditorAction' - $ref: '#/components/schemas/TaskAction' - $ref: '#/components/schemas/TaskTrackerAction' - $ref: '#/components/schemas/TerminalAction' - $ref: '#/components/schemas/WorkflowAction' CriticResult: description: A critic result is a score and a message. properties: message: anyOf: - type: string - type: 'null' description: An optional message explaining the score. title: Message metadata: anyOf: - additionalProperties: true type: object - type: 'null' description: >- Optional metadata about the critic evaluation. Can include event_ids and categorized_features for visualization. title: Metadata score: description: A predicted probability of success between 0 and 1. maximum: 1 minimum: 0 title: Score type: number required: - score - message title: CriticResult type: object ReasoningItemModel: description: |- OpenAI Responses reasoning item (non-stream, subset we consume). Do not log or render encrypted_content. properties: content: anyOf: - items: type: string type: array - type: 'null' title: Content encrypted_content: anyOf: - type: string - type: 'null' title: Encrypted Content id: anyOf: - type: string - type: 'null' title: Id status: anyOf: - type: string - type: 'null' title: Status summary: items: type: string title: Summary type: array title: ReasoningItemModel 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 ThinkingBlock: description: |- Anthropic thinking block for extended thinking feature. This represents the raw thinking blocks returned by Anthropic models when extended thinking is enabled. These blocks must be preserved and passed back to the API for tool use scenarios. properties: signature: anyOf: - type: string - type: 'null' description: Cryptographic signature for the thinking block title: Signature thinking: description: The thinking content title: Thinking type: string type: const: thinking default: thinking title: Type type: string required: - thinking title: ThinkingBlock type: object RedactedThinkingBlock: description: >- Redacted thinking block for previous responses without extended thinking. This is used as a placeholder for assistant messages that were generated before extended thinking was enabled. properties: data: description: The redacted thinking content title: Data type: string type: const: redacted_thinking default: redacted_thinking title: Type type: string required: - data title: RedactedThinkingBlock type: object TextContent: additionalProperties: false properties: cache_prompt: default: false title: Cache Prompt type: boolean text: title: Text type: string type: const: text default: text title: Type type: string required: - text title: TextContent type: object MessageToolCall: description: |- Transport-agnostic tool call representation. One canonical id is used for linking across actions/observations and for Responses function_call_output call_id. properties: arguments: description: JSON string of arguments title: Arguments type: string id: description: Canonical tool call id title: Id type: string name: description: Tool/function name title: Name type: string origin: description: Originating API family enum: - completion - responses title: Origin type: string responses_item_id: anyOf: - type: string - type: 'null' description: Original Responses function_call.id, echoed verbatim on replay title: Responses Item Id required: - id - name - arguments - origin title: MessageToolCall type: object Message: properties: content: items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array name: anyOf: - type: string - type: 'null' title: Name reasoning_content: anyOf: - type: string - type: 'null' description: Intermediate reasoning/thinking content from reasoning models title: Reasoning Content responses_reasoning_item: anyOf: - $ref: '#/components/schemas/ReasoningItemModel' - type: 'null' description: OpenAI Responses reasoning item from model output role: enum: - user - system - assistant - tool title: Role type: string thinking_blocks: description: Raw Anthropic thinking blocks for extended thinking feature items: anyOf: - $ref: '#/components/schemas/ThinkingBlock' - $ref: '#/components/schemas/RedactedThinkingBlock' title: Thinking Blocks type: array tool_call_id: anyOf: - type: string - type: 'null' title: Tool Call Id tool_calls: anyOf: - items: $ref: '#/components/schemas/MessageToolCall' type: array - type: 'null' title: Tool Calls required: - role title: Message type: object Observation: discriminator: mapping: openhands__sdk__mcp__definition__MCPToolObservation-Output__1: '#/components/schemas/MCPToolObservation' openhands__sdk__tool__builtins__classify_and_switch_llm__ClassifyAndSwitchLLMObservation-Output__1: '#/components/schemas/ClassifyAndSwitchLLMObservation' openhands__sdk__tool__builtins__finish__FinishObservation-Output__1: '#/components/schemas/FinishObservation' openhands__sdk__tool__builtins__invoke_skill__InvokeSkillObservation-Output__1: '#/components/schemas/InvokeSkillObservation' openhands__sdk__tool__builtins__switch_llm__SwitchLLMObservation-Output__1: '#/components/schemas/SwitchLLMObservation' openhands__sdk__tool__builtins__think__ThinkObservation-Output__1: '#/components/schemas/ThinkObservation' openhands__sdk__tool__builtins__vision_inspect__VisionInspectObservation-Output__1: '#/components/schemas/VisionInspectObservation' openhands__sdk__tool__client_tool__ClientToolObservation-Output__1: '#/components/schemas/ClientToolObservation' openhands__tools__ask_oracle__definition__AskOracleObservation-Output__1: '#/components/schemas/AskOracleObservation' openhands__tools__browser_use__definition__BrowserObservation-Output__1: '#/components/schemas/BrowserObservation' openhands__tools__delegate__definition__DelegateObservation-Output__1: '#/components/schemas/DelegateObservation' openhands__tools__file_editor__definition__FileEditorObservation-Output__1: '#/components/schemas/FileEditorObservation' openhands__tools__gemini__edit__definition__EditObservation-Output__1: '#/components/schemas/EditObservation' openhands__tools__gemini__list_directory__definition__ListDirectoryObservation-Output__1: '#/components/schemas/ListDirectoryObservation' openhands__tools__gemini__read_file__definition__ReadFileObservation-Output__1: '#/components/schemas/ReadFileObservation' openhands__tools__gemini__write_file__definition__WriteFileObservation-Output__1: '#/components/schemas/WriteFileObservation' openhands__tools__glob__definition__GlobObservation-Output__1: '#/components/schemas/GlobObservation' openhands__tools__grep__definition__GrepObservation-Output__1: '#/components/schemas/GrepObservation' openhands__tools__planning_file_editor__definition__PlanningFileEditorObservation-Output__1: '#/components/schemas/PlanningFileEditorObservation' openhands__tools__task__definition__TaskObservation-Output__1: '#/components/schemas/TaskObservation' openhands__tools__task_tracker__definition__TaskTrackerObservation-Output__1: '#/components/schemas/TaskTrackerObservation' openhands__tools__terminal__definition__TerminalObservation-Output__1: '#/components/schemas/TerminalObservation' openhands__tools__workflow__definition__WorkflowObservation-Output__1: '#/components/schemas/WorkflowObservation' propertyName: kind oneOf: - $ref: '#/components/schemas/MCPToolObservation' - $ref: '#/components/schemas/ClassifyAndSwitchLLMObservation' - $ref: '#/components/schemas/FinishObservation' - $ref: '#/components/schemas/InvokeSkillObservation' - $ref: '#/components/schemas/SwitchLLMObservation' - $ref: '#/components/schemas/ThinkObservation' - $ref: '#/components/schemas/VisionInspectObservation' - $ref: '#/components/schemas/ClientToolObservation' - $ref: '#/components/schemas/AskOracleObservation' - $ref: '#/components/schemas/BrowserObservation' - $ref: '#/components/schemas/DelegateObservation' - $ref: '#/components/schemas/FileEditorObservation' - $ref: '#/components/schemas/EditObservation' - $ref: '#/components/schemas/ListDirectoryObservation' - $ref: '#/components/schemas/ReadFileObservation' - $ref: '#/components/schemas/WriteFileObservation' - $ref: '#/components/schemas/GlobObservation' - $ref: '#/components/schemas/GrepObservation' - $ref: '#/components/schemas/PlanningFileEditorObservation' - $ref: '#/components/schemas/TaskObservation' - $ref: '#/components/schemas/TaskTrackerObservation' - $ref: '#/components/schemas/TerminalObservation' - $ref: '#/components/schemas/WorkflowObservation' ToolDefinition: discriminator: mapping: openhands__sdk__mcp__tool__MCPToolDefinition-Output__1: '#/components/schemas/MCPToolDefinition' openhands__sdk__tool__builtins__classify_and_switch_llm__ClassifyAndSwitchLLMTool-Output__1: '#/components/schemas/ClassifyAndSwitchLLMTool' openhands__sdk__tool__builtins__finish__FinishTool-Output__1: '#/components/schemas/FinishTool' openhands__sdk__tool__builtins__invoke_skill__InvokeSkillTool-Output__1: '#/components/schemas/InvokeSkillTool' openhands__sdk__tool__builtins__switch_llm__SwitchLLMTool-Output__1: '#/components/schemas/SwitchLLMTool' openhands__sdk__tool__builtins__think__ThinkTool-Output__1: '#/components/schemas/ThinkTool' openhands__sdk__tool__builtins__vision_inspect__VisionInspectTool-Output__1: '#/components/schemas/VisionInspectTool' openhands__sdk__tool__client_tool__ClientTool-Output__1: '#/components/schemas/ClientTool' openhands__tools__ask_oracle__definition__AskOracleTool-Output__1: '#/components/schemas/AskOracleTool' openhands__tools__browser_use__definition__BrowserClickTool-Output__1: '#/components/schemas/BrowserClickTool' openhands__tools__browser_use__definition__BrowserCloseTabTool-Output__1: '#/components/schemas/BrowserCloseTabTool' openhands__tools__browser_use__definition__BrowserGetContentTool-Output__1: '#/components/schemas/BrowserGetContentTool' openhands__tools__browser_use__definition__BrowserGetStateTool-Output__1: '#/components/schemas/BrowserGetStateTool' openhands__tools__browser_use__definition__BrowserGetStorageTool-Output__1: '#/components/schemas/BrowserGetStorageTool' openhands__tools__browser_use__definition__BrowserGoBackTool-Output__1: '#/components/schemas/BrowserGoBackTool' openhands__tools__browser_use__definition__BrowserListTabsTool-Output__1: '#/components/schemas/BrowserListTabsTool' openhands__tools__browser_use__definition__BrowserNavigateTool-Output__1: '#/components/schemas/BrowserNavigateTool' openhands__tools__browser_use__definition__BrowserScrollTool-Output__1: '#/components/schemas/BrowserScrollTool' openhands__tools__browser_use__definition__BrowserSetStorageTool-Output__1: '#/components/schemas/BrowserSetStorageTool' openhands__tools__browser_use__definition__BrowserStartRecordingTool-Output__1: '#/components/schemas/BrowserStartRecordingTool' openhands__tools__browser_use__definition__BrowserStopRecordingTool-Output__1: '#/components/schemas/BrowserStopRecordingTool' openhands__tools__browser_use__definition__BrowserSwitchTabTool-Output__1: '#/components/schemas/BrowserSwitchTabTool' openhands__tools__browser_use__definition__BrowserToolSet-Output__1: '#/components/schemas/BrowserToolSet' openhands__tools__browser_use__definition__BrowserTypeTool-Output__1: '#/components/schemas/BrowserTypeTool' openhands__tools__file_editor__definition__FileEditorTool-Output__1: '#/components/schemas/FileEditorTool' openhands__tools__gemini__edit__definition__EditTool-Output__1: '#/components/schemas/EditTool' openhands__tools__gemini__list_directory__definition__ListDirectoryTool-Output__1: '#/components/schemas/ListDirectoryTool' openhands__tools__gemini__read_file__definition__ReadFileTool-Output__1: '#/components/schemas/ReadFileTool' openhands__tools__gemini__write_file__definition__WriteFileTool-Output__1: '#/components/schemas/WriteFileTool' openhands__tools__glob__definition__GlobTool-Output__1: '#/components/schemas/GlobTool' openhands__tools__grep__definition__GrepTool-Output__1: '#/components/schemas/GrepTool' openhands__tools__planning_file_editor__definition__PlanningFileEditorTool-Output__1: '#/components/schemas/PlanningFileEditorTool' openhands__tools__task__definition__TaskTool-Output__1: '#/components/schemas/TaskTool' openhands__tools__task__definition__TaskToolSet-Output__1: '#/components/schemas/TaskToolSet' openhands__tools__task_tracker__definition__TaskTrackerTool-Output__1: '#/components/schemas/TaskTrackerTool' openhands__tools__terminal__definition__TerminalTool-Output__1: '#/components/schemas/TerminalTool' openhands__tools__workflow__definition__WorkflowTool-Output__1: '#/components/schemas/WorkflowTool' openhands__tools__workflow__definition__WorkflowToolSet-Output__1: '#/components/schemas/WorkflowToolSet' propertyName: kind oneOf: - $ref: '#/components/schemas/MCPToolDefinition' - $ref: '#/components/schemas/ClassifyAndSwitchLLMTool' - $ref: '#/components/schemas/FinishTool' - $ref: '#/components/schemas/InvokeSkillTool' - $ref: '#/components/schemas/SwitchLLMTool' - $ref: '#/components/schemas/ThinkTool' - $ref: '#/components/schemas/VisionInspectTool' - $ref: '#/components/schemas/ClientTool' - $ref: '#/components/schemas/AskOracleTool' - $ref: '#/components/schemas/BrowserClickTool' - $ref: '#/components/schemas/BrowserCloseTabTool' - $ref: '#/components/schemas/BrowserGetContentTool' - $ref: '#/components/schemas/BrowserGetStateTool' - $ref: '#/components/schemas/BrowserGetStorageTool' - $ref: '#/components/schemas/BrowserGoBackTool' - $ref: '#/components/schemas/BrowserListTabsTool' - $ref: '#/components/schemas/BrowserNavigateTool' - $ref: '#/components/schemas/BrowserScrollTool' - $ref: '#/components/schemas/BrowserSetStorageTool' - $ref: '#/components/schemas/BrowserStartRecordingTool' - $ref: '#/components/schemas/BrowserStopRecordingTool' - $ref: '#/components/schemas/BrowserSwitchTabTool' - $ref: '#/components/schemas/BrowserToolSet' - $ref: '#/components/schemas/BrowserTypeTool' - $ref: '#/components/schemas/FileEditorTool' - $ref: '#/components/schemas/EditTool' - $ref: '#/components/schemas/ListDirectoryTool' - $ref: '#/components/schemas/ReadFileTool' - $ref: '#/components/schemas/WriteFileTool' - $ref: '#/components/schemas/GlobTool' - $ref: '#/components/schemas/GrepTool' - $ref: '#/components/schemas/PlanningFileEditorTool' - $ref: '#/components/schemas/TaskTool' - $ref: '#/components/schemas/TaskToolSet' - $ref: '#/components/schemas/TaskTrackerTool' - $ref: '#/components/schemas/TerminalTool' - $ref: '#/components/schemas/WorkflowTool' - $ref: '#/components/schemas/WorkflowToolSet' FailureKind: enum: - auth - quota - rate_limit - config - transient - agent_action - internal - unknown title: FailureKind type: string MCPToolAction: additionalProperties: false description: |- Schema for MCP input action. It is just a thin wrapper around raw JSON and does not do any validation. Validation will be performed by MCPTool.__call__ by constructing dynamically created Pydantic model from the MCP tool input schema. properties: data: additionalProperties: true description: Dynamic data fields from the tool call title: Data type: object kind: const: MCPToolAction title: Kind type: string required: - kind title: MCPToolAction type: object ClassifyAndSwitchLLMAction: additionalProperties: false description: Trigger classification of the current task and switch the LLM profile. properties: kind: const: ClassifyAndSwitchLLMAction title: Kind type: string required: - kind title: ClassifyAndSwitchLLMAction type: object FinishAction: additionalProperties: false properties: kind: const: FinishAction title: Kind type: string message: description: Final message to send to the user. title: Message type: string required: - message - kind title: FinishAction type: object InvokeSkillAction: additionalProperties: false properties: kind: const: InvokeSkillAction title: Kind type: string name: description: Name of the loaded skill to invoke. title: Name type: string required: - name - kind title: InvokeSkillAction type: object SwitchLLMAction: additionalProperties: false description: Action for switching this conversation to a saved LLM profile. properties: kind: const: SwitchLLMAction title: Kind type: string profile_name: description: Name of the saved LLM profile to use for future agent steps. title: Profile Name type: string reason: description: Brief reason why this profile is a better fit for the next step. title: Reason type: string required: - profile_name - reason - kind title: SwitchLLMAction type: object ThinkAction: additionalProperties: false description: Action for logging a thought without making any changes. properties: kind: const: ThinkAction title: Kind type: string thought: description: The thought to log. title: Thought type: string required: - thought - kind title: ThinkAction type: object VisionInspectAction: additionalProperties: false description: Action for asking a vision model about an attached image. properties: image_index: description: >- Zero-based index of the image to inspect from the latest user message. minimum: 0 title: Image Index type: integer kind: const: VisionInspectAction title: Kind type: string profile_name: anyOf: - type: string - type: 'null' description: >- Optional saved vision-capable LLM profile name. If omitted, the first available vision profile listed in the tool description is used. title: Profile Name question: description: Question to ask the vision model about the selected image. minLength: 1 title: Question type: string required: - image_index - question - kind title: VisionInspectAction type: object AskOracleAction: additionalProperties: false description: Action for asking the Oracle for advice. properties: context: anyOf: - type: string - type: 'null' description: >- Optional extra context, such as approaches already tried, constraints, or the recommendation you are considering. title: Context kind: const: AskOracleAction title: Kind type: string question: description: >- The specific question or dilemma to ask the Oracle about. Use this when you are stuck, uncertain, or need a second opinion. title: Question type: string required: - question - kind title: AskOracleAction type: object BrowserAction: additionalProperties: false description: |- Base class for all browser actions. This base class serves as the parent for all browser-related actions, enabling proper type hierarchy and eliminating the need for union types. properties: kind: const: BrowserAction title: Kind type: string required: - kind title: BrowserAction type: object BrowserClickAction: additionalProperties: false description: Schema for clicking elements. properties: index: description: The index of the element to click (from browser_get_state) minimum: 0 title: Index type: integer kind: const: BrowserClickAction title: Kind type: string new_tab: default: false description: >- Whether to open any resulting navigation in a new tab. Default: False title: New Tab type: boolean required: - index - kind title: BrowserClickAction type: object BrowserCloseTabAction: additionalProperties: false description: Schema for closing browser tabs. properties: kind: const: BrowserCloseTabAction title: Kind type: string tab_id: description: 4 Character Tab ID of the tab to close (from browser_list_tabs) title: Tab Id type: string required: - tab_id - kind title: BrowserCloseTabAction type: object BrowserGetContentAction: additionalProperties: false description: Schema for getting page content in markdown. properties: extract_links: default: false description: 'Whether to include links in the content (default: False)' title: Extract Links type: boolean kind: const: BrowserGetContentAction title: Kind type: string start_from_char: default: 0 description: 'Character index to start from in the page content (default: 0)' minimum: 0 title: Start From Char type: integer required: - kind title: BrowserGetContentAction type: object BrowserGetStateAction: additionalProperties: false description: Schema for getting browser state. properties: include_screenshot: default: false description: 'Whether to include a screenshot of the current page. Default: False' title: Include Screenshot type: boolean kind: const: BrowserGetStateAction title: Kind type: string required: - kind title: BrowserGetStateAction type: object BrowserGetStorageAction: additionalProperties: false description: >- Schema for getting browser storage (cookies, local storage, session storage). properties: kind: const: BrowserGetStorageAction title: Kind type: string required: - kind title: BrowserGetStorageAction type: object BrowserGoBackAction: additionalProperties: false description: Schema for going back in browser history. properties: kind: const: BrowserGoBackAction title: Kind type: string required: - kind title: BrowserGoBackAction type: object BrowserListTabsAction: additionalProperties: false description: Schema for listing browser tabs. properties: kind: const: BrowserListTabsAction title: Kind type: string required: - kind title: BrowserListTabsAction type: object BrowserNavigateAction: additionalProperties: false description: Schema for browser navigation. properties: kind: const: BrowserNavigateAction title: Kind type: string new_tab: default: false description: 'Whether to open in a new tab. Default: False' title: New Tab type: boolean url: description: The URL to navigate to title: Url type: string required: - url - kind title: BrowserNavigateAction type: object BrowserScrollAction: additionalProperties: false description: Schema for scrolling the page. properties: direction: default: down description: 'Direction to scroll. Options: ''up'', ''down''. Default: ''down''' enum: - up - down title: Direction type: string kind: const: BrowserScrollAction title: Kind type: string required: - kind title: BrowserScrollAction type: object BrowserSetStorageAction: additionalProperties: false description: >- Schema for setting browser storage (cookies, local storage, session storage). properties: kind: const: BrowserSetStorageAction title: Kind type: string storage_state: additionalProperties: true description: >- Storage state dictionary containing 'cookies' and 'origins' (from browser_get_storage) title: Storage State type: object required: - storage_state - kind title: BrowserSetStorageAction type: object BrowserStartRecordingAction: additionalProperties: false description: Schema for starting browser session recording. properties: kind: const: BrowserStartRecordingAction title: Kind type: string required: - kind title: BrowserStartRecordingAction type: object BrowserStopRecordingAction: additionalProperties: false description: Schema for stopping browser session recording. properties: kind: const: BrowserStopRecordingAction title: Kind type: string required: - kind title: BrowserStopRecordingAction type: object BrowserSwitchTabAction: additionalProperties: false description: Schema for switching browser tabs. properties: kind: const: BrowserSwitchTabAction title: Kind type: string tab_id: description: 4 Character Tab ID of the tab to switch to (from browser_list_tabs) title: Tab Id type: string required: - tab_id - kind title: BrowserSwitchTabAction type: object BrowserTypeAction: additionalProperties: false description: Schema for typing text into elements. properties: index: description: The index of the input element (from browser_get_state) minimum: 0 title: Index type: integer kind: const: BrowserTypeAction title: Kind type: string text: description: The text to type title: Text type: string required: - index - text - kind title: BrowserTypeAction type: object DelegateAction: additionalProperties: false description: Schema for delegation operations. properties: agent_types: anyOf: - items: type: string type: array - type: 'null' description: >- Optional parameter of `spawn` command. List of agent types for each ID (e.g., ['researcher', 'programmer']). If omitted or blank for an ID, the default general-purpose agent is used. title: Agent Types command: description: 'The commands to run. Allowed options are: `spawn`, `delegate`.' enum: - spawn - delegate title: Command type: string ids: anyOf: - items: type: string type: array - type: 'null' description: >- Required parameter of `spawn` command. List of identifiers to initialize sub-agents with. title: Ids kind: const: DelegateAction title: Kind type: string tasks: anyOf: - additionalProperties: type: string type: object - type: 'null' description: >- Required parameter of `delegate` command. Dictionary mapping sub-agent identifiers to task descriptions. title: Tasks required: - command - kind title: DelegateAction type: object FileEditorAction: additionalProperties: false description: Schema for file editor operations. properties: command: description: >- The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`. enum: - view - create - str_replace - insert - undo_edit title: Command type: string file_text: anyOf: - type: string - type: 'null' description: >- Required parameter of `create` command, with the content of the file to be created. title: File Text insert_line: anyOf: - minimum: 0 type: integer - type: 'null' description: >- Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`. title: Insert Line kind: const: FileEditorAction title: Kind type: string new_str: anyOf: - type: string - type: 'null' description: >- Optional parameter of `str_replace` command containing the new string (if not given, no string will be added). Required parameter of `insert` command containing the string to insert. title: New Str old_str: anyOf: - type: string - type: 'null' description: >- Required parameter of `str_replace` command containing the string in `path` to replace. title: Old Str path: description: Absolute path to file or directory. title: Path type: string view_range: anyOf: - items: type: integer type: array - type: 'null' description: >- Optional parameter of `view` command when `path` points to a file. If none is given, the full file is shown. If provided, the file will be shown in the indicated line number range, e.g. [11, 12] will show lines 11 and 12. Indexing at 1 to start. Setting `[start_line, -1]` shows all lines from `start_line` to the end of the file. title: View Range required: - command - path - kind title: FileEditorAction type: object EditAction: additionalProperties: false description: Schema for edit operation. properties: expected_replacements: default: 1 description: >- Number of replacements expected. Defaults to 1. Use when you want to replace multiple occurrences. The edit will fail if the actual count doesn't match. minimum: 0 title: Expected Replacements type: integer file_path: description: The path to the file to modify. title: File Path type: string kind: const: EditAction title: Kind type: string new_string: description: The text to replace it with. title: New String type: string old_string: description: >- The text to replace. To create a new file, use an empty string. Must match the exact text in the file including whitespace. title: Old String type: string required: - file_path - old_string - new_string - kind title: EditAction type: object ListDirectoryAction: additionalProperties: false description: Schema for list directory operation. properties: dir_path: default: . description: The path to the directory to list. Defaults to current directory. title: Dir Path type: string kind: const: ListDirectoryAction title: Kind type: string recursive: default: false description: Whether to list subdirectories recursively (up to 2 levels). title: Recursive type: boolean required: - kind title: ListDirectoryAction type: object ReadFileAction: additionalProperties: false description: Schema for read file operation. properties: file_path: description: The path to the file to read. title: File Path type: string kind: const: ReadFileAction title: Kind type: string limit: anyOf: - minimum: 1 type: integer - type: 'null' description: >- Optional: Maximum number of lines to read. Use with 'offset' to paginate through large files. title: Limit offset: anyOf: - minimum: 0 type: integer - type: 'null' description: >- Optional: The 0-based line number to start reading from. Use for paginating through large files. title: Offset required: - file_path - kind title: ReadFileAction type: object WriteFileAction: additionalProperties: false description: Schema for write file operation. properties: content: description: The content to write to the file. title: Content type: string file_path: description: The path to the file to write to. title: File Path type: string kind: const: WriteFileAction title: Kind type: string required: - file_path - content - kind title: WriteFileAction type: object GlobAction: additionalProperties: false description: Schema for glob pattern matching operations. properties: kind: const: GlobAction title: Kind type: string path: anyOf: - type: string - type: 'null' description: >- The directory (absolute path) to search in. Defaults to the current working directory. title: Path pattern: description: The glob pattern to match files (e.g., "**/*.js", "src/**/*.ts") title: Pattern type: string required: - pattern - kind title: GlobAction type: object GrepAction: additionalProperties: false description: Schema for grep content search operations. properties: include: anyOf: - type: string - type: 'null' description: >- Optional file pattern to filter which files to search (e.g., "*.js", "*.{ts,tsx}") title: Include kind: const: GrepAction title: Kind type: string path: anyOf: - type: string - type: 'null' description: >- The directory (absolute path) to search in. Defaults to the current working directory. title: Path pattern: description: The regex pattern to search for in file contents title: Pattern type: string required: - pattern - kind title: GrepAction type: object PlanningFileEditorAction: additionalProperties: false description: |- Schema for planning file editor operations. Inherits from FileEditorAction but restricts editing to PLAN.md only. Allows viewing any file but only editing PLAN.md. properties: command: description: >- The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`. enum: - view - create - str_replace - insert - undo_edit title: Command type: string file_text: anyOf: - type: string - type: 'null' description: >- Required parameter of `create` command, with the content of the file to be created. title: File Text insert_line: anyOf: - minimum: 0 type: integer - type: 'null' description: >- Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`. title: Insert Line kind: const: PlanningFileEditorAction title: Kind type: string new_str: anyOf: - type: string - type: 'null' description: >- Optional parameter of `str_replace` command containing the new string (if not given, no string will be added). Required parameter of `insert` command containing the string to insert. title: New Str old_str: anyOf: - type: string - type: 'null' description: >- Required parameter of `str_replace` command containing the string in `path` to replace. title: Old Str path: description: Absolute path to file or directory. title: Path type: string view_range: anyOf: - items: type: integer type: array - type: 'null' description: >- Optional parameter of `view` command when `path` points to a file. If none is given, the full file is shown. If provided, the file will be shown in the indicated line number range, e.g. [11, 12] will show lines 11 and 12. Indexing at 1 to start. Setting `[start_line, -1]` shows all lines from `start_line` to the end of the file. title: View Range required: - command - path - kind title: PlanningFileEditorAction type: object TaskAction: additionalProperties: false description: Schema for launching a sub-agent task. properties: description: anyOf: - type: string - type: 'null' description: A short (3-5 word) description of the task. title: Description kind: const: TaskAction title: Kind type: string prompt: description: The task for the agent to perform. title: Prompt type: string resume: anyOf: - type: string - type: 'null' description: Task ID of the task to resume from. title: Resume subagent_type: default: general-purpose description: The type of specialized agent to use for this task. title: Subagent Type type: string required: - prompt - kind title: TaskAction type: object TaskTrackerAction: additionalProperties: false description: >- An action where the agent writes or updates a task list for task management. properties: command: default: view description: >- The command to execute. `view` shows the current task list. `plan` creates or updates the task list based on provided requirements and progress. Always `view` the current list before making changes. enum: - view - plan title: Command type: string kind: const: TaskTrackerAction title: Kind type: string task_list: description: The full task list. Required parameter of `plan` command. items: $ref: '#/components/schemas/TaskItem' title: Task List type: array required: - kind title: TaskTrackerAction type: object TerminalAction: additionalProperties: false description: Schema for terminal command execution. properties: command: description: >- The shell command to execute. Can be empty string to view additional logs when the previous exit code is `-1`. Can be a special key name when `is_input` is True: `C-c` (Ctrl+C), `C-d` (Ctrl+D/EOF), `C-z` (Ctrl+Z), or any `C-` for Ctrl sequences; navigation keys `UP`, `DOWN`, `LEFT`, `RIGHT`, `HOME`, `END`, `PGUP`, `PGDN`; and `TAB`, `ESC`, `BS` (Backspace), `ENTER`. You can only execute one command at a time. Use the platform-appropriate shell syntax described in the tool description when chaining commands. title: Command type: string is_input: default: false description: >- If True, the command is an input to the running process. If False, the command is executed in the terminal session. Default is False. title: Is Input type: boolean kind: const: TerminalAction title: Kind type: string reset: default: false description: >- If True, reset the terminal by creating a new session. Use this only when the terminal becomes unresponsive. Note that all previously set environment variables and session state will be lost after reset. Cannot be used with is_input=True. title: Reset type: boolean timeout: anyOf: - minimum: 0 type: number - type: 'null' description: >- Optional. Sets a maximum time limit (in seconds) for running the command. If the command takes longer than this limit, you’ll be asked whether to continue or stop it. If you don’t set a value, the command will instead pause and ask for confirmation when it produces no new output for 30 seconds. Use a higher value if the command is expected to take a long time (like installation or testing), or if it has a known fixed duration (like sleep). title: Timeout required: - command - kind title: TerminalAction type: object WorkflowAction: additionalProperties: false description: Schema for running a Python dynamic workflow script. properties: kind: const: WorkflowAction title: Kind type: string max_concurrency: default: 8 description: >- Maximum number of sub-agent tasks to run concurrently. Consider 2–4 for LLM-heavy workflows to avoid hitting API rate limits. maximum: 64 minimum: 1 title: Max Concurrency type: integer name: description: A short name for this workflow run. title: Name type: string script: description: >- Python workflow script to run. It must define `async def main(wf):` and coordinate work only through the provided `wf` object. title: Script type: string required: - name - script - kind title: WorkflowAction type: object ImageContent: properties: cache_prompt: default: false title: Cache Prompt type: boolean image_urls: items: type: string title: Image Urls type: array type: const: image default: image title: Type type: string required: - image_urls title: ImageContent type: object MCPToolObservation: additionalProperties: false description: Observation from MCP tool execution. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: MCPToolObservation title: Kind type: string tool_name: description: Name of the tool that was called title: Tool Name type: string required: - tool_name - kind title: MCPToolObservation type: object ClassifyAndSwitchLLMObservation: additionalProperties: false description: Result of classifying the task and switching the LLM profile. properties: active_model: anyOf: - type: string - type: 'null' description: Model configured by the activated profile, when available. title: Active Model chosen_class: anyOf: - type: string - type: 'null' description: >- Description of the matched class, or None when no class matched and the tool returned an error. title: Chosen Class content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: ClassifyAndSwitchLLMObservation title: Kind type: string model: anyOf: - type: string - type: 'null' description: Name of the LLM profile that was activated. title: Model required: - kind title: ClassifyAndSwitchLLMObservation type: object FinishObservation: additionalProperties: false description: |- Observation returned after finishing a task. The FinishAction itself contains the message sent to the user so no extra fields are needed here. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: FinishObservation title: Kind type: string required: - kind title: FinishObservation type: object InvokeSkillObservation: additionalProperties: false properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: InvokeSkillObservation title: Kind type: string skill_name: description: Name of the skill this observation corresponds to. title: Skill Name type: string required: - skill_name - kind title: InvokeSkillObservation type: object SwitchLLMObservation: additionalProperties: false description: Observation returned after switching this conversation's LLM profile. properties: active_model: anyOf: - type: string - type: 'null' description: Model configured by the activated profile, when available. title: Active Model content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: SwitchLLMObservation title: Kind type: string profile_name: description: Name of the profile that the tool attempted to activate. title: Profile Name type: string reason: anyOf: - type: string - type: 'null' description: Reason the agent gave for attempting this LLM profile switch. title: Reason required: - profile_name - kind title: SwitchLLMObservation type: object ThinkObservation: additionalProperties: false description: |- Observation returned after logging a thought. The ThinkAction itself contains the thought logged so no extra fields are needed here. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: ThinkObservation title: Kind type: string required: - kind title: ThinkObservation type: object VisionInspectObservation: additionalProperties: false description: Observation returned after a vision model inspects an image. properties: answer: anyOf: - type: string - type: 'null' description: Text answer returned by the vision model. title: Answer base_url: anyOf: - type: string - type: 'null' description: Vision-capable LLM endpoint used for inspection. title: Base Url content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array image_index: description: Image index that was inspected. title: Image Index type: integer is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: VisionInspectObservation title: Kind type: string model: anyOf: - type: string - type: 'null' description: Vision-capable model used for inspection. title: Model profile_name: anyOf: - type: string - type: 'null' description: Vision-capable profile used for inspection. title: Profile Name question: description: Question asked of the vision model. title: Question type: string required: - image_index - question - kind title: VisionInspectObservation type: object ClientToolObservation: additionalProperties: false description: |- Observation returned when a client tool is called. The actual execution happens on the client side; the SDK returns this acknowledgment so the agent loop can continue. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: ClientToolObservation title: Kind type: string required: - kind title: ClientToolObservation type: object AskOracleObservation: additionalProperties: false description: Observation returned by the Oracle consultation. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: AskOracleObservation title: Kind type: string required: - kind title: AskOracleObservation type: object BrowserObservation: additionalProperties: false description: Base observation for browser operations. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array full_output_save_dir: anyOf: - type: string - type: 'null' description: Directory where full output files are saved title: Full Output Save Dir is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: BrowserObservation title: Kind type: string screenshot_data: anyOf: - type: string - type: 'null' description: Base64 screenshot data if available title: Screenshot Data required: - kind title: BrowserObservation type: object DelegateObservation: additionalProperties: false description: Observation from delegation operations. properties: command: description: The command that was executed enum: - spawn - delegate title: Command type: string content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: DelegateObservation title: Kind type: string required: - command - kind title: DelegateObservation type: object FileEditorObservation: additionalProperties: false description: A ToolResult that can be rendered as a CLI output. properties: command: description: >- The command that was run: `view`, `create`, `str_replace`, `insert`, or `undo_edit`. enum: - view - create - str_replace - insert - undo_edit title: Command type: string content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: FileEditorObservation title: Kind type: string new_content: anyOf: - type: string - type: 'null' description: The content of the file after the edit. title: New Content old_content: anyOf: - type: string - type: 'null' description: The content of the file before the edit. title: Old Content path: anyOf: - type: string - type: 'null' description: The file path that was edited. title: Path prev_exist: default: true description: Indicates if the file previously existed. If not, it was created. title: Prev Exist type: boolean required: - command - kind title: FileEditorObservation type: object EditObservation: additionalProperties: false description: Observation from editing a file. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array file_path: anyOf: - type: string - type: 'null' description: The file path that was edited. title: File Path is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean is_new_file: default: false description: Whether a new file was created. title: Is New File type: boolean kind: const: EditObservation title: Kind type: string new_content: anyOf: - type: string - type: 'null' description: The content after the edit. title: New Content old_content: anyOf: - type: string - type: 'null' description: The content before the edit. title: Old Content replacements_made: default: 0 description: Number of replacements actually made. title: Replacements Made type: integer required: - kind title: EditObservation type: object ListDirectoryObservation: additionalProperties: false description: Observation from listing a directory. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array dir_path: anyOf: - type: string - type: 'null' description: The directory path that was listed. title: Dir Path entries: description: List of files and directories found. items: $ref: '#/components/schemas/FileEntry' title: Entries type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean is_truncated: default: false description: Whether the listing was truncated due to too many entries. title: Is Truncated type: boolean kind: const: ListDirectoryObservation title: Kind type: string total_count: default: 0 description: Total number of entries found. title: Total Count type: integer required: - kind title: ListDirectoryObservation type: object ReadFileObservation: additionalProperties: false description: Observation from reading a file. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array file_content: default: '' description: The content read from the file. title: File Content type: string file_path: description: The file path that was read. title: File Path type: string is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean is_truncated: default: false description: Whether the content was truncated due to size limits. title: Is Truncated type: boolean kind: const: ReadFileObservation title: Kind type: string lines_shown: anyOf: - maxItems: 2 minItems: 2 prefixItems: - type: integer - type: integer type: array - type: 'null' description: If truncated, the range of lines shown (start, end) - 1-indexed. title: Lines Shown total_lines: anyOf: - type: integer - type: 'null' description: Total number of lines in the file. title: Total Lines required: - file_path - kind title: ReadFileObservation type: object WriteFileObservation: additionalProperties: false description: Observation from writing a file. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array file_path: anyOf: - type: string - type: 'null' description: The file path that was written. title: File Path is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean is_new_file: default: false description: Whether a new file was created. title: Is New File type: boolean kind: const: WriteFileObservation title: Kind type: string new_content: anyOf: - type: string - type: 'null' description: The new content written to the file. title: New Content old_content: anyOf: - type: string - type: 'null' description: The previous content of the file (if it existed). title: Old Content required: - kind title: WriteFileObservation type: object GlobObservation: additionalProperties: false description: Observation from glob pattern matching operations. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array files: description: List of matching file paths sorted by modification time items: type: string title: Files type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: GlobObservation title: Kind type: string pattern: description: The glob pattern that was used title: Pattern type: string search_path: description: The directory that was searched title: Search Path type: string truncated: default: false description: Whether results were truncated to 100 files title: Truncated type: boolean required: - files - pattern - search_path - kind title: GlobObservation type: object GrepObservation: additionalProperties: false description: Observation from grep content search operations. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array include_pattern: anyOf: - type: string - type: 'null' description: The file pattern filter that was used title: Include Pattern is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: GrepObservation title: Kind type: string matches: description: List of file paths containing the pattern items: type: string title: Matches type: array pattern: description: The regex pattern that was used title: Pattern type: string search_path: description: The directory that was searched title: Search Path type: string truncated: default: false description: Whether results were truncated to 100 files title: Truncated type: boolean required: - matches - pattern - search_path - kind title: GrepObservation type: object PlanningFileEditorObservation: additionalProperties: false description: >- Observation from planning file editor operations. Inherits from FileEditorObservation - same structure, just different type. properties: command: description: >- The command that was run: `view`, `create`, `str_replace`, `insert`, or `undo_edit`. enum: - view - create - str_replace - insert - undo_edit title: Command type: string content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: PlanningFileEditorObservation title: Kind type: string new_content: anyOf: - type: string - type: 'null' description: The content of the file after the edit. title: New Content old_content: anyOf: - type: string - type: 'null' description: The content of the file before the edit. title: Old Content path: anyOf: - type: string - type: 'null' description: The file path that was edited. title: Path prev_exist: default: true description: Indicates if the file previously existed. If not, it was created. title: Prev Exist type: boolean required: - command - kind title: PlanningFileEditorObservation type: object TaskObservation: additionalProperties: false description: Observation from a task execution. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: TaskObservation title: Kind type: string status: description: The status of the task. title: Status type: string subagent: description: The subagent of the task. title: Subagent type: string task_id: description: The unique identifier of the task. title: Task Id type: string required: - task_id - subagent - status - kind title: TaskObservation type: object TaskTrackerObservation: additionalProperties: false description: This data class represents the result of a task tracking operation. properties: command: description: 'The command that was executed: "view" or "plan".' enum: - view - plan title: Command type: string content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: TaskTrackerObservation title: Kind type: string task_list: description: The current task list items: $ref: '#/components/schemas/TaskItem' title: Task List type: array required: - command - kind title: TaskTrackerObservation type: object TerminalObservation: additionalProperties: false description: A ToolResult that can be rendered as a CLI output. properties: command: anyOf: - type: string - type: 'null' description: >- The shell command that was executed. Can be empty string if the observation is from a previous command that hit soft timeout and is not yet finished. title: Command content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array exit_code: anyOf: - type: integer - type: 'null' description: >- The exit code of the command. -1 indicates the process hit the soft timeout and is not yet finished. title: Exit Code full_output_save_dir: anyOf: - type: string - type: 'null' description: Directory where full output files are saved title: Full Output Save Dir is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: TerminalObservation title: Kind type: string metadata: $ref: '#/components/schemas/CmdOutputMetadata' description: Additional metadata captured from PS1 after command execution. timeout: default: false description: Whether the command execution timed out. title: Timeout type: boolean required: - command - kind title: TerminalObservation type: object WorkflowObservation: additionalProperties: false description: Observation from a dynamic workflow run. properties: content: description: >- Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field. items: anyOf: - $ref: '#/components/schemas/TextContent' - $ref: '#/components/schemas/ImageContent' title: Content type: array is_error: default: false description: Whether the observation indicates an error title: Is Error type: boolean kind: const: WorkflowObservation title: Kind type: string name: description: The workflow name that was executed. title: Name type: string status: description: The workflow execution status. enum: - completed - error title: Status type: string required: - name - status - kind title: WorkflowObservation type: object MCPToolDefinition: description: MCP Tool that wraps an MCP client and provides tool functionality. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: MCPToolDefinition title: Kind type: string mcp_tool: $ref: '#/components/schemas/mcp__types__Tool' description: The MCP tool definition. meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - mcp_tool - kind - title title: MCPToolDefinition type: object ClassifyAndSwitchLLMTool: description: Tool that classifies the task and switches to a meta-profile's LLM. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: ClassifyAndSwitchLLMTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: ClassifyAndSwitchLLMTool type: object FinishTool: description: Tool for signaling the completion of a task or conversation. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: FinishTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: FinishTool type: object InvokeSkillTool: description: Built-in tool for explicit invocation of progressive-disclosure skills. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: InvokeSkillTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: InvokeSkillTool type: object SwitchLLMTool: description: Tool for switching a conversation to a saved LLM profile. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: SwitchLLMTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: SwitchLLMTool type: object ThinkTool: description: Tool for logging thoughts without making changes. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: ThinkTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: ThinkTool type: object VisionInspectTool: description: Tool for one-off image inspection through a saved vision profile. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: VisionInspectTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: VisionInspectTool type: object ClientTool: description: |- A tool whose execution is deferred to the external client. Created from a :class:`ClientToolSpec` at conversation start. The agent sees it as a normal tool and can call it; the ActionEvent is emitted over WebSocket for the client to handle. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' client_tool_name: description: Per-instance tool name from the ClientToolSpec. title: Client Tool Name type: string description: title: Description type: string input_schema: additionalProperties: true description: >- The original JSON Schema for the tool's parameters, as provided by the client. Used verbatim when exporting the tool to the LLM so client-defined constraints (enum, nested objects, bounds, additionalProperties, ...) are preserved. title: Input Schema type: object kind: const: ClientTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - client_tool_name - input_schema - kind - title title: ClientTool type: object AskOracleTool: description: Tool for consulting the Oracle (a saved LLM profile named "oracle"). properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: AskOracleTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: AskOracleTool type: object BrowserClickTool: description: Tool for clicking browser elements. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserClickTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserClickTool type: object BrowserCloseTabTool: description: Tool for closing browser tabs. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserCloseTabTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserCloseTabTool type: object BrowserGetContentTool: description: Tool for getting page content in markdown. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserGetContentTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserGetContentTool type: object BrowserGetStateTool: description: Tool for getting browser state. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserGetStateTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserGetStateTool type: object BrowserGetStorageTool: description: Tool for getting browser storage. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserGetStorageTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserGetStorageTool type: object BrowserGoBackTool: description: Tool for going back in browser history. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserGoBackTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserGoBackTool type: object BrowserListTabsTool: description: Tool for listing browser tabs. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserListTabsTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserListTabsTool type: object BrowserNavigateTool: description: Tool for browser navigation. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserNavigateTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserNavigateTool type: object BrowserScrollTool: description: Tool for scrolling the browser page. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserScrollTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserScrollTool type: object BrowserSetStorageTool: description: Tool for setting browser storage. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserSetStorageTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserSetStorageTool type: object BrowserStartRecordingTool: description: Tool for starting browser session recording. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserStartRecordingTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserStartRecordingTool type: object BrowserStopRecordingTool: description: Tool for stopping browser session recording. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserStopRecordingTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserStopRecordingTool type: object BrowserSwitchTabTool: description: Tool for switching browser tabs. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserSwitchTabTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserSwitchTabTool type: object BrowserToolSet: description: |- A set of all browser tools. This tool set includes all available browser-related tools for interacting with web pages. The toolset automatically checks for Chromium availability when created and automatically installs it if missing. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserToolSet title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserToolSet type: object BrowserTypeTool: description: Tool for typing text into browser elements. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: BrowserTypeTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: BrowserTypeTool type: object FileEditorTool: description: >- A ToolDefinition subclass that automatically initializes a FileEditorExecutor. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: FileEditorTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: FileEditorTool type: object EditTool: description: Tool for editing files via find/replace. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: EditTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: EditTool type: object ListDirectoryTool: description: Tool for listing directory contents with metadata. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: ListDirectoryTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: ListDirectoryTool type: object ReadFileTool: description: Tool for reading file contents with pagination support. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: ReadFileTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: ReadFileTool type: object WriteFileTool: description: Tool for writing complete file contents. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: WriteFileTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: WriteFileTool type: object GlobTool: description: A ToolDefinition subclass that automatically initializes a GlobExecutor. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: GlobTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: GlobTool type: object GrepTool: description: A ToolDefinition subclass that automatically initializes a GrepExecutor. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: GrepTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: GrepTool type: object PlanningFileEditorTool: description: A planning file editor tool with read-all, edit-PLAN.md-only access. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: PlanningFileEditorTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: PlanningFileEditorTool type: object TaskTool: description: Tool for launching (blocking) sub-agent tasks. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: TaskTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: TaskTool type: object TaskToolSet: description: |- Task tool set. Creates the Task tool backed by a shared TaskManager. Usage: from openhands.tools.task import TaskToolSet agent = Agent( llm=llm, tools=[ Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name), Tool(name=TaskToolSet.name), ], ) properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: TaskToolSet title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: TaskToolSet type: object TaskTrackerTool: description: >- A ToolDefinition subclass that automatically initializes a TaskTrackerExecutor. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: TaskTrackerTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: TaskTrackerTool type: object TerminalTool: description: >- A ToolDefinition subclass that automatically initializes a TerminalExecutor with auto-detection. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: TerminalTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: TerminalTool type: object WorkflowTool: description: |- Low-level tool for explicit executor injection. Prefer ``WorkflowToolSet`` for standard SDK auto-create usage. Use ``WorkflowTool`` when you need to inject a custom executor (e.g., in tests or extensions). properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: WorkflowTool title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: WorkflowTool type: object WorkflowToolSet: description: Tool set that creates the dynamic workflow tool. properties: action_type: title: Action Type type: string annotations: anyOf: - $ref: '#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations' - type: 'null' description: title: Description type: string kind: const: WorkflowToolSet title: Kind type: string meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta observation_type: anyOf: - type: string - type: 'null' title: Observation Type title: readOnly: true title: Title type: string required: - description - action_type - kind - title title: WorkflowToolSet type: object TaskItem: properties: notes: default: '' description: Additional details or notes about the task. title: Notes type: string status: default: todo description: >- The current status of the task. One of 'todo', 'in_progress', or 'done'. enum: - todo - in_progress - done title: Status type: string title: description: A brief title for the task. title: Title type: string required: - title title: TaskItem type: object FileEntry: description: Information about a file or directory. properties: is_directory: description: Whether this entry is a directory title: Is Directory type: boolean modified_time: description: Last modified timestamp format: date-time title: Modified Time type: string name: description: Name of the file or directory title: Name type: string path: description: Absolute path to the file or directory title: Path type: string size: description: Size of the file in bytes (0 for directories) title: Size type: integer required: - name - path - is_directory - size - modified_time title: FileEntry type: object CmdOutputMetadata: description: Additional metadata captured from PS1 properties: exit_code: default: -1 description: The exit code of the last executed command. title: Exit Code type: integer hostname: anyOf: - type: string - type: 'null' description: The hostname of the machine. title: Hostname pid: default: -1 description: The process ID of the last executed command. title: Pid type: integer prefix: default: '' description: Prefix to add to command output title: Prefix type: string py_interpreter_path: anyOf: - type: string - type: 'null' description: The path to the current Python interpreter, if any. title: Py Interpreter Path suffix: default: '' description: Suffix to add to command output title: Suffix type: string username: anyOf: - type: string - type: 'null' description: The username of the current user. title: Username working_dir: anyOf: - type: string - type: 'null' description: The current working directory. title: Working Dir title: CmdOutputMetadata 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 mcp__types__Tool: additionalProperties: true description: Definition for a tool the client can call. properties: _meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta annotations: anyOf: - $ref: '#/components/schemas/mcp__types__ToolAnnotations' - type: 'null' description: anyOf: - type: string - type: 'null' title: Description execution: anyOf: - $ref: '#/components/schemas/ToolExecution' - type: 'null' icons: anyOf: - items: $ref: '#/components/schemas/Icon' type: array - type: 'null' title: Icons inputSchema: additionalProperties: true title: Inputschema type: object name: title: Name type: string outputSchema: anyOf: - additionalProperties: true type: object - type: 'null' title: Outputschema title: anyOf: - type: string - type: 'null' title: Title required: - name - inputSchema title: Tool type: object mcp__types__ToolAnnotations: additionalProperties: true description: |- Additional properties describing a Tool to clients. NOTE: all properties in ToolAnnotations are **hints**. They are not guaranteed to provide a faithful description of tool behavior (including descriptive properties like `title`). Clients should never make tool use decisions based on ToolAnnotations received from untrusted servers. properties: destructiveHint: anyOf: - type: boolean - type: 'null' title: Destructivehint idempotentHint: anyOf: - type: boolean - type: 'null' title: Idempotenthint openWorldHint: anyOf: - type: boolean - type: 'null' title: Openworldhint readOnlyHint: anyOf: - type: boolean - type: 'null' title: Readonlyhint title: anyOf: - type: string - type: 'null' title: Title title: ToolAnnotations type: object ToolExecution: additionalProperties: true description: Execution-related properties for a tool. properties: taskSupport: anyOf: - enum: - forbidden - optional - required type: string - type: 'null' title: Tasksupport title: ToolExecution type: object Icon: additionalProperties: true description: An icon for display in user interfaces. properties: mimeType: anyOf: - type: string - type: 'null' title: Mimetype sizes: anyOf: - items: type: string type: array - type: 'null' title: Sizes src: title: Src type: string required: - src title: Icon 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.