diff --git a/openapi/agent-sdk.json b/openapi/agent-sdk.json index b1e65f8f..88edf87c 100644 --- a/openapi/agent-sdk.json +++ b/openapi/agent-sdk.json @@ -140,6 +140,40 @@ "title": "Sort order for events", "default": "TIMESTAMP" } + }, + { + "name": "timestamp__gte", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Filter: event timestamp >= this datetime" + } + }, + { + "name": "timestamp__lt", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Filter: event timestamp < this datetime" + } } ], "responses": { @@ -203,6 +237,40 @@ ], "title": "Optional filter by event kind/type (e.g., ActionEvent, MessageEvent)" } + }, + { + "name": "timestamp__gte", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Filter: event timestamp >= this datetime" + } + }, + { + "name": "timestamp__lt", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Filter: event timestamp < this datetime" + } } ], "responses": { @@ -562,13 +630,13 @@ "schema": { "anyOf": [ { - "$ref": "#/components/schemas/AgentExecutionStatus" + "$ref": "#/components/schemas/ConversationExecutionStatus" }, { "type": "null" } ], - "title": "Optional filter by agent execution status" + "title": "Optional filter by conversation execution status" } }, { @@ -622,13 +690,13 @@ "schema": { "anyOf": [ { - "$ref": "#/components/schemas/AgentExecutionStatus" + "$ref": "#/components/schemas/ConversationExecutionStatus" }, { "type": "null" } ], - "title": "Optional filter by agent execution status" + "title": "Optional filter by conversation execution status" } } ], @@ -880,7 +948,6 @@ "llm": { "model": "your-model-provider/your-model-name", "api_key": "**********", - "reasoning_effort": "high", "usage_id": "your-llm-service" }, "tools": [ @@ -2271,7 +2338,8 @@ "required": [ "llm" ], - "title": "Agent" + "title": "Agent", + "description": "Main agent implementation for OpenHands.\n\nThe Agent class provides the core functionality for running AI agents that can\ninteract with tools, process messages, and execute actions. It inherits from\nAgentBase and implements the agent execution logic.\n\nExample:\n >>> from openhands.sdk import LLM, Agent, Tool\n >>> llm = LLM(model=\"claude-sonnet-4-20250514\", api_key=SecretStr(\"key\"))\n >>> tools = [Tool(name=\"BashTool\"), Tool(name=\"FileEditorTool\")]\n >>> agent = Agent(llm=llm, tools=tools)" }, "AgentContext-Output": { "properties": { @@ -2306,6 +2374,12 @@ ], "title": "User Message Suffix", "description": "Optional suffix to append to the user's message." + }, + "load_user_skills": { + "type": "boolean", + "title": "Load User Skills", + "description": "Whether to automatically load user skills from ~/.openhands/skills/ and ~/.openhands/microagents/ (for backward compatibility). ", + "default": false } }, "type": "object", @@ -2366,20 +2440,6 @@ "title": "AgentErrorEvent", "description": "Error triggered by the agent.\n\nNote: This event should not contain model \"thought\" or \"reasoning_content\". It\nrepresents an error produced by the agent/scaffold, not model output." }, - "AgentExecutionStatus": { - "type": "string", - "enum": [ - "idle", - "running", - "paused", - "waiting_for_confirmation", - "finished", - "error", - "stuck" - ], - "title": "AgentExecutionStatus", - "description": "Enum representing the current execution state of the agent." - }, "AlwaysConfirm": { "properties": { "kind": { @@ -2574,6 +2634,20 @@ ], "title": "Body_upload_file_api_file_upload__path__post" }, + "BrowserAction": { + "properties": { + "kind": { + "type": "string", + "const": "BrowserAction", + "title": "Kind", + "default": "BrowserAction" + } + }, + "additionalProperties": false, + "type": "object", + "title": "BrowserAction", + "description": "Base class for all browser actions.\n\nThis base class serves as the parent for all browser-related actions,\nenabling proper type hierarchy and eliminating the need for union types." + }, "BrowserClickAction": { "properties": { "kind": { @@ -2736,22 +2810,26 @@ "title": "Kind", "default": "BrowserObservation" }, - "output": { - "type": "string", - "title": "Output", - "description": "The output message from the browser operation" + "content": { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TextContent" + }, + { + "$ref": "#/components/schemas/ImageContent" + } + ] + }, + "type": "array", + "title": "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." }, - "error": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Error", - "description": "Error message if any" + "is_error": { + "type": "boolean", + "title": "Is Error", + "description": "Whether the observation indicates an error", + "default": false }, "screenshot_data": { "anyOf": [ @@ -2768,9 +2846,6 @@ }, "additionalProperties": false, "type": "object", - "required": [ - "output" - ], "title": "BrowserObservation", "description": "Base observation for browser operations." }, @@ -3189,6 +3264,20 @@ "title": "ConfirmationResponseRequest", "description": "Payload to accept or reject a pending action." }, + "ConversationExecutionStatus": { + "type": "string", + "enum": [ + "idle", + "running", + "paused", + "waiting_for_confirmation", + "finished", + "error", + "stuck" + ], + "title": "ConversationExecutionStatus", + "description": "Enum representing the current execution state of the conversation." + }, "ConversationInfo": { "properties": { "id": { @@ -3230,8 +3319,8 @@ "description": "Whether to enable stuck detection for the agent.", "default": true }, - "agent_status": { - "$ref": "#/components/schemas/AgentExecutionStatus", + "execution_status": { + "$ref": "#/components/schemas/ConversationExecutionStatus", "default": "idle" }, "confirmation_policy": { @@ -3578,10 +3667,26 @@ "title": "Kind", "default": "ExecuteBashObservation" }, - "output": { - "type": "string", - "title": "Output", - "description": "The raw output from the tool." + "content": { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TextContent" + }, + { + "$ref": "#/components/schemas/ImageContent" + } + ] + }, + "type": "array", + "title": "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." + }, + "is_error": { + "type": "boolean", + "title": "Is Error", + "description": "Whether the observation indicates an error", + "default": false }, "command": { "anyOf": [ @@ -3607,12 +3712,6 @@ "title": "Exit Code", "description": "The exit code of the command. -1 indicates the process hit the soft timeout and is not yet finished." }, - "error": { - "type": "boolean", - "title": "Error", - "description": "Whether there was an error during command execution.", - "default": false - }, "timeout": { "type": "boolean", "title": "Timeout", @@ -3627,7 +3726,7 @@ "additionalProperties": false, "type": "object", "required": [ - "output" + "command" ], "title": "ExecuteBashObservation", "description": "A ToolResult that can be rendered as a CLI output." @@ -3771,6 +3870,27 @@ "title": "Kind", "default": "FileEditorObservation" }, + "content": { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TextContent" + }, + { + "$ref": "#/components/schemas/ImageContent" + } + ] + }, + "type": "array", + "title": "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." + }, + "is_error": { + "type": "boolean", + "title": "Is Error", + "description": "Whether the observation indicates an error", + "default": false + }, "command": { "type": "string", "enum": [ @@ -3781,13 +3901,7 @@ "undo_edit" ], "title": "Command", - "description": "The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`." - }, - "output": { - "type": "string", - "title": "Output", - "description": "The output message from the tool for the LLM to see.", - "default": "" + "description": "The command that was run: `view`, `create`, `str_replace`, `insert`, or `undo_edit`." }, "path": { "anyOf": [ @@ -3830,18 +3944,6 @@ ], "title": "New Content", "description": "The content of the file after the edit." - }, - "error": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Error", - "description": "Error message if any." } }, "additionalProperties": false, @@ -3881,18 +3983,32 @@ "title": "Kind", "default": "FinishObservation" }, - "message": { - "type": "string", - "title": "Message", - "description": "Final message sent to the user." + "content": { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TextContent" + }, + { + "$ref": "#/components/schemas/ImageContent" + } + ] + }, + "type": "array", + "title": "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." + }, + "is_error": { + "type": "boolean", + "title": "Is Error", + "description": "Whether the observation indicates an error", + "default": false } }, "additionalProperties": false, "type": "object", - "required": [ - "message" - ], - "title": "FinishObservation" + "title": "FinishObservation", + "description": "Observation returned after finishing a task.\nThe FinishAction itself contains the message sent to the user so no\nextra fields are needed here." }, "GenerateTitleRequest": { "properties": { @@ -4089,6 +4205,9 @@ }, "api_key": { "anyOf": [ + { + "type": "string" + }, { "type": "string", "format": "password", @@ -4127,6 +4246,9 @@ }, "aws_access_key_id": { "anyOf": [ + { + "type": "string" + }, { "type": "string", "format": "password", @@ -4140,6 +4262,9 @@ }, "aws_secret_access_key": { "anyOf": [ + { + "type": "string" + }, { "type": "string", "format": "password", @@ -4292,6 +4417,21 @@ "title": "Max Output Tokens", "description": "The maximum number of output tokens. This is sent to the LLM." }, + "extra_headers": { + "anyOf": [ + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Extra Headers", + "description": "Optional HTTP headers to forward to LiteLLM requests." + }, "input_cost_per_token": { "anyOf": [ { @@ -4417,7 +4557,25 @@ } ], "title": "Reasoning Effort", - "description": "The effort to put into reasoning. This is a string that can be one of 'low', 'medium', 'high', or 'none'. Can apply to all reasoning models." + "description": "The effort to put into reasoning. This is a string that can be one of 'low', 'medium', 'high', or 'none'. Can apply to all reasoning models.", + "default": "high" + }, + "reasoning_summary": { + "anyOf": [ + { + "type": "string", + "enum": [ + "auto", + "concise", + "detailed" + ] + }, + { + "type": "null" + } + ], + "title": "Reasoning Summary", + "description": "The level of detail for reasoning summaries. This is a string that can be one of 'auto', 'concise', or 'detailed'. Requires verified OpenAI organization. Only sent when explicitly set." }, "enable_encrypted_reasoning": { "type": "boolean", @@ -4474,11 +4632,11 @@ "description": "Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking.", "default": "default" }, - "metadata": { + "litellm_extra_body": { "additionalProperties": true, "type": "object", - "title": "Metadata", - "description": "Additional metadata for the LLM instance. Example structure: {'trace_version': '1.0.0', 'tags': ['model:gpt-4', 'agent:my-agent'], 'session_id': 'session-123', 'trace_user_id': 'user-456'}" + "title": "Litellm Extra Body", + "description": "Additional key-value pairs to pass to litellm's extra_body parameter. This is useful for custom inference clusters that need additional metadata for logging, tracking, or routing purposes. Example structure: {'trace_version': '1.0.0', 'tags': ['model:gpt-4', 'agent:my-agent'], 'session_id': 'session-123', 'trace_user_id': 'user-456'}" }, "OVERRIDE_ON_SERIALIZE": { "items": { @@ -4496,7 +4654,7 @@ "additionalProperties": false, "type": "object", "title": "LLM", - "description": "Refactored LLM: simple `completion()`, centralized Telemetry, tiny helpers." + "description": "Language model interface for OpenHands agents.\n\nThe LLM class provides a unified interface for interacting with various\nlanguage models through the litellm library. It handles model configuration,\nAPI authentication,\nretry logic, and tool calling capabilities.\n\nExample:\n >>> from openhands.sdk import LLM\n >>> from pydantic import SecretStr\n >>> llm = LLM(\n ... model=\"claude-sonnet-4-20250514\",\n ... api_key=SecretStr(\"your-api-key\"),\n ... usage_id=\"my-agent\"\n ... )\n >>> # Use with agent or conversation" }, "LLMSummarizingCondenser": { "properties": { @@ -4547,7 +4705,7 @@ "working_dir" ], "title": "LocalWorkspace", - "description": "Mixin providing local workspace operations." + "description": "Local workspace implementation that operates on the host filesystem.\n\nLocalWorkspace provides direct access to the local filesystem and command execution\nenvironment. It's suitable for development and testing scenarios where the agent\nshould operate directly on the host system.\n\nExample:\n >>> workspace = LocalWorkspace(working_dir=\"/path/to/project\")\n >>> with workspace:\n ... result = workspace.execute_command(\"ls -la\")\n ... content = workspace.read_file(\"README.md\")" }, "LookupSecret": { "properties": { @@ -4629,12 +4787,12 @@ }, "type": "array", "title": "Content", - "description": "Content returned from the MCP tool converted to LLM Ready TextContent or ImageContent" + "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." }, "is_error": { "type": "boolean", "title": "Is Error", - "description": "Whether the call resulted in an error", + "description": "Whether the observation indicates an error", "default": false }, "tool_name": { @@ -5271,7 +5429,7 @@ "host" ], "title": "RemoteWorkspace", - "description": "Remote Workspace Implementation." + "description": "Remote workspace implementation that connects to an OpenHands agent server.\n\nRemoteWorkspace provides access to a sandboxed environment running on a remote\nOpenHands agent server. This is the recommended approach for production deployments\nas it provides better isolation and security.\n\nExample:\n >>> workspace = RemoteWorkspace(\n ... host=\"https://agent-server.example.com\",\n ... working_dir=\"/workspace\"\n ... )\n >>> with workspace:\n ... result = workspace.execute_command(\"ls -la\")\n ... content = workspace.read_file(\"README.md\")" }, "ResponseLatency": { "properties": { @@ -5808,16 +5966,34 @@ "default": "TaskTrackerObservation" }, "content": { - "type": "string", + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TextContent" + }, + { + "$ref": "#/components/schemas/ImageContent" + } + ] + }, + "type": "array", "title": "Content", - "description": "The formatted task list or status message", - "default": "" + "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." + }, + "is_error": { + "type": "boolean", + "title": "Is Error", + "description": "Whether the observation indicates an error", + "default": false }, "command": { "type": "string", + "enum": [ + "view", + "plan" + ], "title": "Command", - "description": "The command that was executed", - "default": "" + "description": "The command that was executed: \"view\" or \"plan\"." }, "task_list": { "items": { @@ -5830,6 +6006,9 @@ }, "additionalProperties": false, "type": "object", + "required": [ + "command" + ], "title": "TaskTrackerObservation", "description": "This data class represents the result of a task tracking operation." }, @@ -5912,16 +6091,31 @@ "default": "ThinkObservation" }, "content": { - "type": "string", + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TextContent" + }, + { + "$ref": "#/components/schemas/ImageContent" + } + ] + }, + "type": "array", "title": "Content", - "description": "Confirmation message.", - "default": "Your thought has been logged." + "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." + }, + "is_error": { + "type": "boolean", + "title": "Is Error", + "description": "Whether the observation indicates an error", + "default": false } }, "additionalProperties": false, "type": "object", "title": "ThinkObservation", - "description": "Observation returned after logging a thought." + "description": "Observation returned after logging a thought.\nThe ThinkAction itself contains the thought logged so no extra\nfields are needed here." }, "ThinkingBlock": { "properties": { @@ -6293,6 +6487,9 @@ { "$ref": "#/components/schemas/ThinkAction" }, + { + "$ref": "#/components/schemas/BrowserAction" + }, { "$ref": "#/components/schemas/BrowserClickAction" }, @@ -6339,6 +6536,7 @@ "openhands__sdk__mcp__definition__MCPToolAction-Output__1": "#/components/schemas/MCPToolAction", "openhands__sdk__tool__builtins__finish__FinishAction-Output__1": "#/components/schemas/FinishAction", "openhands__sdk__tool__builtins__think__ThinkAction-Output__1": "#/components/schemas/ThinkAction", + "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",